diff --git a/source/applications/geospatial-indexes.txt b/source/applications/geospatial-indexes.txt index 06aa0cd7417..39fd76242f6 100644 --- a/source/applications/geospatial-indexes.txt +++ b/source/applications/geospatial-indexes.txt @@ -68,7 +68,7 @@ following form: .. code-block:: javascript - db.runCommand( { geoNear: "[collection]", near: [ x, y ] } ) + db.runCommand( { geoNear: , near: [ x, y ] } ) .. example:: @@ -132,7 +132,7 @@ To specify distance with the :dbcommand:`geoNear` command, use the .. code-block:: javascript - db.runCommand( { geoNear: "collection", near: [ x, y ], maxDistance: } ) + db.runCommand( { geoNear: , near: [ x, y ], maxDistance: } ) .. _geospatial-indexes-limit: @@ -153,7 +153,7 @@ the ``num`` option. Use the following form: .. code-block:: javascript - db.runCommand( { geoNear: "collection", near: [ x, y ], num: z } ) + db.runCommand( { geoNear: , near: [ x, y ], num: z } ) To limit geospatial search results by distance, see :ref:`geospatial-indexes-distance`. diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt index 91fea9089b0..0d17fadf42e 100644 --- a/source/core/geospatial-indexes.txt +++ b/source/core/geospatial-indexes.txt @@ -9,7 +9,7 @@ Overview ``2d`` geospatial indexes make it possible to associate documents with locations in two-dimensional space, such as a point on a map. MongoDB -interprets two-dimensional coordinates in a location field, as points +interprets two-dimensional coordinates in a location field as points and can index these points in a special index type to support location-based queries. Geospatial indexes provide special geospatial query operators. For example, you can query for documents based on @@ -34,7 +34,7 @@ To use ``2d`` geospatial indexes, you must model location data on a predetermined two-dimensional coordinate system, such as longitude and latitude. You store a document's location data as two coordinates in a field that holds either a two-dimensional array or an embedded -document with two fields. Consider the following two examples: +document with two fields. Consider the following two examples: .. code-block:: javascript @@ -69,7 +69,7 @@ MongoDB's :ref:`geospatial operations data. When you create the index, MongoDB converts location data to binary -:term:`geohash` values, and calculates these values using the location +:term:`geohash` values and calculates these values using the location data and the index's location range, as described in :ref:`geospatial-indexes-range`. The default range for ``2d`` indexes assumes longitude and latitude and uses the bounds -180 inclusive and @@ -110,13 +110,13 @@ Location Precision ``2d`` indexes use a :ref:`geohash ` representation of all coordinate data internally. Geohashes have a -precision, determined by the number of bits in the hash. More bits +precision that is determined by the number of bits in the hash. More bits allow the index to provide results with greater precision, while fewer -bits only the index to provide results with more limited +bits mean the index provides results with more limited precision. Indexes with lower precision have a lower processing overhead for -insert operations and will consume less space; however, higher +insert operations and will consume less space. However, higher precision indexes means that queries will need to scan smaller portions of the index to return results. The actual stored values are always used in the final query processing, and index precision does @@ -143,17 +143,17 @@ Compound Geospatial Indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``2d`` geospatial indexes may be :ref:`compound -`, if an only if the field with location data is +`, if and only if the field with location data is the first field. A compound geospatial index makes it possible to -construct queries that primarily select on a location-based field, but -also select on a second criteria. For example, you could use this kind -of index to support queries for carpet wholesalers within a specific +construct queries that primarily select on a location-based field but +also select on a second criteria. For example, you could use such +an index to support queries for carpet wholesalers within a specific region. .. note:: Geospatial queries will *only* use additional query parameters after applying the geospatial criteria. If your - geospatial query criteria queries select a large number of - documents, the additional query will only filter the result set, + geospatial query criteria selects a large number of + documents, the additional query will only filter the result set and *not* result in a more targeted query. To create a geospatial index with two fields, specify the location field @@ -165,7 +165,7 @@ ascending order), you would issue the following: db.storeInfo.ensureIndex( { loc: "2d", product: 1 } ); -This creates an index that supports queries on the just location field +This creates an index that supports queries on just the location field (i.e. ``loc``), as well as queries on both the ``loc`` and ``product``. @@ -187,7 +187,7 @@ that are within 5 units of the specified longitude and latitude. ``bucketSize`` also determines the granularity of the index. You can tune the parameter to the distribution of your data so that in general you search only very small regions of a two-dimensional -space. Furthermore, the areas defined by buckets can overlap: as a +space. Furthermore, the areas defined by buckets can overlap. As a result a document can exist in multiple buckets. To build a haystack index, use the ``bucketSize`` parameter in the @@ -271,7 +271,7 @@ for geospatial information based on a sphere or earth. ``6378.137`` kilometers. The following query would return documents from the ``places`` -collection, within the circle described by the center ``[ -74, 40.74 ]`` +collection within the circle described by the center ``[ -74, 40.74 ]`` with a radius of ``100`` miles: .. code-block:: javascript @@ -339,10 +339,10 @@ Geohash Values To create a geospatial index, MongoDB computes the :term:`geohash` value for coordinate pairs within the specified :ref:`range -`, and indexes the geohash for that point . +` and indexes the geohash for that point . To calculate a geohash value, continuously divide a 2D map into -quadrants. Then, assign each quadrant a two-bit value. For example, a +quadrants. Then assign each quadrant a two-bit value. For example, a two-bit representation of four quadrants would be: .. code-block:: javascript @@ -351,7 +351,7 @@ two-bit representation of four quadrants would be: 00 10 -These two bit values, ``00``, ``01``, ``10``, and ``11``, represent each +These two-bit values (``00``, ``01``, ``10``, and ``11``) represent each of the quadrants and all points within each quadrant. For a geohash with two bits of resolution, all points in the bottom left quadrant would have a geohash of ``00``. The top left quadrant would have the geohash @@ -376,9 +376,9 @@ Geospatial Indexes and Sharding You *cannot* use a geospatial index as a :term:`shard key` when sharding a collection. However, you *can* create and maintain a -geospatial index on a sharded collection, using a different field as +geospatial index on a sharded collection by using a different field as the shard key. Your application may query for geospatial data using -:dbcommand:`geoNear` and :operator:`$within`; however, queries using +:dbcommand:`geoNear` and :operator:`$within`. However, queries using :operator:`$near` are not supported for sharded collections. .. _geospatial-indexes-multi-location: @@ -390,9 +390,9 @@ Multi-location Documents Support for multiple locations in a document. While ``2d`` indexes do not support more than one set of coordinates in -a document you can use a :ref:`multi-key indexes `, +a document, you can use a :ref:`multi-key indexes ` to store and index multiple coordinate pairs in a single document. In the -simplest example, you may have a field (e.g. ``locs``) that holds an +simplest example you may have a field (e.g. ``locs``) that holds an array of coordinates, as in the following prototype data model: @@ -408,7 +408,7 @@ model: } The values of the array may either be arrays holding coordinates, as -in ``[ 55.5, 42.3 ]`` or embedded documents as in ``{ "lat": 55.3, +in ``[ 55.5, 42.3 ]``, or embedded documents, as in ``{ "lat": 55.3, "long": 40.2 }``. You could then create a geospatial index on the ``locs`` field, as in @@ -419,8 +419,8 @@ the following: db.places.ensureIndex( { "locs": "2d" } ) You may also model the location data as a field inside of a -sub-document. In this case, the document would contain field -(e.g. ``addresses``) that held an array of documents where each +sub-document. In this case, the document would contain a field +(e.g. ``addresses``) that holds an array of documents where each document has a field (e.g. ``loc:``) that holds location coordinates. Consider the following prototype data model: @@ -441,7 +441,7 @@ coordinates. Consider the following prototype data model: ] } -Then, create the geospatial index on the ``addresses.loc`` field as +You could then create the geospatial index on the ``addresses.loc`` field as in the following example: .. code-block:: javascript @@ -449,7 +449,7 @@ in the following example: db.records.ensureIndex( { "addresses.loc": "2d" } ) For documents with multiple coordinate values, queries may return the -same document multiple times, if more than one indexed coordinate pair +same document multiple times if more than one indexed coordinate pair satisfies the query constraints. Use the ``uniqueDocs`` parameter to :dbcommand:`geoNear` or the :operator:`$uniqueDocs` operator in conjunction with :operator:`$within`.