NearQuery (Spring Data MongoDB 3.2.0-RC1 API)

java.lang.Object
- org.springframework.data.mongodb.core.query.NearQuery

public final class NearQuery
extends Object

Builder class to build near-queries.
MongoDB $geoNear operator allows usage of a GeoJSON Point or legacy coordinate pair. Though syntactically different, there's no difference between near: [-73.99171, 40.738868] and

near: { type:
 "Point", coordinates: [-73.99171, 40.738868] }

for the MongoDB server

Please note that there is a huge difference in the distance calculation. Using the legacy format (for near) operates upon Radians on an Earth like sphere, whereas the GeoJSON format uses Meters. The actual type within the document is of no concern at this point.
To avoid a serious headache make sure to set the Metric to the desired unit of measure which ensures the distance to be calculated correctly.

In other words:
Assume you've got 5 Documents like the ones below

     
 {
     "_id" : ObjectId("5c10f3735d38908db52796a5"),
     "name" : "Penn Station",
     "location" : { "type" : "Point", "coordinates" : [  -73.99408, 40.75057 ] }
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796a6"),
     "name" : "10gen Office",
     "location" : { "type" : "Point", "coordinates" : [ -73.99171, 40.738868 ] }
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796a9"),
     "name" : "City Bakery ",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796aa"),
     "name" : "Splash Bar",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796ab"),
     "name" : "Momofuku Milk Bar",
     "location" : { "type" : "Point", "coordinates" : [ -73.985839, 40.731698 ] }
 }

Fetching all Documents within a 400 Meter radius from [-73.99171, 40.738868] would look like this using GeoJSON:

     
 {
     $geoNear: {
         maxDistance: 400,
         num: 10,
         near: { type: "Point", coordinates: [-73.99171, 40.738868] },
         spherical:true,
         key: "location",
         distanceField: "distance"
     }
 }

resulting in the following 3 Documents.

     
 {
     "_id" : ObjectId("5c10f3735d38908db52796a6"),
     "name" : "10gen Office",
     "location" : { "type" : "Point", "coordinates" : [ -73.99171, 40.738868 ] }
     "distance" : 0.0 // Meters
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796a9"),
     "name" : "City Bakery ",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
     "distance" : 69.3582262492474 // Meters
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796aa"),
     "name" : "Splash Bar",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
     "distance" : 69.3582262492474 // Meters
 }

Using legacy coordinate pairs one operates upon radians as discussed before. Assume we use Metrics.KILOMETERS when constructing the geoNear command. The Metric will make sure the distance multiplier is set correctly, so the command is rendered like

     
 {
     $geoNear: {
         maxDistance: 0.0000627142377, // 400 Meters
         distanceMultiplier: 6378.137,
         num: 10,
         near: [-73.99171, 40.738868],
         spherical:true,
         key: "location",
         distanceField: "distance"
     }
 }

Please note the calculated distance now uses Kilometers instead of Meters as unit of measure, so we need to take it times 1000 to match up to Meters as in the GeoJSON variant.
Still as we've been requesting the Distance in Metrics.KILOMETERS the Distance.getValue() reflects exactly this.

     
 {
     "_id" : ObjectId("5c10f3735d38908db52796a6"),
     "name" : "10gen Office",
     "location" : { "type" : "Point", "coordinates" : [ -73.99171, 40.738868 ] }
     "distance" : 0.0 // Kilometers
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796a9"),
     "name" : "City Bakery ",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
     "distance" : 0.0693586286032982 // Kilometers
 }
 {
     "_id" : ObjectId("5c10f3735d38908db52796aa"),
     "name" : "Splash Bar",
     "location" : { "type" : "Point", "coordinates" : [ -73.992491, 40.738673 ] }
     "distance" : 0.0693586286032982 // Kilometers
 }

