From cede76d53129ea09393b15b7aa532713f69b7b68 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 19 Jul 2012 11:34:25 -0400 Subject: [PATCH 01/17] edited geospatial apps --- draft/applications/geospatial-indexes.txt | 99 ++++++++++++++++------- 1 file changed, 70 insertions(+), 29 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index f71061dab21..33a74375c17 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -8,11 +8,13 @@ MongoDB provides rich location aware queries that return documents based on location with a special geospatial index type. This document introduces geospatial data modeling, indexing operations, and provides example queries using the :ref:`geospatial query operators -`. For more information about the -geospatial indexes and operations see the :doc:`/applications/geospatial-indexes`. +`. For more information about +geospatial indexes and operations see the :doc:`/applications/geospatial-indexes` document. .. _geospatial-coordinates: +.. This include inserts an introduction to geospatial modeling. + "Representing Coordinate Data" .. include:: /includes/geospatial-coordinates.rst .. index:: geospatial queries @@ -24,7 +26,7 @@ Queries MongoDB provides special :ref:`geospatial query operators ` for performing queries on location data -inside of normal :func:`find() ` operation. The +inside the normal :func:`find() ` operator. The :dbcommand:`geoNear` command also returns results using geospatial indexes, but also includes additional geospatial information in the return documents. @@ -37,10 +39,12 @@ return documents. MongoDB can also calculate and return accurate results for locations in a :ref:`spherical ` - coordinate system, suing :ref:`spherical query operations `. + coordinate system, using :ref:`spherical query operations `. .. index:: geospatial queries; exact +.. _geospatial-query-exact: + Exact ~~~~~ @@ -55,11 +59,11 @@ following prototypical form: This query will return any document that where the value of ``[ x, y ]`` is *exactly* the same as the one specified in the query. To return all documents in the ``places`` collection with values in the ``loc`` -field that are exactly ``[ 42, 42 ]``, consider the following example: +field that are exactly ``[ -74, 40.74 ]``, consider the following example: .. code-block:: javascript - db.places.find( { "loc": [ 42, 42 ] } ) + db.places.find( { "loc": [ -74, 40.74 ] } ) Exact geospatial queries only have applicability for a limited selection of cases, :ref:`proximity ` and :ref:`bounded @@ -97,7 +101,7 @@ In addition to :operator:`near`, the :dbcommand:`geoNear` command provides equivalent functionality. :dbcommand:`geoNear` adds additional options and returns more information for each document found. In its most simple form, the :dbcommand:`geoNear` -command has the following prototype form: +command has the following prototypical form: .. code-block:: javascript @@ -110,19 +114,26 @@ in the previous example: db.runCommand( {geoNear: "places", near: [ -74, 40.74 ] } ) +.. seealso:: + + :ref:`geospatial-query-exact` + +.. _geospatial-query-limit: + Limit ````` -To impose a limit on the result set other than the default 100 -document limit, use the :func:`limit() ` method with -:func:`find() ` queries, in the following -prototype operation. +By default, geospatial queries with :func:`find() +` return 100 documents. To impose a limit +on the result set, use the :func:`limit() ` method +with :func:`find() ` operator. The following is +the prototype operation. .. code-block:: javascript db.collection.find( { : { $near: [ x, y ] } } ).limit(n) -The following example, will return only 20 results of the above query: +The following example will return only ``20`` results of the above query: .. code-block:: javascript @@ -140,11 +151,18 @@ in the previous example: .. code-block:: javascript - db.runCommand( {geoNear: "collection", near: [ -74, 40.74 ], num: 20 } ) + db.runCommand( { geoNear: "collection", near: [ -74, 40.74 ], num: 20 } ) + +The :func:`limit() ` and :operator:`near` do not limit +geospatial query results by distance, only the number of returned +:term:`documents`. To limit geospatial search results by distance, +please see the :ref:`geospatial-query-distance` section. .. index:: $maxDistance .. index:: geospatial queries; distance limit +.. _geospatial-query-distance: + Distance ```````` @@ -168,15 +186,18 @@ Specify the distance in the ``maxDistance`` option using the same units as the coordinate system specified. For example, if the indexed location data is in meters, the distance units are also in meters. +To limit geospatial query results by the number of returned +:term:`documents`, please see the :ref:`geospatial-query-limit` section. + .. _geospatial-within: .. _geospatial-query-bounded: Bounded ~~~~~~~ -Bounded queries return results within the boundaries of a shape -specified in the query. The :operator:`$within` operator allows you to -construct these quires. Bounded queries do not return sorted results: +Bounded queries return results within the boundaries of a specified shape +in the query. The :operator:`$within` operator allows you to +construct these queries. Bounded queries do not return sorted results, as a result these queries are faster than :ref:`proximity ` queries. @@ -184,7 +205,7 @@ Using the :operator:`$within`, you can specify boundaries with the following shapes: - circles, -- rectangles (i.e. "boxes,") or +- rectangles, - polygons. Bounded queries take the following prototype form: @@ -197,6 +218,9 @@ Bounded queries take the following prototype form: } } ) +To perform geospatial queries for a particular distance around a +certain point, please see the :ref:`geospatial-query-distance` section. + The following sections provide examples of bounded queries using the :operator:`$within` operator. @@ -237,12 +261,12 @@ corners of the shape, using the :operator:`$within` operator and the The following query will return all documents that have coordinates that exist within the rectangle, where the lower-left corner is at ``[ -0, 0 ]`` and the upper-right corner is at ``[ 5, 5 ]`` using a +0, 0 ]`` and the upper-right corner is at ``[ 3, 3 ]`` using a geospatial index on the ``loc`` field: .. code-block:: javascript - db.places.find( { "loc": { "$within": { "$box": [ [0, 0] , [5, 5] ] } } } ) + db.places.find( { "loc": { "$within": { "$box": [ [0, 0] , [3, 3] ] } } } ) Polygons ```````` @@ -265,7 +289,7 @@ of points: .. code-block:: javascript - [4,0], [3,2], [2,3], [2,4], [4,5] + [0,0], [3,3], [6,0] The following query will return all documents that have coordinates that exist within the bounds of the polygon, where the sides of the @@ -275,7 +299,7 @@ polygon connects at the above points using a geospatial index on the .. code-block:: javascript db.places.find({ "loc": { "$within": { "$polygon": - [4,0], [3,2], [2,3], [2,4], [4,5] + [0,0], [3,3], [6,0] } } }) .. _geospatial-query-spherical: @@ -283,12 +307,14 @@ polygon connects at the above points using a geospatial index on the Spherical ~~~~~~~~~ -If the coordinates in your documents represent points on a -spherical plane, :ref:`proximity ` and +.. TODO make the 'documents' here refer to the MongoDB term. How? + +If the coordinates in your :ref:`documents ` represent points on a +spherical surface, :ref:`proximity ` and some :ref:`bounded ` queries will not return accurate results. To compensate, you can use the following spherical -queries which adjust for these errors. The following table provides a -list of spherical query operators and their flat system equivalents: +queries which adjust for these differences. The following table provides a +list of spherical query operators and their flat surface equivalents: ========================== =================== Spherical Flat @@ -297,7 +323,7 @@ list of spherical query operators and their flat system equivalents: :operator:`$centerSphere` :operator:`$center` ========================== =================== -The :dbcommand:`geoNear` will return results for spherical systems if +The :dbcommand:`geoNear` will return results for spherical surface if you specify the ``{ spherical: true }`` option to the command. .. admonition:: Spherical Queries Use Radians for Distance @@ -321,12 +347,12 @@ you specify the ``{ spherical: true }`` option to the command. The following query would return documents from the ``places`` collection, within the circle described by the center ``[ -74, 40.74 ]`` -with a radius of ``100`` kilometers: +with a radius of ``100`` miles: .. code-block:: javascript db.places.find( { loc: { $centerSphere: [ [ -74, 40.74 ] , - 100 / 6378.137 ] } } ) + 100 / 3963.192 ] } } ) Remember that you must convert the distance of the radius to radians. This conversion *must* happen in your client @@ -360,6 +386,21 @@ their distance from the ``[ -74, 40.74 ]`` point. .. TODO add in distanceMultiplier description +:func:`distanceMultiplier` is a built-in function which will +automatically multiply distances in spherical queries by the assigned +value. All spherical queries using :func:`distanceMultiplier` will +have distances properly compensated in the result :ref:`document`. + +.. code-block:: javascript + + db.runCommand( { geoNear: "places", + near: [ -74, 40.74 ], + maxDistance: { 100 }, + spherical: true, + distanceMultiplier: 3963.192 + } ) + + Multi-location Documents ------------------------ @@ -418,7 +459,7 @@ coordinates. Consider the following prototype data model: ] } -Then, create the geospatial index on the ``addresses.lock`` field as +Then, create the geospatial index on the ``addresses.loc`` field as in the following example: .. code-block:: javascript From d66306893fedfaa7eb74d808c24997938741c79b Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 19 Jul 2012 11:55:30 -0400 Subject: [PATCH 02/17] editied geospatial core --- draft/core/geospatial-indexes.txt | 66 +++++++++++++++---------------- 1 file changed, 32 insertions(+), 34 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 824e97ce37f..ede3a7f826f 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -8,15 +8,15 @@ Overview -------- MongoDB supports location-based queries and geospatial data with a -special index for coordinate data. The index stores :ref:`geohashes +special index for coordinate data. The geospatial index stores :ref:`geohashes `, and makes it possible to return documents based on proximity to a point or within a bounded region. Geospatial -queries support coordinate systems on either flat and spherical planes. +queries support coordinate systems on either flat and spherical surfaces. Additionally, geospatial haystack indexes provide additional support for certain classes of region-based queries. This document introduces the core concepts -that underpin geospatial queries and indexes in MongoDB. For more +that underpin geospatial queries and indexes in MongoDB. For more information, :doc:`/applications/geospatial-indexes` provide complete documentation of all location-based operations and queries. @@ -31,7 +31,7 @@ Geospatial Indexes location data in MongoDB. To use geospatial functions in MongoDB, model -location data in a 2D array and create an index using the +location data in a 2D array tehen create an index using the :func:`ensureIndex ` method on this field using the ``2d`` option. Consider the following prototype operation: @@ -39,10 +39,11 @@ using the ``2d`` option. Consider the following prototype operation: db.collection.ensureIndex( { : "2d" } ) -All queries using coordinates will use this geospatial index. -The index uses a :term:`geohash` calculated from the coordinates. -For more information on :term:`geohash`, please refer to the -:ref:`geohash ` section. +After the ``2d`` index has been created, all queries using coordinates +will use this geospatial index. The index uses a :term:`geohash` +calculated from the coordinates. For more information on +:term:`geohash`, please refer to the :ref:`geohash +` section. .. note:: @@ -56,13 +57,13 @@ For more information on :term:`geohash`, please refer to the Range ~~~~~ -All geospatial indexes are bounded. MongoDB will return an error and -reject documents with coordinate pairs outside of these -boundaries. The default boundaries assume latitude and -longitude data, and are -between -180 inclusive and 180 non-inclusive. +All geospatial indexes are bounded to a certain range. MongoDB will +return an error and reject documents with coordinate pairs outside of +the specified range. The default range assume latitude and longitude +data, and are between -180 inclusive and 180 +non-inclusive. (i.e. ``[-180, 180)`` ) -To configure the boundaries of a geospatial index, use the ``min`` and +To configure the range of a geospatial index, use the ``min`` and ``max`` options with the :func:`ensureIndex() ` operation, as in the following prototype. @@ -72,7 +73,7 @@ operation, as in the following prototype. { min: , max: } ) The following operation will create an index on the ``places`` -collection, for coordinates in the ``loc`` field, with boundaries +collection, for coordinates in the ``loc`` field, with a range between ``-90`` and ``90``: .. code-block:: javascript @@ -133,7 +134,7 @@ These indexes support regular geospatial queries as well as queries where you mu location and by another field. For example, if you need to return a list of restaurants near a given point, but you want to optionally filter restaurants by type, such as "take-out," or -"bar" stored in a ``type`` field. +"bar" stored in the ``type`` field. .. note:: @@ -148,15 +149,10 @@ filter restaurants by type, such as "take-out," or Haystack Index ~~~~~~~~~~~~~~ -Geospatial haystack indexes make it possible to build a special -``bucket`` for keys in the index to tune the distribution of data. Haystack -indexes improve query performance for queries limited to a specific -area. For more information, please refer to :doc:`Geospatial Indexes -`. - -To improve query performance when filtering geospatial -results along another dimension, consider -using a :ref:`compound index `. +Geospatial haystack indexes make it possible for you to tune the +distribution of your data and build a special ``bucket`` +index. Haystack indexes improve query performance for queries limited +to a specific area. .. note:: @@ -164,10 +160,14 @@ using a :ref:`compound index `. a particular location, as the closest documents could be far away compared to the bucket size. +To improve query performance when filtering geospatial results along +another dimension, consider using a :ref:`compound index +`. + To build a :term:`geoHaystack` index, specify the ``geoHaystack`` for the location field and a ``bucketSize`` parameter . The ``bucketSize`` parameter determines the granularity of the bucket index. A -``bucketSize`` of 1 creates an index that stores keys within a single unit +``bucketSize`` of ``1`` creates an index that stores keys within a single unit in the coordinate in the same bucket. .. code-block:: javascript @@ -180,7 +180,7 @@ documents. In the following example, the :func:`ensureIndex() ` method creates an index that would support -a query that: returned all locations (e.g. restaurants) in the +a query that returned all locations (e.g. restaurants) in the ``places`` collection within a maximum distance of 2 degrees longitude or latitude. Create this index using following command: @@ -189,9 +189,6 @@ or latitude. Create this index using following command: db.places.ensureIndex({ loc: "geoHaystack", type: 1} , { bucketSize: 2 } ) -.. TODO clarify what the type argument does or if it's just always - required. - .. _geospatial-spherical-representation: Spatial Representation Systems @@ -232,7 +229,7 @@ two bit representation of four quadrants would be: 00 10 These two bit values, ``00``, ``01``, ``10``, and ``11``, represent -each of the quadrants, and points within that quadrant. For a geohash +each of the quadrants, and points within that quadrant. For a :term:`geohash` with two bits of resolution, a point in the top left quadrant would have the geohash of ``01``. @@ -241,10 +238,11 @@ sub-quadrants. To identify quadrants within a sub-quadrant, take the containing quadrant (e.g. ``01``) and concatenate the identifier for the sub-quadrant. Therefore, for the upper-right quadrant, ``11``, the sub-quadrants would be: -``1101``, ``1111``, ``1110``, and ``1100``. +``1101`` (top-center), ``1111`` (top-left), ``1110`` (right-center), +and ``1100`` (center). -To calculate a more precise geohash, continue dividing the -sub-quadrant concatenate the two-bit identifier for each division. The +To calculate a more precise :term:`geohash`, continue dividing the +sub-quadrant, concatenate the two-bit identifier for each division. The more "bits" in the hash identifier for a given point, the smaller possible area that the hash can describe, and the higher the resolution of the geospatial index. From eda305be9ada5e074a81a046d67e3cf4d61900a9 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 19 Jul 2012 14:22:25 -0400 Subject: [PATCH 03/17] geospatial index update - geoSearch draft --- draft/applications/geospatial-indexes.txt | 39 ++++++++++++++++++++++- draft/core/geospatial-indexes.txt | 8 +++++ 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 33a74375c17..ec3c38dab3a 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -384,7 +384,8 @@ their distance from the ``[ -74, 40.74 ]`` point. between ``-180`` inclusive, and ``180``, valid values for latitude are between ``-90`` and ``90``. -.. TODO add in distanceMultiplier description +Distance Multiplier +~~~~~~~~~~~~~~~~~~~ :func:`distanceMultiplier` is a built-in function which will automatically multiply distances in spherical queries by the assigned @@ -400,6 +401,42 @@ have distances properly compensated in the result :ref:`document`. distanceMultiplier: 3963.192 } ) +.. TODO can be used with normal find() query too (i.e. for zooming) + +.. _geospatial-haystack-queries: + +Querying Haystack Indexes +------------------------- + +Once the the :ref:`haystack index ` has +been built, you must use the :dbcommand:`geoSearch` to query the +haystack index. + +the following prototype: + +.. code-block:: javascript + + db.runCommand( { geoSearch: , + search: { : } } ) + +For example: + +.. code-block:: javascript + + db.runCommand( { geoSearch: "places", + search: { type: "restaurant" }, + near: [-74, 40.74] } ) + + +To create geospatial indexes with the haystack option, please see: +:ref:`Haystack Index ` + +:ref:`Spherical queries ` are not +currently supported by haystack indexes. + +A geospatial haystack index can *only* be queried using +the :dbcommand:`geoSearch` command. + Multi-location Documents ------------------------ diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index ede3a7f826f..cf9efc934e4 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -189,6 +189,14 @@ or latitude. Create this index using following command: db.places.ensureIndex({ loc: "geoHaystack", type: 1} , { bucketSize: 2 } ) +To query geohaystack indexes, you *must* use the :dbcommand:`geoSearch` +command, please see the :ref:`Querying Haystack Indexes +` section. + +:ref:`Spherical queries ` are not +currently supported by haystack indexes. + + .. _geospatial-spherical-representation: Spatial Representation Systems From 22a03912855df2eea15f6918931009b43251194a Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 20 Jul 2012 13:43:37 -0400 Subject: [PATCH 04/17] quick changes --- draft/applications/geospatial-indexes.txt | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index ec3c38dab3a..45bd30e8b95 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -307,9 +307,7 @@ polygon connects at the above points using a geospatial index on the Spherical ~~~~~~~~~ -.. TODO make the 'documents' here refer to the MongoDB term. How? - -If the coordinates in your :ref:`documents ` represent points on a +If the coordinates in your :term:`documents` represent points on a spherical surface, :ref:`proximity ` and some :ref:`bounded ` queries will not return accurate results. To compensate, you can use the following spherical @@ -408,24 +406,24 @@ have distances properly compensated in the result :ref:`document`. Querying Haystack Indexes ------------------------- -Once the the :ref:`haystack index ` has -been built, you must use the :dbcommand:`geoSearch` to query the -haystack index. +To query the :ref:`geospatial haystack index +`, you must use the +:dbcommand:`geoSearch`. the following prototype: .. code-block:: javascript db.runCommand( { geoSearch: , - search: { : } } ) + search: { : } } ) For example: .. code-block:: javascript db.runCommand( { geoSearch: "places", - search: { type: "restaurant" }, - near: [-74, 40.74] } ) + search: { type: "restaurant" }, + near: [-74, 40.74] } ) To create geospatial indexes with the haystack option, please see: From 00b0fac5cb5d7b8cc09a8e61fc4a9a1d0206a210 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 20 Jul 2012 18:09:24 -0400 Subject: [PATCH 05/17] updating distanceMultiplier and geoSearch --- draft/applications/geospatial-indexes.txt | 63 +++++++++++++++-------- 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 45bd30e8b95..ad03df0a6ab 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -299,8 +299,7 @@ polygon connects at the above points using a geospatial index on the .. code-block:: javascript db.places.find({ "loc": { "$within": { "$polygon": - [0,0], [3,3], [6,0] - } } }) + [0,0], [3,3], [6,0] } } } ) .. _geospatial-query-spherical: @@ -354,7 +353,10 @@ with a radius of ``100`` miles: Remember that you must convert the distance of the radius to radians. This conversion *must* happen in your client -(i.e. application) code. +(i.e. application) code. You may also utilize the +:option:`distanceMultiplier` option to have the conversion happen on +the server code. Please see the :ref:`distance multiplier +` section. The following spherical proximity query, returns all documents in the collection ``places`` within ``100`` miles from the point ``[ -74, @@ -382,58 +384,75 @@ their distance from the ``[ -74, 40.74 ]`` point. between ``-180`` inclusive, and ``180``, valid values for latitude are between ``-90`` and ``90``. +.. _geospatial-distance-multiplier: + Distance Multiplier ~~~~~~~~~~~~~~~~~~~ -:func:`distanceMultiplier` is a built-in function which will -automatically multiply distances in spherical queries by the assigned -value. All spherical queries using :func:`distanceMultiplier` will -have distances properly compensated in the result :ref:`document`. +:option:`distanceMultiplier` is an option that will automatically +multiply distances in :term:`documents ` returned by the assigned +value. + +The :option:`distanceMultiplier` is useful when working with :ref:`spherical queries +`. :ref:`Documents ` returned +from spherical queries can be multiplied from radians to distance, so there is no need +to perform the conversion in another function. + +:option:`distanceMultiplier` can be useful for multiplying distance +values of result documents to match a particular view settings. + +The following example uses :option:`distanceMultiplier` in geoNear +with a spherical example: .. code-block:: javascript db.runCommand( { geoNear: "places", near: [ -74, 40.74 ], - maxDistance: { 100 }, + maxDistance: { 100 / 3963.192 }, spherical: true, distanceMultiplier: 3963.192 } ) -.. TODO can be used with normal find() query too (i.e. for zooming) +.. seealso:: + :ref:`geospatial-query-distance` .. _geospatial-haystack-queries: Querying Haystack Indexes ------------------------- -To query the :ref:`geospatial haystack index -`, you must use the -:dbcommand:`geoSearch`. +:ref:`Geospatial haystack indexes ` are +useful to optimize your location data for certain ``bucketsize`` with +another field. To utilize the haystack indexes with your queries, you must use +the :dbcommand:`geoSearch` command with another field. The +:func:`find() ` and :dbcommand:`geoFind` will +not use the haystack index. -the following prototype: +The :dbcommand:`geoSearch` has the following prototype: .. code-block:: javascript db.runCommand( { geoSearch: , search: { : } } ) -For example: +For example, to find all the ``restaurants`` within the pre-indexed ``bucketsize`` in +the ``places`` collection near a particular point, the command would be: .. code-block:: javascript - db.runCommand( { geoSearch: "places", - search: { type: "restaurant" }, + db.runCommand( { geoSearch: "places", + search: { type: "restaurant" }, near: [-74, 40.74] } ) -To create geospatial indexes with the haystack option, please see: -:ref:`Haystack Index ` +To create geospatial indexes with the haystack option and a particular +``bucketsize``, please see: :ref:`Haystack Index +` -:ref:`Spherical queries ` are not -currently supported by haystack indexes. +.. note:: -A geospatial haystack index can *only* be queried using -the :dbcommand:`geoSearch` command. + :ref:`Spherical queries ` are + not currently supported by haystack indexes. Multi-location Documents From b27b3bad0bb83245b100a6cae9e43edf87d4e5d4 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 23 Jul 2012 16:06:07 -0400 Subject: [PATCH 06/17] fixing up bucketSize and added warning for haystack --- draft/applications/geospatial-indexes.txt | 18 +++++++++++++----- draft/core/geospatial-indexes.txt | 2 +- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index ad03df0a6ab..0eb09492b81 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -389,7 +389,7 @@ their distance from the ``[ -74, 40.74 ]`` point. Distance Multiplier ~~~~~~~~~~~~~~~~~~~ -:option:`distanceMultiplier` is an option that will automatically +``distanceMultiplier`` is an option that will automatically multiply distances in :term:`documents ` returned by the assigned value. @@ -401,8 +401,8 @@ to perform the conversion in another function. :option:`distanceMultiplier` can be useful for multiplying distance values of result documents to match a particular view settings. -The following example uses :option:`distanceMultiplier` in geoNear -with a spherical example: +The following example uses ``distanceMultiplier`` in :dbcommand:`geoNear` +with a :ref:`spherical ` example: .. code-block:: javascript @@ -422,8 +422,16 @@ Querying Haystack Indexes ------------------------- :ref:`Geospatial haystack indexes ` are -useful to optimize your location data for certain ``bucketsize`` with -another field. To utilize the haystack indexes with your queries, you must use +useful to optimize your location data for certain ``bucketSize`` with +another field. + +.. note:: + + Haystack indexes are not suited to returning the closest documents to + a particular location, as the closest documents could be far away + compared to the ``bucketSize``. + +To utilize the haystack indexes with your queries, you must use the :dbcommand:`geoSearch` command with another field. The :func:`find() ` and :dbcommand:`geoFind` will not use the haystack index. diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index cf9efc934e4..489124d6b57 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -158,7 +158,7 @@ to a specific area. Haystack indexes are not suited to returning the closest documents to a particular location, as the closest documents could be far away - compared to the bucket size. + compared to the ``bucketSize``. To improve query performance when filtering geospatial results along another dimension, consider using a :ref:`compound index From bc51e16a8731a4e6ea770f6ac927203179339899 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 24 Jul 2012 10:54:40 -0400 Subject: [PATCH 07/17] proof reading edits --- draft/applications/geospatial-indexes.txt | 70 +++++++++++----------- draft/core/geospatial-indexes.txt | 48 +++++++-------- source/includes/geospatial-coordinates.rst | 2 +- 3 files changed, 61 insertions(+), 59 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 0eb09492b81..b7ddbd31170 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -26,7 +26,7 @@ Queries MongoDB provides special :ref:`geospatial query operators ` for performing queries on location data -inside the normal :func:`find() ` operator. The +inside the normal :func:`find() ` method. The :dbcommand:`geoNear` command also returns results using geospatial indexes, but also includes additional geospatial information in the return documents. @@ -133,7 +133,7 @@ the prototype operation. db.collection.find( { : { $near: [ x, y ] } } ).limit(n) -The following example will return only ``20`` results of the above query: +The following example will return only 20 results of the above query: .. code-block:: javascript @@ -153,12 +153,11 @@ in the previous example: db.runCommand( { geoNear: "collection", near: [ -74, 40.74 ], num: 20 } ) -The :func:`limit() ` and :operator:`near` do not limit +The :func:`limit() ` method and :operator:`near` method do not limit geospatial query results by distance, only the number of returned :term:`documents`. To limit geospatial search results by distance, please see the :ref:`geospatial-query-distance` section. -.. index:: $maxDistance .. index:: geospatial queries; distance limit .. _geospatial-query-distance: @@ -187,7 +186,7 @@ as the coordinate system specified. For example, if the indexed location data is in meters, the distance units are also in meters. To limit geospatial query results by the number of returned -:term:`documents`, please see the :ref:`geospatial-query-limit` section. +:term:`document`, please see the :ref:`geospatial-query-limit` section. .. _geospatial-within: .. _geospatial-query-bounded: @@ -306,7 +305,7 @@ polygon connects at the above points using a geospatial index on the Spherical ~~~~~~~~~ -If the coordinates in your :term:`documents` represent points on a +If the coordinates in your :term:`document` represent points on a spherical surface, :ref:`proximity ` and some :ref:`bounded ` queries will not return accurate results. To compensate, you can use the following spherical @@ -320,7 +319,7 @@ list of spherical query operators and their flat surface equivalents: :operator:`$centerSphere` :operator:`$center` ========================== =================== -The :dbcommand:`geoNear` will return results for spherical surface if +The :dbcommand:`geoNear` will return results assuming a spherical surface if you specify the ``{ spherical: true }`` option to the command. .. admonition:: Spherical Queries Use Radians for Distance @@ -353,8 +352,8 @@ with a radius of ``100`` miles: Remember that you must convert the distance of the radius to radians. This conversion *must* happen in your client -(i.e. application) code. You may also utilize the -:option:`distanceMultiplier` option to have the conversion happen on +(i.e. application) code. You may also use the +``distanceMultiplier`` option to the :dbcommand:`geoNear` to convert on the server code. Please see the :ref:`distance multiplier ` section. @@ -389,20 +388,27 @@ their distance from the ``[ -74, 40.74 ]`` point. Distance Multiplier ~~~~~~~~~~~~~~~~~~~ -``distanceMultiplier`` is an option that will automatically -multiply distances in :term:`documents ` returned by the assigned -value. +The ``distanceMultiplier`` option multiplies all distances values in +the ``distance`` field returned by :dbcommand:`geoNear` command by an +assigned value. -The :option:`distanceMultiplier` is useful when working with :ref:`spherical queries -`. :ref:`Documents ` returned -from spherical queries can be multiplied from radians to distance, so there is no need -to perform the conversion in another function. +This option is useful when working with :ref:`spherical queries +`. Distances in the ``distance`` field of +:dbcommand:`geoNear` queried documents can be multiplied by the proper +radians to distances ratio before the query returns. Thus, the +``distance`` field will contain distance values instead of radian +values for spherical queries. -:option:`distanceMultiplier` can be useful for multiplying distance -values of result documents to match a particular view settings. +.. note:: + + Because ``distanceMultiplier`` is an option to + :dbcommand:`geoNear`, the multiplication operation occurs on the + :program:`mongod` process. This multiplication operation will add a + slight computational load to the server. -The following example uses ``distanceMultiplier`` in :dbcommand:`geoNear` -with a :ref:`spherical ` example: +The following example uses ``distanceMultiplier`` in the +:dbcommand:`geoNear` command with a :ref:`spherical +` example: .. code-block:: javascript @@ -414,16 +420,17 @@ with a :ref:`spherical ` example: } ) .. seealso:: - :ref:`geospatial-query-distance` + :ref:`Distance operator ` .. _geospatial-haystack-queries: Querying Haystack Indexes ------------------------- -:ref:`Geospatial haystack indexes ` are -useful to optimize your location data for certain ``bucketSize`` with -another field. +Geospatial haystack indexes are a special geospatial index that can +optimize your location data with another field. To create geospatial +indexes with the haystack option and a particular ``bucketSize``, +please see: :ref:`Haystack Index ` .. note:: @@ -431,20 +438,20 @@ another field. a particular location, as the closest documents could be far away compared to the ``bucketSize``. -To utilize the haystack indexes with your queries, you must use +To utilize the haystack index with your queries, you must use the :dbcommand:`geoSearch` command with another field. The -:func:`find() ` and :dbcommand:`geoFind` will +:func:`find() ` method and :dbcommand:`geoNear` will not use the haystack index. -The :dbcommand:`geoSearch` has the following prototype: +The :dbcommand:`geoSearch` has the following prototype form: .. code-block:: javascript db.runCommand( { geoSearch: , search: { : } } ) -For example, to find all the ``restaurants`` within the pre-indexed ``bucketsize`` in -the ``places`` collection near a particular point, the command would be: +For example, to return all documents with the value +``restaurants`` in the ``type`` field near the example point, the command would resemble: .. code-block:: javascript @@ -452,11 +459,6 @@ the ``places`` collection near a particular point, the command would be: search: { type: "restaurant" }, near: [-74, 40.74] } ) - -To create geospatial indexes with the haystack option and a particular -``bucketsize``, please see: :ref:`Haystack Index -` - .. note:: :ref:`Spherical queries ` are diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 489124d6b57..4765bae6e0d 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -31,7 +31,7 @@ Geospatial Indexes location data in MongoDB. To use geospatial functions in MongoDB, model -location data in a 2D array tehen create an index using the +location data in a 2D array then create an index using the :func:`ensureIndex ` method on this field using the ``2d`` option. Consider the following prototype operation: @@ -45,11 +45,14 @@ calculated from the coordinates. For more information on :term:`geohash`, please refer to the :ref:`geohash ` section. +To perform queries on your geospatial data, please see +:doc:`/applications/geospatial-indexes`. + .. note:: MongoDB only supports *one* geospatial index per collection. As with any MongoDB index, any single query can only - use one index. Creating more than one geospatial index to a + use one index. Creating more than one geospatial index with a collection will produce unexpected results. .. _geospatial-indexes-range: @@ -57,11 +60,11 @@ calculated from the coordinates. For more information on Range ~~~~~ -All geospatial indexes are bounded to a certain range. MongoDB will -return an error and reject documents with coordinate pairs outside of -the specified range. The default range assume latitude and longitude +All geospatial indexes are bounded. MongoDB will +return an error and reject documents with coordinate data outside of +the specified range. The default range assumes latitude and longitude data, and are between -180 inclusive and 180 -non-inclusive. (i.e. ``[-180, 180)`` ) +non-inclusive (i.e. ``[-180, 180)``.) To configure the range of a geospatial index, use the ``min`` and ``max`` options with the :func:`ensureIndex() ` @@ -73,7 +76,7 @@ operation, as in the following prototype. { min: , max: } ) The following operation will create an index on the ``places`` -collection, for coordinates in the ``loc`` field, with a range +collection, for coordinates in the ``loc`` field, with the range between ``-90`` and ``90``: .. code-block:: javascript @@ -82,7 +85,7 @@ between ``-90`` and ``90``: { min: 90 , max: 90 } ) For more information see the :ref:`geospatial precision -` and :ref:`rehashes +` and :ref:`geohash ` sections. .. _geospatial-indexes-precision: @@ -90,8 +93,8 @@ For more information see the :ref:`geospatial precision Precision ~~~~~~~~~ -Geospatial indexes represent precision, or resolution in -"bits". Higher bit values allow MongoDB to return more precise +Geospatial indexes use "bits" to represent precision, or +resolution. Higher bit values allow MongoDB to return more precise results, at the expense of speed. For more information on the relationship between bits and precision, see the :ref:`geohash ` section. @@ -99,7 +102,7 @@ relationship between bits and precision, see the :ref:`geohash By default, geospatial indexes in MongoDB have 26 bits of precision, although precision is configurable upon index creation and MongoDB supports up to 32 bits of precision. With 26 bits of precision, using -the default range of -180 to 180, results can be precise to roughly 2 +the default range of -180 to 180, geospatial data can be precise to roughly 2 feet or about 60 centimeters. You can set the precision of a geospatial index during creation by @@ -149,8 +152,8 @@ filter restaurants by type, such as "take-out," or Haystack Index ~~~~~~~~~~~~~~ -Geospatial haystack indexes make it possible for you to tune the -distribution of your data and build a special ``bucket`` +Geospatial haystack indexes make it possible to tune the +distribution of your data and build a special bucket index. Haystack indexes improve query performance for queries limited to a specific area. @@ -160,10 +163,6 @@ to a specific area. a particular location, as the closest documents could be far away compared to the ``bucketSize``. -To improve query performance when filtering geospatial results along -another dimension, consider using a :ref:`compound index -`. - To build a :term:`geoHaystack` index, specify the ``geoHaystack`` for the location field and a ``bucketSize`` parameter . The ``bucketSize`` parameter determines the granularity of the bucket index. A @@ -186,7 +185,7 @@ or latitude. Create this index using following command: .. code-block:: javascript - db.places.ensureIndex({ loc: "geoHaystack", type: 1} , + db.places.ensureIndex({ loc: "geoHaystack", type: 1}, { bucketSize: 2 } ) To query geohaystack indexes, you *must* use the :dbcommand:`geoSearch` @@ -194,7 +193,7 @@ command, please see the :ref:`Querying Haystack Indexes ` section. :ref:`Spherical queries ` are not -currently supported by haystack indexes. +supported by haystack indexes. .. _geospatial-spherical-representation: @@ -237,17 +236,18 @@ two bit representation of four quadrants would be: 00 10 These two bit values, ``00``, ``01``, ``10``, and ``11``, represent -each of the quadrants, and points within that quadrant. For a :term:`geohash` -with two bits of resolution, a point in the top left quadrant would -have the geohash of ``01``. +each of the quadrants, and points within that quadrant. For a +:term:`geohash` with two bits of resolution, a point in the bottom +left quadrant would have a geohash of ``00``. The top left quadrant +would have the geohash of ``01``. The bottom right and top right would +have a geohash of ``10`` and ``11``, respectively. To provide additional precision, continue dividing each quadrant into sub-quadrants. To identify quadrants within a sub-quadrant, take the containing quadrant (e.g. ``01``) and concatenate the identifier for the sub-quadrant. Therefore, for the upper-right quadrant, ``11``, the sub-quadrants would be: -``1101`` (top-center), ``1111`` (top-left), ``1110`` (right-center), -and ``1100`` (center). +``1101``, ``1111``, ``1110``, and ``1100``. To calculate a more precise :term:`geohash`, continue dividing the sub-quadrant, concatenate the two-bit identifier for each division. The diff --git a/source/includes/geospatial-coordinates.rst b/source/includes/geospatial-coordinates.rst index ba910f66fff..4dbc031e302 100644 --- a/source/includes/geospatial-coordinates.rst +++ b/source/includes/geospatial-coordinates.rst @@ -9,7 +9,7 @@ that holds a 2 dimensional array. The preferred form is: [ x, y ] Consistency is crucial: all documents must store the values in the -same order. you may also use an embeded document, as in: +same order. You may also use an embeded document, as in: .. code-block:: javascript From 216dc4e9700ec655496237a3e520df882d23f0d9 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 24 Jul 2012 11:03:32 -0400 Subject: [PATCH 08/17] rewording geohash example --- draft/core/geospatial-indexes.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 4765bae6e0d..22785bcb048 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -244,9 +244,9 @@ have a geohash of ``10`` and ``11``, respectively. To provide additional precision, continue dividing each quadrant into sub-quadrants. To identify quadrants within a sub-quadrant, take the -containing quadrant (e.g. ``01``) and concatenate the identifier for -the sub-quadrant. Therefore, for -the upper-right quadrant, ``11``, the sub-quadrants would be: +geohash for the containing quadrant (e.g. ``01``) and concatenate the geohash for +the sub-quadrant. Therefore, the geohash for +the upper-right quadrant is ``11``, the geohash for the sub-quadrants would be: ``1101``, ``1111``, ``1110``, and ``1100``. To calculate a more precise :term:`geohash`, continue dividing the From 8dcab2645cbba94336149d3479c134b09b341e30 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 24 Jul 2012 11:45:35 -0400 Subject: [PATCH 09/17] proof reading geo apps --- draft/applications/geospatial-indexes.txt | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index b7ddbd31170..bc509977172 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -9,7 +9,7 @@ based on location with a special geospatial index type. This document introduces geospatial data modeling, indexing operations, and provides example queries using the :ref:`geospatial query operators `. For more information about -geospatial indexes and operations see the :doc:`/applications/geospatial-indexes` document. +geospatial indexes and operations see the :doc:`/core/geospatial-indexes` document. .. _geospatial-coordinates: @@ -158,6 +158,15 @@ geospatial query results by distance, only the number of returned :term:`documents`. To limit geospatial search results by distance, please see the :ref:`geospatial-query-distance` section. +.. note:: + + The :func:`limit() ` method and ``num`` option have + different performance characteristics. Geospatial queries with + :func:`limit() ` method will return 100 documents, + sort them, and finally the limit method is applied. Geospatial + queries with ``num`` option will only return the specified number + of documents unsorted. + .. index:: geospatial queries; distance limit .. _geospatial-query-distance: @@ -395,9 +404,9 @@ assigned value. This option is useful when working with :ref:`spherical queries `. Distances in the ``distance`` field of :dbcommand:`geoNear` queried documents can be multiplied by the proper -radians to distances ratio before the query returns. Thus, the -``distance`` field will contain distance values instead of radian -values for spherical queries. +radians to distances ratio before the query returns. For spherical +queries, the ``distance`` field will contain distance values instead +of radian values when properly used with ``distanceMultiplier``. .. note:: From 93980b17964ca21cab425b1d607090d8bcc0de4e Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 25 Jul 2012 18:01:59 -0400 Subject: [PATCH 10/17] hopefully final draft of geo docs --- draft/applications/geospatial-indexes.txt | 85 ++++++++++++----------- draft/core/geospatial-indexes.txt | 2 +- 2 files changed, 46 insertions(+), 41 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index bc509977172..4666b889547 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -127,7 +127,7 @@ By default, geospatial queries with :func:`find() ` return 100 documents. To impose a limit on the result set, use the :func:`limit() ` method with :func:`find() ` operator. The following is -the prototype operation. +the prototype operation: .. code-block:: javascript @@ -139,8 +139,8 @@ The following example will return only 20 results of the above query: db.places.find( { loc: { $near: [ -74, 40.74 ] } } ).limit(20) -You may also use the ``num`` option with the :dbcommand:`geoNear` near -command, as in the following prototype: +You may also use the ``num`` option with the :dbcommand:`geoNear` +command and the ``near`` parameter, as in the following prototype: .. code-block:: javascript @@ -153,9 +153,9 @@ in the previous example: db.runCommand( { geoNear: "collection", near: [ -74, 40.74 ], num: 20 } ) -The :func:`limit() ` method and :operator:`near` method do not limit +The :func:`limit() ` method and ``near`` parameter do not limit geospatial query results by distance, only the number of returned -:term:`documents`. To limit geospatial search results by distance, +:term:`document`. To limit geospatial search results by distance, please see the :ref:`geospatial-query-distance` section. .. note:: @@ -194,8 +194,8 @@ Specify the distance in the ``maxDistance`` option using the same units as the coordinate system specified. For example, if the indexed location data is in meters, the distance units are also in meters. -To limit geospatial query results by the number of returned -:term:`document`, please see the :ref:`geospatial-query-limit` section. +See the :ref:`geospatial-query-limit` section to limit geospatial +query results by the number of returned :term:`documents `. .. _geospatial-within: .. _geospatial-query-bounded: @@ -203,11 +203,10 @@ To limit geospatial query results by the number of returned Bounded ~~~~~~~ -Bounded queries return results within the boundaries of a specified shape -in the query. The :operator:`$within` operator allows you to -construct these queries. Bounded queries do not return sorted results, -as a result these queries are faster than :ref:`proximity -` queries. +Bounded queries return documents that have coordinates within a shape +specified in the query. Bounded queries, using the :operator:`$within` +operator do not return sorted results and are faster than +:ref:`proximity queries ` Using the :operator:`$within`, you can specify boundaries with the following shapes: @@ -226,8 +225,8 @@ Bounded queries take the following prototype form: } } ) -To perform geospatial queries for a particular distance around a -certain point, please see the :ref:`geospatial-query-distance` section. +See the :ref:`geospatial-query-distance` section to perform geospatial +queries for a particular distance around a certain point. The following sections provide examples of bounded queries using the :operator:`$within` operator. @@ -318,7 +317,7 @@ If the coordinates in your :term:`document` represent points on a spherical surface, :ref:`proximity ` and some :ref:`bounded ` queries will not return accurate results. To compensate, you can use the following spherical -queries which adjust for these differences. The following table provides a +queries that adjust for these differences. The following table provides a list of spherical query operators and their flat surface equivalents: ========================== =================== @@ -328,8 +327,8 @@ list of spherical query operators and their flat surface equivalents: :operator:`$centerSphere` :operator:`$center` ========================== =================== -The :dbcommand:`geoNear` will return results assuming a spherical surface if -you specify the ``{ spherical: true }`` option to the command. +The :dbcommand:`geoNear` command returns documents assuming a spherical surface if +you specify the ``{ spherical: true }`` option. .. admonition:: Spherical Queries Use Radians for Distance @@ -361,10 +360,10 @@ with a radius of ``100`` miles: Remember that you must convert the distance of the radius to radians. This conversion *must* happen in your client -(i.e. application) code. You may also use the -``distanceMultiplier`` option to the :dbcommand:`geoNear` to convert on -the server code. Please see the :ref:`distance multiplier -` section. +(i.e. application) code. You may also use the ``distanceMultiplier`` +option to the :dbcommand:`geoNear` to convert in the :program:`mongod` +process, rather than in your application code. Please see the +:ref:`distance multiplier ` section. The following spherical proximity query, returns all documents in the collection ``places`` within ``100`` miles from the point ``[ -74, @@ -397,24 +396,29 @@ their distance from the ``[ -74, 40.74 ]`` point. Distance Multiplier ~~~~~~~~~~~~~~~~~~~ -The ``distanceMultiplier`` option multiplies all distances values in +The ``distanceMultiplier`` option multiplies all distance values in the ``distance`` field returned by :dbcommand:`geoNear` command by an assigned value. -This option is useful when working with :ref:`spherical queries -`. Distances in the ``distance`` field of -:dbcommand:`geoNear` queried documents can be multiplied by the proper -radians to distances ratio before the query returns. For spherical -queries, the ``distance`` field will contain distance values instead -of radian values when properly used with ``distanceMultiplier``. +.. TODO refactor paragraph again. +Use this option with :ref:`spherical queries +` to convert the contents of the +``distance`` field returned in the extra output of the +:dbcommand:`geoNear` command from radians to distances. Distances in +the ``distance`` field of :dbcommand:`geoNear` queried documents can +be multiplied by the proper radians to distances ratio before the +query returns. For spherical queries, the ``distance`` field will +contain distance values instead of radian values when properly used +with ``distanceMultiplier``. .. note:: Because ``distanceMultiplier`` is an option to :dbcommand:`geoNear`, the multiplication operation occurs on the - :program:`mongod` process. This multiplication operation will add a - slight computational load to the server. + :program:`mongod` process. The operation adds a slight overhead to + the operation of :dbcommand:`geoNear`. +.. TODO add in results & why would one run it The following example uses ``distanceMultiplier`` in the :dbcommand:`geoNear` command with a :ref:`spherical ` example: @@ -436,10 +440,12 @@ The following example uses ``distanceMultiplier`` in the Querying Haystack Indexes ------------------------- -Geospatial haystack indexes are a special geospatial index that can -optimize your location data with another field. To create geospatial -indexes with the haystack option and a particular ``bucketSize``, -please see: :ref:`Haystack Index ` +Geospatial haystack indexes are a special geospatial index that that +allows MongoDB to optimize the query process for location queries, +given a coordinate and another field in your documents. To create +geospatial indexes with the haystack option and a particular +``bucketSize``, please see: :ref:`Haystack Index +` .. note:: @@ -447,12 +453,11 @@ please see: :ref:`Haystack Index ` a particular location, as the closest documents could be far away compared to the ``bucketSize``. -To utilize the haystack index with your queries, you must use -the :dbcommand:`geoSearch` command with another field. The -:func:`find() ` method and :dbcommand:`geoNear` will -not use the haystack index. - -The :dbcommand:`geoSearch` has the following prototype form: +The :dbcommand:`geoSearch` is the only way to return results using the +haystack index: :func:`find() ` and +:dbcommand:`geoNear` cannot access the haystack index. You must +specify both the coordinate and other field to geoSearch, which takes +the following prototypical form: .. code-block:: javascript diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 22785bcb048..5f38ae91caf 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -31,7 +31,7 @@ Geospatial Indexes location data in MongoDB. To use geospatial functions in MongoDB, model -location data in a 2D array then create an index using the +location data in a 2D array, then create an index using the :func:`ensureIndex ` method on this field using the ``2d`` option. Consider the following prototype operation: From 807c1c4c53fbf334524108f8832d3d54936c7d07 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 25 Jul 2012 21:28:40 -0400 Subject: [PATCH 11/17] small update to distanceMultiplier & spherical queries --- draft/applications/geospatial-indexes.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 4666b889547..bc0257be985 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -400,16 +400,12 @@ The ``distanceMultiplier`` option multiplies all distance values in the ``distance`` field returned by :dbcommand:`geoNear` command by an assigned value. -.. TODO refactor paragraph again. -Use this option with :ref:`spherical queries + Use ``distanceMultiplier`` with :ref:`spherical queries ` to convert the contents of the ``distance`` field returned in the extra output of the -:dbcommand:`geoNear` command from radians to distances. Distances in -the ``distance`` field of :dbcommand:`geoNear` queried documents can -be multiplied by the proper radians to distances ratio before the -query returns. For spherical queries, the ``distance`` field will -contain distance values instead of radian values when properly used -with ``distanceMultiplier``. +:dbcommand:`geoNear` command from radians to distances. For more +information about the conversion, see the :ref:`spherical queries +` section. .. note:: @@ -418,8 +414,10 @@ with ``distanceMultiplier``. :program:`mongod` process. The operation adds a slight overhead to the operation of :dbcommand:`geoNear`. -.. TODO add in results & why would one run it -The following example uses ``distanceMultiplier`` in the +.. TODO add in results +Using ``distanceMultiplier`` in spherical queries allows one to use +results from the :dbcommand:`geoNear` command without radian to +distance conversion. The following example uses ``distanceMultiplier`` in the :dbcommand:`geoNear` command with a :ref:`spherical ` example: @@ -432,6 +430,8 @@ The following example uses ``distanceMultiplier`` in the distanceMultiplier: 3963.192 } ) + output: + .. seealso:: :ref:`Distance operator ` From 456c766d13df37ccae2ca0c1d3f2e7b07a0124f6 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 27 Jul 2012 18:35:59 -0400 Subject: [PATCH 12/17] adding in examples for distanceMultiplier & spherical query --- draft/applications/geospatial-indexes.txt | 83 ++++++++++++++++++++++- 1 file changed, 80 insertions(+), 3 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index bc0257be985..bd70bda4077 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -373,10 +373,50 @@ collection ``places`` within ``100`` miles from the point ``[ -74, db.runCommand( { geoNear: "places", near: [ -74, 40.74 ], - maxDistance: { 100 / 3963.192 }, + maxDistance: 100 / 3963.192, spherical: true } ) +The corresponding output: + +.. code-block:: javascript + + { + "ns" : "test.place", + "near" : "0110000111011010011111010100000010011111011110010100", + "results" : [ + { + "dis" : 0.012915436464754133, + "obj" : { + "_id" : ObjectId("501193a5563f26da30f3f378"), + "loc" : [ + -74, + 40 + ] + } + }, + { + "dis" : 0.01853688938212826, + "obj" : { + "_id" : ObjectId("501193a0563f26da30f3f377"), + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + "time" : 0, + "btreelocs" : 0, + "nscanned" : 3, + "objectsLoaded" : 2, + "avgDistance" : 0.015726162923441197, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } + :dbcommand:`geoNear` returns documents in this result set sorted by their distance from the ``[ -74, 40.74 ]`` point. @@ -414,7 +454,6 @@ information about the conversion, see the :ref:`spherical queries :program:`mongod` process. The operation adds a slight overhead to the operation of :dbcommand:`geoNear`. -.. TODO add in results Using ``distanceMultiplier`` in spherical queries allows one to use results from the :dbcommand:`geoNear` command without radian to distance conversion. The following example uses ``distanceMultiplier`` in the @@ -430,7 +469,45 @@ distance conversion. The following example uses ``distanceMultiplier`` in the distanceMultiplier: 3963.192 } ) - output: +The corresponding output: + +.. code-block:: javascript + + { + "ns" : "test.place", + "near" : "0110000111011010011111010100000010011111011110010100", + "results" : [ + { + "dis" : 51.18635447362186, + "obj" : { + "_id" : ObjectId("501193a5563f26da30f3f378"), + "loc" : [ + -74, + 40 + ] + } + }, + { + "dis" : 73.46525170413567, + "obj" : { + "_id" : ObjectId("501193a0563f26da30f3f377"), + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + "time" : 0, + "btreelocs" : 0, + "nscanned" : 3, + "objectsLoaded" : 2, + "avgDistance" : 62.325803088878764, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } .. seealso:: :ref:`Distance operator ` From c2fda9f17af49cd182e4420fa2d2e276d4fdd5db Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 11:17:16 -0400 Subject: [PATCH 13/17] updated examples for distance multiplier and spherical --- draft/applications/geospatial-indexes.txt | 118 ++++++++-------------- 1 file changed, 44 insertions(+), 74 deletions(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index bd70bda4077..fdbe2d9a385 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -373,49 +373,34 @@ collection ``places`` within ``100`` miles from the point ``[ -74, db.runCommand( { geoNear: "places", near: [ -74, 40.74 ], - maxDistance: 100 / 3963.192, spherical: true } ) -The corresponding output: +The output of the above command would be: .. code-block:: javascript - { - "ns" : "test.place", - "near" : "0110000111011010011111010100000010011111011110010100", - "results" : [ - { - "dis" : 0.012915436464754133, - "obj" : { - "_id" : ObjectId("501193a5563f26da30f3f378"), - "loc" : [ - -74, - 40 - ] - } - }, - { - "dis" : 0.01853688938212826, - "obj" : { - "_id" : ObjectId("501193a0563f26da30f3f377"), - "loc" : [ - -73, - 40 - ] - } - } - ], - "stats" : { - "time" : 0, - "btreelocs" : 0, - "nscanned" : 3, - "objectsLoaded" : 2, - "avgDistance" : 0.015726162923441197, - "maxDistance" : 0.01853714811400047 - }, - "ok" : 1 - } + { + // [ ... ] + "results" : [ + { + "dis" : 0.01853688938212826, + "obj" : { + "_id" : ObjectId( ... ) + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + // [ ... ] + "avgDistance" : 0.01853688938212826, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } :dbcommand:`geoNear` returns documents in this result set sorted by their distance from the ``[ -74, 40.74 ]`` point. @@ -464,50 +449,35 @@ distance conversion. The following example uses ``distanceMultiplier`` in the db.runCommand( { geoNear: "places", near: [ -74, 40.74 ], - maxDistance: { 100 / 3963.192 }, spherical: true, distanceMultiplier: 3963.192 } ) -The corresponding output: +The output of the above command would be: .. code-block:: javascript - { - "ns" : "test.place", - "near" : "0110000111011010011111010100000010011111011110010100", - "results" : [ - { - "dis" : 51.18635447362186, - "obj" : { - "_id" : ObjectId("501193a5563f26da30f3f378"), - "loc" : [ - -74, - 40 - ] - } - }, - { - "dis" : 73.46525170413567, - "obj" : { - "_id" : ObjectId("501193a0563f26da30f3f377"), - "loc" : [ - -73, - 40 - ] - } - } - ], - "stats" : { - "time" : 0, - "btreelocs" : 0, - "nscanned" : 3, - "objectsLoaded" : 2, - "avgDistance" : 62.325803088878764, - "maxDistance" : 0.01853714811400047 - }, - "ok" : 1 - } + { + // [ ... ] + "results" : [ + { + "dis" : 73.46525170413567, + "obj" : { + "_id" : ObjectId( ... ) + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + // [ ... ] + "avgDistance" : 0.01853688938212826, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } .. seealso:: :ref:`Distance operator ` From aa8acf2eb0918177349a9eef8fbca8a6d9a994c0 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 1 Aug 2012 14:57:00 -0400 Subject: [PATCH 14/17] removed geoSearch example code. --- draft/core/geospatial-indexes.txt | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 5f38ae91caf..0ce315e0fbb 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -177,17 +177,6 @@ in the coordinate in the same bucket. By default, all queries that use a geospatial haystack index will return 50 documents. -In the following example, the :func:`ensureIndex() -` method creates an index that would support -a query that returned all locations (e.g. restaurants) in the -``places`` collection within a maximum distance of 2 degrees longitude -or latitude. Create this index using following command: - -.. code-block:: javascript - - db.places.ensureIndex({ loc: "geoHaystack", type: 1}, - { bucketSize: 2 } ) - To query geohaystack indexes, you *must* use the :dbcommand:`geoSearch` command, please see the :ref:`Querying Haystack Indexes ` section. From 883e60e5aa94d9abf3262372c7678faaaa85208f Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 1 Aug 2012 19:04:38 -0400 Subject: [PATCH 15/17] adding in includeLocs field --- draft/applications/geospatial-indexes.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index fdbe2d9a385..63e99b084ce 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -525,6 +525,7 @@ For example, to return all documents with the value :ref:`Spherical queries ` are not currently supported by haystack indexes. +.. _geospatial-multi-location: Multi-location Documents ------------------------ @@ -591,6 +592,10 @@ in the following example: db.records.ensureIndex( { "addresses.loc": "2d" } ) +To include the location field with the distance field in +multi-location document queries, specify ``includeLocs: true`` field +in the :dbcommand:`geoNear`. + .. the following is a section about the limitations of geospatial indexes in sharding: From 0c5c1b0f0d6dff0c058042ffc9744832af08a05e Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 1 Aug 2012 19:06:09 -0400 Subject: [PATCH 16/17] touching up includeLocs field --- draft/applications/geospatial-indexes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 63e99b084ce..16830ce4b53 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -594,7 +594,7 @@ in the following example: To include the location field with the distance field in multi-location document queries, specify ``includeLocs: true`` field -in the :dbcommand:`geoNear`. +in the :dbcommand:`geoNear` command. .. the following is a section about the limitations of geospatial indexes in sharding: From 2c02d7b39e386fb3891b04032f253f0e5be7264e Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 2 Aug 2012 15:26:30 -0400 Subject: [PATCH 17/17] minor edit --- draft/applications/geospatial-indexes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 16830ce4b53..96a19c4c096 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -593,7 +593,7 @@ in the following example: db.records.ensureIndex( { "addresses.loc": "2d" } ) To include the location field with the distance field in -multi-location document queries, specify ``includeLocs: true`` field +multi-location document queries, specify ``includeLocs: true`` in the :dbcommand:`geoNear` command. .. the following is a section about the limitations of geospatial