Skip to content

Commit 1eb44aa

Browse files
author
Andrew Leung
committed
added includeLocs to geoNear, rewrote uniqueDocs options
1 parent f1d86c2 commit 1eb44aa

File tree

4 files changed

+147
-32
lines changed

4 files changed

+147
-32
lines changed

‎source/reference/command/geoNear.txt‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,15 @@ geoNear
2626

2727
:field num: Specifies the maximum number of documents to return.
2828

29-
:field maxDistance: Limits the results to those falling within
29+
:field maxDistance: Optional. Limits the results to those falling within
3030
a given distance of the center coordinate.
3131

32-
:field query: Further narrows the results using any standard
32+
:field query: Optional. Further narrows the results using any standard
3333
MongoDB query operator or selection. See :method:`db.collection.find()`
3434
and ":doc:`/reference/operators`" for more
3535
information.
3636

37-
:field distanceMultipler: Specifies a factor to multiply
37+
:field distanceMultipler: Optional. Specifies a factor to multiply
3838
all distances returned by
3939
:dbcommand:`geoNear`. For example, use
4040
``distanceMultiplier`` to convert from
@@ -43,4 +43,24 @@ geoNear
4343
by multiplying by the radius of the
4444
Earth.
4545

46+
47+
.. TODO include
48+
:ref:`geospatial-spherical-geometry`
49+
link when geospatial materials are
50+
merged in.
51+
52+
:field includeLocs: Optional. Default: ``false``. When specified
53+
``true``, the location of matching documents
54+
are returned in the result.
55+
56+
:field uniqueDocs: Optional. Default ``true``. The default settings
57+
will only return a matching document once, even
58+
if more than one of its location fields match
59+
the query. When specified ``false``, documents
60+
with multiple location fields matching the query
61+
will be returned for each match.
62+
63+
.. seealso:: :operator:`$uniqueDocs`
64+
65+
4666
.. read-lock, slave-ok

‎source/reference/operator/uniqueDocs.txt‎

Lines changed: 107 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,113 @@ $uniqueDocs
66

77
.. operator:: $uniqueDocs
88

9-
When using the :dbcommand:`geoNear`, if document contains more than
10-
one field with coordinate values, MongoDB will return the same
11-
document multiple times. When using the :operator:`$within`,
12-
however, MongoDB provides opposite behavior: if a document contains
13-
more than one field with coordinate values, MongoDB will only
14-
return the document once.
15-
16-
The :operator:`$uniqueDocs` operator overrides these default
17-
behaviors.
18-
19-
By specifying ``$uniqueDocs: false`` in a :operator:`$within`
20-
query, will cause the query to return a single document multiple
21-
times if there is more than one match.
22-
23-
By contrast, if you specify ``uniqueDocs: true`` as an option to
24-
the a :dbcommand:`geoNear` command, then :dbcommand:`geoNear` only
25-
returns a single document even if there are multiple matches.
9+
.. versionadded:: 2.0
10+
11+
For :term:`geospatial` queries, MongoDB may reuturn a single
12+
document more than once for a single query, because geospatial
13+
indexes may include multiple coordinate pairs in a single
14+
document, and therefore return the same document more than once.
15+
16+
The :operator:`$uniqueDocs` operator inverts the default behavior
17+
of these queres. By default, :dbcommand:`geoNear` will always
18+
return multiple instances of the same document, while the
19+
:operator:`$within` operator will *never* return the same document
20+
more than once. Consider the following:
21+
22+
- For :dbcommand:`geoNear` queries, the default
23+
:operator:`$uniqueDocs` setting is ``false``. If you specify a
24+
value of ``true`` for :operator:`uniqueDocs`, MongoDB will
25+
return multiple instances of a single document.
26+
27+
- For :operator:`$within` queries, the default
28+
:operator:`$uniqueDocs` setting is ``true``. If you specify a
29+
value of ``false`` for :operator:`uniqueDocs`, MongoDB will
30+
return multiple instances of a single document.
31+
32+
.. example::
33+
34+
Given a document in the following form:
35+
36+
.. code-block:: javascript
37+
38+
{ addresses: [ { name: "Home", loc:[55.5,42.3]}, {name:"Work",loc:[32.3,44.2]}]}
39+
40+
The following queries would return the same document multiple
41+
times:
42+
43+
.. code-block:: javascript
44+
45+
> db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: false })
46+
47+
> db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
48+
49+
The following queries would return each matching document, only
50+
once:
51+
52+
.. code-block:: javascript
53+
54+
> db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: true })
55+
56+
> db.geo.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty()
57+
58+
..
59+
The following example commands in the :program:`mongo` shell
60+
illustrate this feature:
61+
62+
.. code-block:: javascript
63+
64+
> db.geoExample.insert( )
65+
> db.geoExample.ensureIndex({"addresses.loc":"2d"})
66+
67+
/* this will return the entry once - default for $within */
68+
> db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ] } }})
69+
/* this will return the entry twice */
70+
> db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
71+
72+
73+
.. Above code output:
74+
75+
.. code-block:: javascript
76+
77+
> db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
78+
{
79+
"_id" : ObjectId("504900870826ac3f09e25db6"),
80+
"addresses" : [
81+
{
82+
"name" : "Home",
83+
"loc" : [
84+
55.5,
85+
42.3
86+
]
87+
},
88+
{
89+
"name" : "Work",
90+
"loc" : [
91+
32.3,
92+
44.2
93+
]
94+
}
95+
]
96+
}
97+
{
98+
"_id" : ObjectId("504900870826ac3f09e25db6"),
99+
"addresses" : [
100+
{
101+
"name" : "Home",
102+
"loc" : [
103+
55.5,
104+
42.3
105+
]
106+
},
107+
{
108+
"name" : "Work",
109+
"loc" : [
110+
32.3,
111+
44.2
112+
]
113+
}
114+
]
115+
}
26116

27117
You cannot specify :operator:`$uniqueDocs` with :operator:`$near`
28118
or haystack queries.

‎source/reference/operator/within.txt‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,21 @@ $within
4949
although this is subject to the imprecision of floating point
5050
numbers.
5151

52+
Use :operator:`uniqueDocs` to control whether documents with
53+
many location fields show up multiple times when more than one
54+
of its fields match the query.
55+
5256
.. include:: /includes/note-geospatial-index-must-exist.rst
57+
58+
.. include:: /reference/operator/box.txt
59+
:start-after: mongodb
60+
61+
.. include:: /reference/operator/polygon.txt
62+
:start-after: mongodb
63+
64+
.. include:: /reference/operator/center.txt
65+
:start-after: mongodb
66+
67+
.. include:: /reference/operator/uniqueDocs.txt
68+
:start-after: mongodb
69+

‎source/reference/operators.txt‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -98,24 +98,12 @@ Geospatial
9898
.. include:: operator/within.txt
9999
:start-after: mongodb
100100

101-
.. include:: operator/box.txt
102-
:start-after: mongodb
103-
104-
.. include:: operator/polygon.txt
105-
:start-after: mongodb
106-
107-
.. include:: operator/center.txt
108-
:start-after: mongodb
109-
110101
.. include:: operator/nearSphere.txt
111102
:start-after: mongodb
112103

113104
.. include:: operator/centerSphere.txt
114105
:start-after: mongodb
115106

116-
.. include:: operator/uniqueDocs.txt
117-
:start-after: mongodb
118-
119107
.. index:: query selectors; logical
120108
.. _query-selectors-logical:
121109

0 commit comments

Comments
 (0)