Skip to content

Commit ded2577

Browse files
kay-kimkay-kim
committed
DOCS-1070 geoNear
1 parent d9029d7 commit ded2577

File tree

4 files changed

+176
-0
lines changed

4 files changed

+176
-0
lines changed

‎source/applications/aggregation.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ through the pipeline.
7676
- :agg:pipeline:`$unwind`
7777
- :agg:pipeline:`$group`
7878
- :agg:pipeline:`$sort`
79+
- :agg:pipeline:`$geoNear`
7980

8081
.. _aggregation-expressions:
8182

@@ -204,6 +205,13 @@ following aggregation operators:
204205
- :agg:pipeline:`$unwind`
205206
- :agg:pipeline:`$group`.
206207

208+
.. versionadded:: 2.4
209+
210+
The :agg:pipeline:`$geoNear` pipeline operator takes advantage of a
211+
geospatial index. When using :agg:pipeline:`$geoNear`, the
212+
:agg:pipeline:`$geoNear` pipeline operation must appear as the first
213+
stage in an aggregation pipeline.
214+
207215
Early Filtering
208216
~~~~~~~~~~~~~~~
209217

‎source/reference/aggregation.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,9 @@ The current pipeline operators are:
9393
.. include:: aggregation/sort.txt
9494
:start-after: default-domain:: agg
9595

96+
.. include:: aggregation/geoNear.txt
97+
:start-after: default-domain:: agg
98+
9699
.. _aggregation-expression-operators:
97100

98101
Expressions

‎source/reference/aggregation/geoNear.txt

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
======================
2+
$geoNear (aggregation)
3+
======================
4+
5+
.. default-domain:: agg
6+
7+
.. pipeline:: $geoNear
8+
9+
.. versionadded:: 2.4
10+
11+
:pipeline:`$geoNear` returns documents in order of nearest to
12+
farthest from a specified point and pass the documents
13+
through the aggregation :term:`pipeline`.
14+
15+
.. important::
16+
17+
- You can only use :pipeline:`$geoNear` as the first stage of a
18+
pipeline.
19+
20+
- You must include the ``distanceField`` option. The
21+
``distanceField`` option specifies the field that will contain
22+
the calculated distance.
23+
24+
- The collection must have a :doc:`geospatial index
25+
</core/geospatial-indexes>`.
26+
27+
The :pipeline:`$geoNear` accept the following options:
28+
29+
:field coordinates near:
30+
Specifies the coordinates (e.g. ``[ x, y ]``) to
31+
use as the center of a geospatial query.
32+
33+
:field string distanceField:
34+
Specifies the output field that will contain the calculated
35+
distance. You can use the :mongodb:term:`dot notation` to
36+
specify a field within a subdocument.
37+
38+
:field number num:
39+
Optional. Specifies the maximum number of documents to
40+
return. The default value is 100.
41+
42+
:field number maxDistance: Optional.
43+
Limits the results to the documents within the
44+
specified distance from the center coordinates.
45+
46+
:field document query:
47+
Optional.
48+
Limits the results to the documents that match the
49+
query. The query syntax is identical to
50+
the :ref:`read operation query
51+
<read-operations-query-argument>` syntax.
52+
53+
:field boolean spherical:
54+
Optional. Default value is ``false``. When ``true``,
55+
MongoDB performs calculation using spherical geometry.
56+
57+
:field number distanceMultiplier:
58+
Optional. Specifies a factor to multiply all distances
59+
returned by :pipeline:`$geoNear`. For example, use
60+
``distanceMultiplier`` to convert from spherical
61+
queries returned in radians to linear units (i.e.
62+
miles or kilometers) by multiplying by the radius of
63+
the Earth.
64+
65+
:field string includeLocs:
66+
Optional. Specifies the output field that identifies
67+
the location used to calculate the distance. This
68+
option is useful when a location field contains
69+
multiple locations. You can use the
70+
:mongodb:term:`dot notation` to specify a field within
71+
a subdocument.
72+
73+
:field boolean uniqueDocs:
74+
Optional. Default value is ``false``. If a location
75+
field contains multiple locations, the default
76+
settings will return the document multiple times if
77+
more than one location meets the criteria.
78+
79+
When ``true``, the document will only return once
80+
even if the document has multiple locations that meet
81+
the criteria.
82+
83+
.. example::
84+
85+
The following aggregation finds at most ``5`` *unique* documents
86+
with a location at most .008 from the center ``[40.72, -73.99]``
87+
and have ``type`` equal to ``public``:
88+
89+
.. code-block:: javascript
90+
91+
db.places.aggregate([
92+
{
93+
$geoNear: {
94+
near: [40.724, -73.997],
95+
distanceField: "dist.calculated",
96+
maxDistance: 0.008,
97+
query: { type: "public" },
98+
includeLocs: "dist.location",
99+
uniqueDocs: true,
100+
num: 5
101+
}
102+
}
103+
])
104+
105+
The aggregation returns the following:
106+
107+
.. code-block:: javascript
108+
109+
{
110+
"result" : [
111+
{ "_id" : 7,
112+
"name" : "Washington Square",
113+
"type" : "public",
114+
"location" : [
115+
[ 40.731, -73.999 ],
116+
[ 40.732, -73.998 ],
117+
[ 40.730, -73.995 ],
118+
[ 40.729, -73.996 ]
119+
],
120+
"dist" : {
121+
"calculated" : 0.0050990195135962296,
122+
"location" : [ 40.729, -73.996 ]
123+
}
124+
},
125+
{ "_id" : 8,
126+
"name" : "Sara D. Roosevelt Park",
127+
"type" : "public",
128+
"location" : [
129+
[ 40.723, -73.991 ],
130+
[ 40.723, -73.990 ],
131+
[ 40.715, -73.994 ],
132+
[ 40.715, -73.994 ]
133+
],
134+
"dist" : {
135+
"calculated" : 0.006082762530298062,
136+
"location" : [ 40.723, -73.991 ]
137+
}
138+
}
139+
],
140+
"ok" : 1
141+
}
142+
143+
The matching documents in the ``result`` field contain two new fields:
144+
145+
- ``dist.calculated`` field that contains the calculated distance, and
146+
147+
- ``dist.location`` field that contains the location used in the
148+
calculation.
149+
150+
.. note::
151+
152+
The options for :pipeline:`$geoNear` are similar to the
153+
:mongodb:dbcommand:`geoNear` command with the following
154+
exceptions:
155+
156+
- ``distanceField`` is a mandatory field for the
157+
:pipeline:`$geoNear` pipeline operator; the option does not
158+
exist in the :mongodb:dbcommand:`geoNear` command.
159+
160+
- ``includeLocs`` accepts a ``string`` in the
161+
:pipeline:`$geoNear` pipeline operator and a ``boolean`` in the
162+
:mongodb:dbcommand:`geoNear` command.

‎source/release-notes/2.4.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -457,3 +457,6 @@ Improvements to the Aggregation Framework
457457
portion of a date.
458458

459459
- New :agg:expression:`$concat` concatenates array of strings.
460+
461+
- New :agg:pipeline:`$geoNear` pipeline operator to support geospatial
462+
queries.

0 commit comments

Comments
 (0)