Author:: Oliver Gierke, Thomas Darimont, Christoph Strobl, Mark Paluch

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`NearQuery`	`distanceMultiplier(double distanceMultiplier)` Configures a `CustomMetric` with the given multiplier.
`Collation`	`getCollation()` Get the `Collation` to use along with the `query(Query)`.
`Distance`	`getMaxDistance()` Returns the maximum `Distance`.
`Metric`	`getMetric()` Returns the `Metric` underlying the actual query.
`Distance`	`getMinDistance()` Returns the maximum `Distance`.
`Long`	`getSkip()`
`NearQuery`	`in(Metric metric)` Will cause the results' distances being returned in the given metric.
`NearQuery`	`inKilometers()` Will cause the results' distances being returned in kilometers.
`NearQuery`	`inMiles()` Will cause the results' distances being returned in miles.
`boolean`	`isSpherical()` Returns whether spharical values will be returned.
`NearQuery`	`limit(long limit)` Configures the maximum number of results to return.
`NearQuery`	`maxDistance(Distance distance)` Sets the maximum distance to the given `Distance`.
`NearQuery`	`maxDistance(double maxDistance)` Sets the max distance results shall have from the configured origin.
`NearQuery`	`maxDistance(double maxDistance, Metric metric)` Sets the maximum distance supplied in a given metric.
`NearQuery`	`minDistance(Distance distance)` Sets the minimum distance to the given `Distance`.
`NearQuery`	`minDistance(double minDistance)` Sets the minimum distance results shall have from the configured origin.
`NearQuery`	`minDistance(double minDistance, Metric metric)` Sets the minimum distance supplied in a given metric.
`static NearQuery`	`near(double x, double y)` Creates a new `NearQuery` starting near the given coordinates.
`static NearQuery`	`near(double x, double y, Metric metric)` Creates a new `NearQuery` starting at the given coordinates using the given `Metric` to adapt given values to further configuration.
`static NearQuery`	`near(Point point)` Creates a new `NearQuery` starting at the given `Point`.
`static NearQuery`	`near(Point point, Metric metric)` Creates a `NearQuery` starting near the given `Point` using the given `Metric` to adapt given values to further configuration.
`NearQuery`	`num(long num)` Deprecated. since 2.2. Please use `limit(long)` instead.
`NearQuery`	`query(Query query)` Adds an actual query to the `NearQuery` to restrict the objects considered for the actual near operation.
`NearQuery`	`skip(long skip)` Configures the number of results to skip.
`NearQuery`	`spherical(boolean spherical)` Configures whether to return spherical values for the actual distance.
`org.bson.Document`	`toDocument()` Returns the `Document` built by the `NearQuery`.
`NearQuery`	`with(Pageable pageable)` Configures the `Pageable` to use.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - near
```
public static NearQuery near(double x,
                             double y)
```
    Creates a new NearQuery starting near the given coordinates.
    
    Parameters:
    
    x -
    
    y -
    
    Returns:
  - near
```
public static NearQuery near(double x,
                             double y,
                             Metric metric)
```
    Creates a new NearQuery starting at the given coordinates using the given Metric to adapt given values to further configuration. E.g. setting a maxDistance(double) will be interpreted as a value of the initially set Metric.
    
    Parameters:
    
    x -
    
    y -
    
    metric - must not be null.
    
    Returns:
  - near
```
public static NearQuery near(Point point)
```
    Creates a new NearQuery starting at the given Point.
    NOTE There is a difference in using Point versus GeoJsonPoint. Point values are rendered as coordinate pairs in the legacy format and operate upon radians, whereas the GeoJsonPoint uses according to its specification meters as unit of measure. This may lead to different results when using a neutral Metric.
    
    Parameters:
    
    point - must not be null.
    
    Returns:
    
    new instance of NearQuery.
  - near
```
public static NearQuery near(Point point,
                             Metric metric)
```
    Creates a NearQuery starting near the given Point using the given Metric to adapt given values to further configuration. E.g. setting a maxDistance(double) will be interpreted as a value of the initially set Metric.
    NOTE There is a difference in using Point versus GeoJsonPoint. Point values are rendered as coordinate pairs in the legacy format and operate upon radians, whereas the GeoJsonPoint uses according to its specification meters as unit of measure. This may lead to different results when using a neutral Metric.
    
    Parameters:
    
    point - must not be null.
    
    metric - must not be null.
    
    Returns:
    
    new instance of NearQuery.
  - getMetric
```
public Metric getMetric()
```
    Returns the Metric underlying the actual query. If no metric was set explicitly Metrics.NEUTRAL will be returned.
    
    Returns:
    
    will never be null.
  - num
```
@Deprecated
public NearQuery num(long num)
```
    Deprecated. since 2.2. Please use limit(long) instead.
    
    Configures the maximum number of results to return.
    
    Parameters:
    
    num -
    
    Returns:
  - limit
```
public NearQuery limit(long limit)
```
    Configures the maximum number of results to return.
    
    Parameters:
    
    limit -
    
    Returns:
    
    Since:
    
    2.2
  - skip
```
public NearQuery skip(long skip)
```
    Configures the number of results to skip.
    
    Parameters:
    
    skip -
    
    Returns:
  - with
```
public NearQuery with(Pageable pageable)
```
    Configures the Pageable to use.
    
    Parameters:
    
    pageable - must not be null
    
    Returns:
  - maxDistance
```
public NearQuery maxDistance(double maxDistance)
```
    Sets the max distance results shall have from the configured origin. If a Metric was set before the given value will be interpreted as being a value in that metric. E.g.
