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/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/uniqueDocs.txt b/source/reference/operator/uniqueDocs.txt index cd1ddc44da1..ecf71db95f2 100644 --- a/source/reference/operator/uniqueDocs.txt +++ b/source/reference/operator/uniqueDocs.txt @@ -6,23 +6,40 @@ $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 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 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 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 query would return the same document multiple + times: + + .. code-block:: javascript + + 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 } } } ) 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 57b65b817c0..62022b64807 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 @@ -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 @@ -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 925a6fa00f3..ab6b41e9960 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -98,7 +98,10 @@ Geospatial .. include:: operator/within.txt :start-after: mongodb -.. include:: operator/uniqueDocs.txt +.. include:: operator/nearSphere.txt + :start-after: mongodb + +.. include:: operator/centerSphere.txt :start-after: mongodb .. index:: query selectors; logical