public final class NearQuery extends Object
$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 serverMetric
to the desired unit of measure which ensures the
distance to be calculated correctly.
{
"_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. 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
}
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)
|
static NearQuery |
near(Point point)
|
static NearQuery |
near(Point point,
Metric metric)
|
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. |
public static NearQuery near(double x, double y)
NearQuery
starting near the given coordinates.x
- y
- public static NearQuery near(double x, double y, Metric metric)
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
.x
- y
- metric
- must not be null.public static NearQuery near(Point point)
NearQuery
starting at the given Point
. 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
.point
- must not be null.NearQuery
.public static NearQuery near(Point point, Metric metric)
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
. 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
.point
- must not be null.metric
- must not be null.NearQuery
.public Metric getMetric()
Metric
underlying the actual query. If no metric was set explicitly Metrics.NEUTRAL
will be returned.@Deprecated public NearQuery num(long num)
limit(long)
instead.num
- public NearQuery limit(long limit)
limit
- public NearQuery skip(long skip)
skip
- public NearQuery with(Pageable pageable)
Pageable
to use.pageable
- must not be nullpublic NearQuery maxDistance(double maxDistance)
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.
maxDistance
- public NearQuery maxDistance(double maxDistance, Metric metric)
Metric
if one was configured before.maxDistance
- metric
- must not be null.public NearQuery maxDistance(Distance distance)
Distance
. Will set the returned Metric
to be the one of the
given Distance
if Metric
was Metrics.NEUTRAL
before.distance
- must not be null.public NearQuery minDistance(double minDistance)
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.
minDistance
- public NearQuery minDistance(double minDistance, Metric metric)
Metric
if one was configured before.minDistance
- metric
- must not be null.public NearQuery minDistance(Distance distance)
Distance
. Will set the returned Metric
to be the one of the
given Distance
if no Metric
was set before.distance
- must not be null.@Nullable public Distance getMinDistance()
Distance
.public NearQuery distanceMultiplier(double distanceMultiplier)
CustomMetric
with the given multiplier.distanceMultiplier
- public NearQuery spherical(boolean spherical)
spherical
- public boolean isSpherical()
public NearQuery inKilometers()
distanceMultiplier(double)
and
spherical(boolean)
accordingly.public NearQuery inMiles()
distanceMultiplier(double)
and
spherical(boolean)
accordingly.public NearQuery in(@Nullable Metric metric)
distanceMultiplier(double)
accordingly as well as spherical(boolean)
if the given Metric
is not Metrics.NEUTRAL
.metric
- the metric the results shall be returned in. Uses Metrics.NEUTRAL
if null is
passed.public NearQuery query(Query query)
NearQuery
to restrict the objects considered for the actual near operation.query
- must not be null.@Nullable public Collation getCollation()
Collation
to use along with the query(Query)
.Collation
if set. null otherwise.public org.bson.Document toDocument()
Document
built by the NearQuery
.Copyright © 2011–2021 Pivotal Software, Inc.. All rights reserved.