```
 NearQuery query = near(10.0, 20.0, Metrics.KILOMETERS).maxDistance(150);
 
```
    Will set the maximum distance to 150 kilometers.
    Parameters:
    
    maxDistance -
    
    Returns:
  - maxDistance
```
public NearQuery maxDistance(double maxDistance,
                             Metric metric)
```
    Sets the maximum distance supplied in a given metric. Will normalize the distance but not reconfigure the query's result Metric if one was configured before.
    
    Parameters:
    
    maxDistance -
    
    metric - must not be null.
    
    Returns:
  - maxDistance
```
public NearQuery maxDistance(Distance distance)
```
    Sets the maximum distance to the given Distance. Will set the returned Metric to be the one of the given Distance if Metric was Metrics.NEUTRAL before.
    
    Parameters:
    
    distance - must not be null.
    
    Returns:
  - minDistance
```
public NearQuery minDistance(double minDistance)
```
    Sets the minimum distance results shall have from the configured origin. If a Metric was set before the given value will be interpreted as being a value in that metric. E.g.
```
 NearQuery query = near(10.0, 20.0, Metrics.KILOMETERS).minDistance(150);
 
```
    Will set the minimum distance to 150 kilometers.
    Parameters:
    
    minDistance -
    
    Returns:
    
    Since:
    
    1.7
  - minDistance
```
public NearQuery minDistance(double minDistance,
                             Metric metric)
```
    Sets the minimum distance supplied in a given metric. Will normalize the distance but not reconfigure the query's result Metric if one was configured before.
    
    Parameters:
    
    minDistance -
    
    metric - must not be null.
    
    Returns:
    
    Since:
    
    1.7
  - minDistance
```
public NearQuery minDistance(Distance distance)
```
    Sets the minimum distance to the given Distance. Will set the returned Metric to be the one of the given Distance if no Metric was set before.
    
    Parameters:
    
    distance - must not be null.
    
    Returns:
    
    Since:
    
    1.7
  - getMaxDistance
```
@Nullable
public Distance getMaxDistance()
```
    Returns the maximum Distance.
    
    Returns:
  - getMinDistance
```
@Nullable
public Distance getMinDistance()
```
    Returns the maximum Distance.
    
    Returns:
    
    Since:
    
    1.7
  - distanceMultiplier
```
public NearQuery distanceMultiplier(double distanceMultiplier)
```
    Configures a CustomMetric with the given multiplier.
    
    Parameters:
    
    distanceMultiplier -
    
    Returns:
  - spherical
```
public NearQuery spherical(boolean spherical)
```
    Configures whether to return spherical values for the actual distance.
    
    Parameters:
    
    spherical -
    
    Returns:
  - isSpherical
```
public boolean isSpherical()
```
    Returns whether spharical values will be returned.
    
    Returns:
  - inKilometers
```
public NearQuery inKilometers()
```
    Will cause the results' distances being returned in kilometers. Sets distanceMultiplier(double) and spherical(boolean) accordingly.
    
    Returns:
  - inMiles
```
public NearQuery inMiles()
```
    Will cause the results' distances being returned in miles. Sets distanceMultiplier(double) and spherical(boolean) accordingly.
    
    Returns:
  - in
```
public NearQuery in(@Nullable
                    Metric metric)
```
    Will cause the results' distances being returned in the given metric. Sets distanceMultiplier(double) accordingly as well as spherical(boolean) if the given Metric is not Metrics.NEUTRAL.
    
    Parameters:
    
    metric - the metric the results shall be returned in. Uses Metrics.NEUTRAL if null is passed.
    
    Returns:
  - query
```
public NearQuery query(Query query)
```
    Adds an actual query to the NearQuery to restrict the objects considered for the actual near operation.
    
    Parameters:
    
    query - must not be null.
    
    Returns:
  - getSkip
```
@Nullable
public Long getSkip()
```
    Returns:
    
    the number of elements to skip.
  - getCollation
```
@Nullable
public Collation getCollation()
```
    Get the Collation to use along with the query(Query).
    
    Returns:
    
    the Collation if set. null otherwise.
    
    Since:
    
    2.2
  - toDocument
```
public org.bson.Document toDocument()
```
    Returns the Document built by the NearQuery.
    
    Returns:

Class NearQuery

Method Summary

Methods inherited from class java.lang.Object

Method Detail

near

near

near

near

getMetric

num

limit

skip

with

maxDistance

maxDistance

maxDistance

minDistance

minDistance

minDistance

getMaxDistance

getMinDistance

distanceMultiplier

spherical

isSpherical

inKilometers

inMiles

in

query

getSkip

getCollation

toDocument