From e375d1b71c80fd82ac0a0a61b7fd175feb7a1fef Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 11:49:31 -0400 Subject: [PATCH 1/5] adding in geoOperators (box, center, near-center sphere, polygon) to the operators list --- source/reference/operator/box.txt | 24 +++++++++++++++++++ source/reference/operator/center.txt | 28 ++++++++++++++++++++++ source/reference/operator/centerSphere.txt | 25 +++++++++++++++++++ source/reference/operator/nearSphere.txt | 19 +++++++++++++++ source/reference/operator/polygon.txt | 27 +++++++++++++++++++++ source/reference/operator/within.txt | 2 +- 6 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 source/reference/operator/box.txt create mode 100644 source/reference/operator/center.txt create mode 100644 source/reference/operator/centerSphere.txt create mode 100644 source/reference/operator/nearSphere.txt create mode 100644 source/reference/operator/polygon.txt diff --git a/source/reference/operator/box.txt b/source/reference/operator/box.txt new file mode 100644 index 00000000000..1d08a7c12fc --- /dev/null +++ b/source/reference/operator/box.txt @@ -0,0 +1,24 @@ +==== +$box +==== + +.. default-domain:: mongodb + +.. operator:: $box + + .. versionadded:: 1.4 + + The :operator:`$box` operator specifies a rectangular shape for the + :operator:`$within` operator in :term:`geospatial` queries. To use + the :operator:`$box` operator, you must specify the bottom left and + top right corners of the rectangle in an array object. Consider the + following example: + + .. code-block:: javascript + + db.collection.find( { loc: { $within: { $box: [ [0,0], [100,100] ] } } } ) + + This will return all the documents that are within the box having + points at: ``[0,0]``, ``[0,100]``, ``[100,0]``, and ``[100,100]``. + + .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/center.txt b/source/reference/operator/center.txt new file mode 100644 index 00000000000..80fc40cd00f --- /dev/null +++ b/source/reference/operator/center.txt @@ -0,0 +1,28 @@ +======= +$center +======= + +.. default-domain:: mongodb + +.. operator:: $center + + .. versionadded:: 1.4 + + This specifies a circle shape for the :operator:`$within` operator + in :term:`geospatial` queries. To define the bounds of a query + using :operator:`$center`, you must specify: + + - the center point, and + + - the radius + + Considering the following example: + + .. code-block:: javascript + + db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } ); + + The above command returns all the documents that fall within a + 10 unit radius of the point ``[0,0]``. + + .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/centerSphere.txt b/source/reference/operator/centerSphere.txt new file mode 100644 index 00000000000..9afc27f9185 --- /dev/null +++ b/source/reference/operator/centerSphere.txt @@ -0,0 +1,25 @@ +============= +$centerSphere +============= + +.. default-domain:: mongodb + +.. operator:: $centerSphere + + .. versionadded:: 1.8 + + The :operator:`$centerSphere` operator is the spherical equivalent + of the :operator:`$center` operator. :operator:`$centerSphere` uses + spherical geometry to calculate distances in a circle specified by + a point and radius. + + Considering the following example: + + .. code-block:: javascript + + db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } ) + + This query will return all documents within a 10 mile radius of + ``[0,0]`` using a spherical geometry to calculate distances. + + .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/nearSphere.txt b/source/reference/operator/nearSphere.txt new file mode 100644 index 00000000000..4b700bfc731 --- /dev/null +++ b/source/reference/operator/nearSphere.txt @@ -0,0 +1,19 @@ +=========== +$nearSphere +=========== + +.. default-domain:: mongodb + +.. operator:: $nearSphere + + .. versionadded:: 1.8 + + The :operator:`$nearSphere` operator is the spherical equivalent of + the :operator:`$near` operator. :operator:`$nearSphere` returns all + documents near a point, calculating distances using spherical geometry. + + .. code-block:: javascript + + db.collection.find( { loc: { $nearSphere: [0,0] } } ) + + .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/polygon.txt b/source/reference/operator/polygon.txt new file mode 100644 index 00000000000..31387ae03a0 --- /dev/null +++ b/source/reference/operator/polygon.txt @@ -0,0 +1,27 @@ +======== +$polygon +======== + +.. default-domain:: mongodb + +.. operator:: $polygon + + .. versionadded:: 1.9 + + Use :operator:`$polygon` to specify a polgon for a bounded query + using the :operator:`$within` operator for :term:`geospatial` + queries. To define the polygon, you must specify an array of + coordinate points, as in the following: + + [ [ x1,y1 ], [x2,y2], [x3,y3] ] + + The last point specified is always implicitly connected to the + first. You can specify as many points, and therfore sides, as you + like. Consider the following bounded query for documents with + coordinates within a polygon: + + .. code-block:: javascript + + db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0] ] } } } ) + + .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/within.txt b/source/reference/operator/within.txt index 57b65b817c0..28e6da0bb61 100644 --- a/source/reference/operator/within.txt +++ b/source/reference/operator/within.txt @@ -7,7 +7,7 @@ $within .. operator:: $within The :operator:`$within` operator allows you to select items that exist - within a shape on a coordinate system. This operator uses the + within a shape on a coordinate system for :term:`geospatial` queries. This operator uses the following syntax: .. code-block:: javascript From f1d86c299370ff4d2b71ca1e2c98fa356e255e50 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 13:49:04 -0400 Subject: [PATCH 2/5] adding in cross references from within function and updating operators.txt --- source/reference/operator/within.txt | 6 +++--- source/reference/operators.txt | 15 +++++++++++++++ 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/source/reference/operator/within.txt b/source/reference/operator/within.txt index 28e6da0bb61..1041babe9b9 100644 --- a/source/reference/operator/within.txt +++ b/source/reference/operator/within.txt @@ -18,7 +18,7 @@ $within :operator:`$within` command supports three shapes. These shapes and the relevant expressions follow: - - Rectangles. Use the :operator:`$box` shape, consider the following + - Rectangles. Use the :operator:`$box` operator, consider the following variable and :operator:`$within` document: .. code-block:: javascript @@ -29,13 +29,13 @@ $within for the query. As a minimum, you must specify the lower-left and upper-right corners of the box. - - Circles. Specify circles in the following form: + - Circles. Use the :operator:`$center` operator. Specify circles in the following form: .. code-block:: javascript db.collection.find( { location: { $within: { $circle: [ center, radius } } } ); - - Polygons. Specify polygons with an array of points. See the + - Polygons. Use the :operator:`$polygon` operator. Specify polygons with an array of points. See the following example: .. code-block:: javascript diff --git a/source/reference/operators.txt b/source/reference/operators.txt index 925a6fa00f3..55718bed085 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -98,6 +98,21 @@ Geospatial .. include:: operator/within.txt :start-after: mongodb +.. include:: operator/box.txt + :start-after: mongodb + +.. include:: operator/polygon.txt + :start-after: mongodb + +.. include:: operator/center.txt + :start-after: mongodb + +.. include:: operator/nearSphere.txt + :start-after: mongodb + +.. include:: operator/centerSphere.txt + :start-after: mongodb + .. include:: operator/uniqueDocs.txt :start-after: mongodb From 1eb44aa697764134f1a3cdabaaef04c07a348d69 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 18:15:37 -0400 Subject: [PATCH 3/5] added includeLocs to geoNear, rewrote uniqueDocs options --- source/reference/command/geoNear.txt | 26 ++++- source/reference/operator/uniqueDocs.txt | 124 +++++++++++++++++++---- source/reference/operator/within.txt | 17 ++++ source/reference/operators.txt | 12 --- 4 files changed, 147 insertions(+), 32 deletions(-) diff --git a/source/reference/command/geoNear.txt b/source/reference/command/geoNear.txt index 812898725b7..d98ccd2bb91 100644 --- a/source/reference/command/geoNear.txt +++ b/source/reference/command/geoNear.txt @@ -26,15 +26,15 @@ geoNear :field num: Specifies the maximum number of documents to return. - :field maxDistance: Limits the results to those falling within + :field maxDistance: Optional. Limits the results to those falling within a given distance of the center coordinate. - :field query: Further narrows the results using any standard + :field query: Optional. Further narrows the results using any standard MongoDB query operator or selection. See :method:`db.collection.find()` and ":doc:`/reference/operators`" for more information. - :field distanceMultipler: Specifies a factor to multiply + :field distanceMultipler: Optional. Specifies a factor to multiply all distances returned by :dbcommand:`geoNear`. For example, use ``distanceMultiplier`` to convert from @@ -43,4 +43,24 @@ geoNear by multiplying by the radius of the Earth. + + .. TODO include + :ref:`geospatial-spherical-geometry` + link when geospatial materials are + merged in. + + :field includeLocs: Optional. Default: ``false``. When specified + ``true``, the location of matching documents + are returned in the result. + + :field uniqueDocs: Optional. Default ``true``. The default settings + will only return a matching document once, even + if more than one of its location fields match + the query. When specified ``false``, documents + with multiple location fields matching the query + will be returned for each match. + + .. seealso:: :operator:`$uniqueDocs` + + .. read-lock, slave-ok diff --git a/source/reference/operator/uniqueDocs.txt b/source/reference/operator/uniqueDocs.txt index cd1ddc44da1..06574ec74ff 100644 --- a/source/reference/operator/uniqueDocs.txt +++ b/source/reference/operator/uniqueDocs.txt @@ -6,23 +6,113 @@ $uniqueDocs .. operator:: $uniqueDocs - When using the :dbcommand:`geoNear`, if document contains more than - one field with coordinate values, MongoDB will return the same - document multiple times. When using the :operator:`$within`, - however, MongoDB provides opposite behavior: if a document contains - more than one field with coordinate values, MongoDB will only - return the document once. - - The :operator:`$uniqueDocs` operator overrides these default - behaviors. - - By specifying ``$uniqueDocs: false`` in a :operator:`$within` - query, will cause the query to return a single document multiple - times if there is more than one match. - - By contrast, if you specify ``uniqueDocs: true`` as an option to - the a :dbcommand:`geoNear` command, then :dbcommand:`geoNear` only - returns a single document even if there are multiple matches. + .. versionadded:: 2.0 + + For :term:`geospatial` queries, MongoDB may reuturn a single + document more than once for a single query, because geospatial + indexes may include multiple coordinate pairs in a single + document, and therefore return the same document more than once. + + The :operator:`$uniqueDocs` operator inverts the default behavior + of these queres. By default, :dbcommand:`geoNear` will always + return multiple instances of the same document, while the + :operator:`$within` operator will *never* return the same document + more than once. Consider the following: + + - For :dbcommand:`geoNear` queries, the default + :operator:`$uniqueDocs` setting is ``false``. If you specify a + value of ``true`` for :operator:`uniqueDocs`, MongoDB will + return multiple instances of a single document. + + - For :operator:`$within` queries, the default + :operator:`$uniqueDocs` setting is ``true``. If you specify a + value of ``false`` for :operator:`uniqueDocs`, MongoDB will + return multiple instances of a single document. + + .. example:: + + Given a document in the following form: + + .. code-block:: javascript + + { addresses: [ { name: "Home", loc:[55.5,42.3]}, {name:"Work",loc:[32.3,44.2]}]} + + The following queries would return the same document multiple + times: + + .. code-block:: javascript + + > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: false }) + + > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() + + The following queries would return each matching document, only + once: + + .. code-block:: javascript + + > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: true }) + + > db.geo.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty() + +.. + The following example commands in the :program:`mongo` shell + illustrate this feature: + + .. code-block:: javascript + + > db.geoExample.insert( ) + > db.geoExample.ensureIndex({"addresses.loc":"2d"}) + + /* this will return the entry once - default for $within */ + > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ] } }}) + /* this will return the entry twice */ + > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() + + + .. Above code output: + + .. code-block:: javascript + + > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() + { + "_id" : ObjectId("504900870826ac3f09e25db6"), + "addresses" : [ + { + "name" : "Home", + "loc" : [ + 55.5, + 42.3 + ] + }, + { + "name" : "Work", + "loc" : [ + 32.3, + 44.2 + ] + } + ] + } + { + "_id" : ObjectId("504900870826ac3f09e25db6"), + "addresses" : [ + { + "name" : "Home", + "loc" : [ + 55.5, + 42.3 + ] + }, + { + "name" : "Work", + "loc" : [ + 32.3, + 44.2 + ] + } + ] + } You cannot specify :operator:`$uniqueDocs` with :operator:`$near` or haystack queries. diff --git a/source/reference/operator/within.txt b/source/reference/operator/within.txt index 1041babe9b9..62022b64807 100644 --- a/source/reference/operator/within.txt +++ b/source/reference/operator/within.txt @@ -49,4 +49,21 @@ $within although this is subject to the imprecision of floating point numbers. + Use :operator:`uniqueDocs` to control whether documents with + many location fields show up multiple times when more than one + of its fields match the query. + .. include:: /includes/note-geospatial-index-must-exist.rst + + .. include:: /reference/operator/box.txt + :start-after: mongodb + + .. include:: /reference/operator/polygon.txt + :start-after: mongodb + + .. include:: /reference/operator/center.txt + :start-after: mongodb + + .. include:: /reference/operator/uniqueDocs.txt + :start-after: mongodb + diff --git a/source/reference/operators.txt b/source/reference/operators.txt index 55718bed085..ab6b41e9960 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -98,24 +98,12 @@ Geospatial .. include:: operator/within.txt :start-after: mongodb -.. include:: operator/box.txt - :start-after: mongodb - -.. include:: operator/polygon.txt - :start-after: mongodb - -.. include:: operator/center.txt - :start-after: mongodb - .. include:: operator/nearSphere.txt :start-after: mongodb .. include:: operator/centerSphere.txt :start-after: mongodb -.. include:: operator/uniqueDocs.txt - :start-after: mongodb - .. index:: query selectors; logical .. _query-selectors-logical: From 0cabed6548f3df0a6153dd78829071dcee33ce24 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 19:15:06 -0400 Subject: [PATCH 4/5] cleared geoNear examples from uniqueDocs --- source/reference/operator/uniqueDocs.txt | 93 +++--------------------- 1 file changed, 10 insertions(+), 83 deletions(-) diff --git a/source/reference/operator/uniqueDocs.txt b/source/reference/operator/uniqueDocs.txt index 06574ec74ff..43751c0aebf 100644 --- a/source/reference/operator/uniqueDocs.txt +++ b/source/reference/operator/uniqueDocs.txt @@ -8,111 +8,38 @@ $uniqueDocs .. versionadded:: 2.0 - For :term:`geospatial` queries, MongoDB may reuturn a single + For :term:`geospatial` queries, MongoDB may return a single document more than once for a single query, because geospatial indexes may include multiple coordinate pairs in a single document, and therefore return the same document more than once. The :operator:`$uniqueDocs` operator inverts the default behavior - of these queres. By default, :dbcommand:`geoNear` will always - return multiple instances of the same document, while the - :operator:`$within` operator will *never* return the same document - more than once. Consider the following: - - - For :dbcommand:`geoNear` queries, the default - :operator:`$uniqueDocs` setting is ``false``. If you specify a - value of ``true`` for :operator:`uniqueDocs`, MongoDB will - return multiple instances of a single document. - - - For :operator:`$within` queries, the default - :operator:`$uniqueDocs` setting is ``true``. If you specify a - value of ``false`` for :operator:`uniqueDocs`, MongoDB will - return multiple instances of a single document. + of the :operator:`$within` operator. By default, the + :operator:`$within` operator returns the document only once. If you + specify a value of ``false`` for :operator:`uniqueDocs`, MongoDB + will return multiple instances of a single document. .. example:: - Given a document in the following form: + Given an ``addressBook`` collection with a document in the following form: .. code-block:: javascript { addresses: [ { name: "Home", loc:[55.5,42.3]}, {name:"Work",loc:[32.3,44.2]}]} - The following queries would return the same document multiple + The following query would return the same document multiple times: .. code-block:: javascript - > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: false }) - - > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() + db.addressBook.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() - The following queries would return each matching document, only + The following query would return each matching document, only once: .. code-block:: javascript - > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: true }) - - > db.geo.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty() - -.. - The following example commands in the :program:`mongo` shell - illustrate this feature: - - .. code-block:: javascript - - > db.geoExample.insert( ) - > db.geoExample.ensureIndex({"addresses.loc":"2d"}) - - /* this will return the entry once - default for $within */ - > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ] } }}) - /* this will return the entry twice */ - > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() - - - .. Above code output: - - .. code-block:: javascript - - > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() - { - "_id" : ObjectId("504900870826ac3f09e25db6"), - "addresses" : [ - { - "name" : "Home", - "loc" : [ - 55.5, - 42.3 - ] - }, - { - "name" : "Work", - "loc" : [ - 32.3, - 44.2 - ] - } - ] - } - { - "_id" : ObjectId("504900870826ac3f09e25db6"), - "addresses" : [ - { - "name" : "Home", - "loc" : [ - 55.5, - 42.3 - ] - }, - { - "name" : "Work", - "loc" : [ - 32.3, - 44.2 - ] - } - ] - } + db.addressBook.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty() You cannot specify :operator:`$uniqueDocs` with :operator:`$near` or haystack queries. From e1638901500599b99e524891431e6ecd7f2c349c Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 19:25:37 -0400 Subject: [PATCH 5/5] fixing up spacing in examples --- source/reference/operator/uniqueDocs.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/reference/operator/uniqueDocs.txt b/source/reference/operator/uniqueDocs.txt index 43751c0aebf..ecf71db95f2 100644 --- a/source/reference/operator/uniqueDocs.txt +++ b/source/reference/operator/uniqueDocs.txt @@ -16,7 +16,7 @@ $uniqueDocs The :operator:`$uniqueDocs` operator inverts the default behavior of the :operator:`$within` operator. By default, the :operator:`$within` operator returns the document only once. If you - specify a value of ``false`` for :operator:`uniqueDocs`, MongoDB + specify a value of ``false`` for :operator:`$uniqueDocs`, MongoDB will return multiple instances of a single document. .. example:: @@ -25,21 +25,21 @@ $uniqueDocs .. code-block:: javascript - { addresses: [ { name: "Home", loc:[55.5,42.3]}, {name:"Work",loc:[32.3,44.2]}]} + { addresses: [ { name: "Home", loc: [55.5, 42.3] }, { name: "Work", loc: [32.3, 44.2] } ] } The following query would return the same document multiple times: .. code-block:: javascript - db.addressBook.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty() + db.addressBook.find( { "addresses.loc": { "$within": { "$box": [ [0,0], [100,100] ], $uniqueDocs: false } } } ) The following query would return each matching document, only once: .. code-block:: javascript - db.addressBook.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty() + db.addressBook.find( { "address.loc": { "$within": { "$box": [ [0,0], [100,100] ], $uniqueDocs: true } } } ) You cannot specify :operator:`$uniqueDocs` with :operator:`$near` or haystack queries.