From 2d890b6f3912fc8ee6f5d56a33788bbc761ddc21 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 11 Jul 2012 16:42:25 -0400 Subject: [PATCH 1/6] geoSpatial core doc draft --- draft/core/geospatial-indexes.txt | 110 ++++++++++++++---------------- 1 file changed, 51 insertions(+), 59 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 8b4939f31f7..7af2bd36c3b 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -1,5 +1,3 @@ -.. TODO have a better way to handle 2d vs 2D vs 2 dimensional - ================== Geospatial Indexes ================== @@ -9,11 +7,14 @@ Geospatial Indexes Overview -------- -.. TODO revise introduction +.. TODO beef this up. + +MongoDB can store and query geospatial data with a focus on +location-based queries. -MongoDB supports geospatial data by rceating a special index for -location data points. The index is a geohash calculated from the -range and data points which can be queried. +MongoDB supports geospatial data by creating a special index for +location data points. The index is a geohash calculated based on the +range and data points. To use geospatial functions in MongoDB, you have to structure the location data in a 2D array and make an index on this location @@ -30,7 +31,9 @@ index configuration. Geospatial Indexes ------------------ -.. TODO put a little bit here. +In order for MongoDB to use geospatial data, you must specify +MongoDB to create a geospatial index on the location data in your +collection. .. see:: :ref:`geospatial-coordinates` for an overview on modeling location data in MongoDB. @@ -141,15 +144,15 @@ geospatial indexes. component first. This will affect your result set if you specify additional sort operations. -Haystack Indexing -~~~~~~~~~~~~~~~~~ +Haystack Index +~~~~~~~~~~~~~~ Geospatial haystack indexes makes it possible to build a special ``bucket`` -collection that can better support queries that operate within a +collection that better support queries that operate within a limited area. For more information, please refer to :doc:`Geospatial Indexes ` -Build a geospatial index and specify the ``geoHaystack`` for the +To build a geospatial 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 where keys within 1 unit of @@ -172,34 +175,24 @@ searches in this area, create the index using the following command: db.places.ensureIndex({ loc: "geoHaystack", type: 1} , { bucketSize: 6 } ) -.. TODO merge in or remove this: - - In addition to ordinary 2d geospatial indices, mongodb supports - the use of bucket-based geospatial indexes called "haystack - indexing". These indexes can accelerate small-region type - longitude / latitude queries when an additional criteria is - required. - - Haystack indexes allow you to tune your bucket size to the - distribution of your data, so that queries only search a very small - region of 2d space for a particular kind of document. Haystack - indexes are not suited for finding the closest documents to a - particular location, as the closest documents could be far away - compared to the bucket size. +Haystack indexes allow you to tune your bucket size to the +distribution of your data, so that queries only search a very small +region of 2D space for a particular kind of document. Haystack +indexes are not suited to finding the closest documents to a +particular location, as the closest documents could be far away +compared to the bucket size. .. _geospatial-spherical-representation: Spatial Representation Systems ------------------------------ -.. TODO this might need to be a *bit longer* - MongoDB supports two systems for representing and returning geospatial results. The default representation is flat and assumes that the coordinates represent points on a flat plane. While this -representation is sufficient for many applications, if the points -refer to locations on a spherical plane (i.e. coordinates on Earth) -then sphical queries will provide more accurate results. +representation is sufficient for many applications, points that refer +to locations on a spherical plane (i.e. coordinates on Earth) then +spherical queries will provide more accurate results. .. note:: @@ -208,7 +201,7 @@ then sphical queries will provide more accurate results. geospatial systems in MongoDB is in the **queries**. In general, the flat system is easier and accurate for system data -sets, but will return imprecise or skewed results if your coordinate +sets, but may return imprecise or skewed results if your coordinate system reflects points on a curved plane, like the Earth's surface. For more information on spherical and flat queries see the @@ -219,41 +212,40 @@ information on query operations for spherical systems see the Geohash ------- -.. TODO revise and make better +.. TODO this is really an internals stuff + +When creating a geospatial index, MongoDB will compute a location's +geohash value. A geohash value is a binary representation of the +location on a coordinate grid. + +Geohash values are generated by continuously dividing a 2D map into +quadrants. Each quadrant is assigned a two bit value. A basic two bit +assignment for each quadrant could be: + +.. code-block:: javascript -.. cut this down -.. know the geohashes are used for indexes -.. leave finer parts in the doc. + 01 11 -.. works on a fixed grid -.. computed on index creation -.. geohash used for look up -.. not cryptographic hash -.. h + 00 10 -With Geospatial data, MongoDB will store 2D values as geohash -values. A geohash value is a binary representation of a 2D system -which can accurately represent 2D data. +.. TODO color code these bits? -Geohash values are generated for a 2D map by continuously dividing a -2D map into quadrants. Each quadrant is assigned a 2bit value. Basic -bit assignment for a quadrant: +These two bit values (00, 01, 10, 11) each represent one of the four +quadrants. If a point exists in any of these quadrants, a set of two +bits will be assigned to describe the location. - 01 11 +To describe the point's location in more detail using the geohash, the +map will be further divided within the same quadrant and another two +bits will be assigned to the point. This point now has 2x two bits +representing its location, four bits total. - 00 10 +As the map is further divided, another two bit value is +assigned. Further divisions will provide additional accuracy with more +bits. -These two bits: 00, 01, 10, 11 represent each of the quadrants. If a -point exists in any of these quadrants, these two bits will represent -them. The map will be further divided within the same quadrant and -another two bits will be assigned to the point. This point now has 2 -two bits representing its location, 4 bits total. As the map is -further divided, each quadrant is assigned the same 2bit value, -resulting in another two bits describing the map. Further divisions -will improve further accuracy with more bits for more quadrants +.. TODO insert graphical example to describe? It would be 'nice' for +.. those that REALLy want to know... -.. Note: each quadrant includes its own left and lower bounds. If -.. there are any points which lie on the center of two boundaries, the -.. default would be to +.. TODO this doesn't show up in the draft HTML .. includes:: /includes/geospatial-sharding.rst From 7571cd400ce112f8b614514f1ff7f0aab834093e Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 11 Jul 2012 17:33:17 -0400 Subject: [PATCH 2/6] quick note to add in distanceMultiplier --- draft/applications/geospatial-indexes.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/draft/applications/geospatial-indexes.txt b/draft/applications/geospatial-indexes.txt index 634f579b85c..6057aa77958 100644 --- a/draft/applications/geospatial-indexes.txt +++ b/draft/applications/geospatial-indexes.txt @@ -362,6 +362,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 + Multi-location Documents ------------------------ From b88f10162e8a02c87b0b5099c87a81538c739d2b Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 12 Jul 2012 11:59:12 -0400 Subject: [PATCH 3/6] updated geoCore doc. things should be tighter... --- draft/core/geospatial-indexes.txt | 140 +++++++++++++++--------------- 1 file changed, 70 insertions(+), 70 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 7af2bd36c3b..2e83f73e2f9 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -7,22 +7,15 @@ Geospatial Indexes Overview -------- -.. TODO beef this up. +MongoDB can support geospatial data with a focus on location-based +queries using flat or spherical models. You can query with various +levels of precision, combine location data with other indexes, and +create special haystack indexes for accelerated region queries. -MongoDB can store and query geospatial data with a focus on -location-based queries. - -MongoDB supports geospatial data by creating a special index for -location data points. The index is a geohash calculated based on the -range and data points. - -To use geospatial functions in MongoDB, you have to structure the -location data in a 2D array and make an index on this location -data with special options. - -When you query for locations against the geospatial index, MongoDB -will automatically query against the geohash index, as well as other -index configuration. +This document introduces many of the core concepts required to +understand and setup your geospatial data for use in MongoDB. For more +information on how to use geospatial data in MongoDB, please refer to +:doc:`Using Geospatial Data`. .. include:: /includes/geospatial-coordinates.rst @@ -31,13 +24,19 @@ index configuration. Geospatial Indexes ------------------ -In order for MongoDB to use geospatial data, you must specify -MongoDB to create a geospatial index on the location data in your -collection. - .. see:: :ref:`geospatial-coordinates` for an overview on modeling location data in MongoDB. +To use geospatial functions in MongoDB, you have to structure the +location data in a 2D array and make an index on this location +data with special options. + +When you query for locations against the geospatial index, MongoDB +will automatically query against this geospatial index, as well as other +index configuration. This index is a geohash calculated based on the +range and data points. For more information on geohash, please +refer to :ref:`geohash` + To create a geospatial index, use an operation modeled on the following prototype: @@ -46,8 +45,8 @@ following prototype: db.collection.ensureIndex( { : "2d" } ) These operations will create a special index on location field in the -specified collection. These indexes use :ref:`geospatial-geohash`. All -geospatial queries will use this geospatial index. +specified collection. All geospatial queries will use this geospatial +index. .. note:: @@ -62,11 +61,11 @@ geospatial queries will use this geospatial index. Range ~~~~~ -All geospatial indexes are bounded and MongoDB will return an error -and reject documents with coordinate pairs outside of these -boundaries. The default boundaries support global coordinate data -(i.e. latitude and longitude for points on Earth,) are between -180 -inclusive, and 180 non-inclusive. +All geospatial indexes are bounded. MongoDB will return an error and +reject documents with coordinate pairs outside of these +boundaries. The default boundaries support global coordinate data are +between -180 inclusive, and 180 non-inclusive. (i.e. latitude and +longitude for points on Earth) To specify the boundaries of a geospatial index, use the ``min`` and ``max`` operators with the :func:`ensureIndex() ` @@ -95,13 +94,16 @@ Geospatial indexes record precision, or resolution, in "bits", which are configurable during index creation. If a geospatial index has a higher bits setting, MongoDB will be able to return more precise results from the index. However, lower resolution indexes provide -faster performance. For more information, please refer to the -:ref:`precision ` section. +faster performance. For more information on how bits affect precision, +please refer to the :ref:`geohash ` section. By default, geospatial indexes in MongoDB have 26 bits of precision -and supports as many as 32 bits of precision. You can set the -precision of a geospatial index during creation by specifying the -``bits`` option to the :func:`ensureIndex() +and supports as many as 32 bits of precision. With 26 bits of +precision, using the default range of -180 to 180, your precision +would be about 1 foot or 30 centimeters. + +You can set the precision of a geospatial index during creation by +specifying the ``bits`` option to the :func:`ensureIndex() ` method, as in the following example. .. code-block:: javascript @@ -116,11 +118,11 @@ precision in exchange for query speed. Compound Indexes ~~~~~~~~~~~~~~~~ -MongoDB supports :term:`compound indexes ` where one component is a -coordinate in a geospatial index, and the other coordinate is one or -more fields. This means that, for some operations, MongoDB will be -able to use this index for a larger portion of an operation, which -will improve performance for these queries. +MongoDB supports :ref:`compound indexes ` where +one component is a geospatial index, and the other component is +another document field. For queries which use these fields, MongoDB +will be able to use this index for a larger portion of an operation, +which will improve performance for these queries. Use an operation that resembles the following prototype command to create a compound geospatial index. @@ -136,7 +138,7 @@ select only restaurants that match a certain type (i.e. "take-out," or "bar" stored in a ``type`` field.) See the :ref:`index-type-compound` section for more information on -geospatial indexes. +compound indexes. .. note:: @@ -147,10 +149,15 @@ geospatial indexes. Haystack Index ~~~~~~~~~~~~~~ -Geospatial haystack indexes makes it possible to build a special ``bucket`` -collection that better support queries that operate within a -limited area. For more information, please refer to :doc:`Geospatial -Indexes ` +Geospatial haystack indexes makes it possible to build a special +``bucket`` index to tune for your distribution of data. Haystack +indexes improve query performance that operate within a limited +area. For more information, please refer to :doc:`Geospatial Indexes +` + +Haystack indexes are not suited to finding the closest documents to a +particular location, as the closest documents could be far away +compared to the bucket size. To build a geospatial index, specify the ``geoHaystack`` for the location field and a ``bucketSize`` parameter . The ``bucketSize`` @@ -173,14 +180,7 @@ searches in this area, create the index using the following command: .. code-block:: javascript db.places.ensureIndex({ loc: "geoHaystack", type: 1} , - { bucketSize: 6 } ) - -Haystack indexes allow you to tune your bucket size to the -distribution of your data, so that queries only search a very small -region of 2D space for a particular kind of document. Haystack -indexes are not suited to finding the closest documents to a -particular location, as the closest documents could be far away -compared to the bucket size. + { bucketSize: 6 } ) .. _geospatial-spherical-representation: @@ -188,11 +188,11 @@ Spatial Representation Systems ------------------------------ MongoDB supports two systems for representing and returning geospatial -results. The default representation is flat and assumes that the -coordinates represent points on a flat plane. While this -representation is sufficient for many applications, points that refer -to locations on a spherical plane (i.e. coordinates on Earth) then -spherical queries will provide more accurate results. +results. The default representation is flat and assumes coordinates +points are on a flat plane. While this representation is sufficient +for many applications, points that refer to locations on a spherical +plane (i.e. coordinates on Earth) then spherical queries will provide +more proper results. .. note:: @@ -200,20 +200,18 @@ spherical queries will provide more accurate results. in MongoDB. Rather, the only difference between spherical and flat geospatial systems in MongoDB is in the **queries**. -In general, the flat system is easier and accurate for system data +In general, the flat system is easier and accurate for certain data sets, but may return imprecise or skewed results if your coordinate system reflects points on a curved plane, like the Earth's surface. -For more information on spherical and flat queries see the -:ref:`geospatial-representation-system` section and for more -information on query operations for spherical systems see the +For more information on query operations for spherical systems see the :ref:`spherical queries ` section. +.. _geospatial-geohash: + Geohash ------- -.. TODO this is really an internals stuff - When creating a geospatial index, MongoDB will compute a location's geohash value. A geohash value is a binary representation of the location on a coordinate grid. @@ -228,24 +226,26 @@ assignment for each quadrant could be: 00 10 -.. TODO color code these bits? +.. TODO @Sam: how to best format this? These two bit values (00, 01, 10, 11) each represent one of the four quadrants. If a point exists in any of these quadrants, a set of two -bits will be assigned to describe the location. +bits will be assigned to describe the location. (i.e. top left is 01 ) -To describe the point's location in more detail using the geohash, the -map will be further divided within the same quadrant and another two -bits will be assigned to the point. This point now has 2x two bits -representing its location, four bits total. +To describe the point's location in more detail, the map will be +further divided within the same quadrant and the same bit values +applied within the new division. Another two bits will be assigned to +the point, giving another two bits describing the location. This point +now has 2x two bits representing its location, four bits +total. (i.e. if the point is in the middle of the top left quadrant, +the new bits will be 10, and the geohash will be: 0110) As the map is further divided, another two bit value is assigned. Further divisions will provide additional accuracy with more bits. -.. TODO insert graphical example to describe? It would be 'nice' for -.. those that REALLy want to know... +.. TODO later - this is a great insert graphical example -.. TODO this doesn't show up in the draft HTML +.. TODO the below include doesn't show up in the draft HTML -.. includes:: /includes/geospatial-sharding.rst +.. include:: /includes/geospatial-sharding.rst From b60b57bb9021005c54460bc511091337ae651c3f Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Fri, 13 Jul 2012 11:10:09 -0400 Subject: [PATCH 4/6] geoCore edits --- draft/core/geospatial-indexes.txt | 39 +++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 2e83f73e2f9..a17773d4849 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -14,8 +14,9 @@ create special haystack indexes for accelerated region queries. This document introduces many of the core concepts required to understand and setup your geospatial data for use in MongoDB. For more -information on how to use geospatial data in MongoDB, please refer to -:doc:`Using Geospatial Data`. +information on how to use geospatial data in MongoDB, such as +querying, please refer to :doc:`Using Geospatial +Data`. .. include:: /includes/geospatial-coordinates.rst @@ -33,8 +34,8 @@ data with special options. When you query for locations against the geospatial index, MongoDB will automatically query against this geospatial index, as well as other -index configuration. This index is a geohash calculated based on the -range and data points. For more information on geohash, please +index configuration. This index is a :term:`geohash` calculated based on the +range and data points. For more information on :term:`geohash`, please refer to :ref:`geohash` To create a geospatial index, use an operation modeled on the @@ -85,6 +86,12 @@ between ``-90`` and ``90``: db.places.ensureIndex( { loc: "2d" } , { min: 90 , max: 90 } ) +For more information on precision with geospatial data, please refer to: +:ref:`precision ` section. + +For more information on resolution or accuracy with geospatial data, +please refer to: :ref:`geohash ` section. + .. _geospatial-indexes-precision: Precision @@ -100,7 +107,9 @@ please refer to the :ref:`geohash ` section. By default, geospatial indexes in MongoDB have 26 bits of precision and supports as many as 32 bits of precision. With 26 bits of precision, using the default range of -180 to 180, your precision -would be about 1 foot or 30 centimeters. +would be about 1 foot or 30 centimeters. For more information on how +to configure the range for your geospatial data, please refer to the +:ref:`range ` section. You can set the precision of a geospatial index during creation by specifying the ``bits`` option to the :func:`ensureIndex() @@ -121,7 +130,7 @@ Compound Indexes MongoDB supports :ref:`compound indexes ` where one component is a geospatial index, and the other component is another document field. For queries which use these fields, MongoDB -will be able to use this index for a larger portion of an operation, +will be able to use this index for a larger portion of operations, which will improve performance for these queries. Use an operation that resembles the following prototype command to @@ -137,15 +146,20 @@ list of restaurants near a given point, but you want to optionally select only restaurants that match a certain type (i.e. "take-out," or "bar" stored in a ``type`` field.) -See the :ref:`index-type-compound` section for more information on +See the :ref:`` section for more information on compound indexes. +To improve performance based on the distribution of your data, please +refer to the :ref:`` section. + .. note:: Limits in geospatial queries are always applied to the geospatial component first. This will affect your result set if you specify additional sort operations. +.. _geospatial-haystack-index: + Haystack Index ~~~~~~~~~~~~~~ @@ -155,9 +169,14 @@ indexes improve query performance that operate within a limited area. For more information, please refer to :doc:`Geospatial Indexes ` -Haystack indexes are not suited to finding the closest documents to a -particular location, as the closest documents could be far away -compared to the bucket size. +To improve geospatial query performance with another field, please +refer to the :ref:`compound index ` section. + +.. note:: + + Haystack indexes are not suited to finding the closest documents to + a particular location, as the closest documents could be far away + compared to the bucket size. To build a geospatial index, specify the ``geoHaystack`` for the location field and a ``bucketSize`` parameter . The ``bucketSize`` From 75fad10fd4cd5ac6efa1c6b410c6486b60af68e7 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Sat, 14 Jul 2012 19:11:13 -0400 Subject: [PATCH 5/6] updated geoCore draft. review please. --- draft/core/geospatial-indexes.txt | 115 ++++++++++++++---------------- source/reference/glossary.txt | 4 ++ 2 files changed, 56 insertions(+), 63 deletions(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index a17773d4849..6ebe55d5a94 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -7,16 +7,17 @@ Geospatial Indexes Overview -------- -MongoDB can support geospatial data with a focus on location-based -queries using flat or spherical models. You can query with various -levels of precision, combine location data with other indexes, and -create special haystack indexes for accelerated region queries. - -This document introduces many of the core concepts required to -understand and setup your geospatial data for use in MongoDB. For more -information on how to use geospatial data in MongoDB, such as -querying, please refer to :doc:`Using Geospatial -Data`. +MongoDB supports location-based queries and geospatial data with a +special index for coordinate data. The index stores :ref:`geohashes +` data, and makes it possible to return documents +using special proximity and bounded queries against flat or spherical +coordinate systems. Geospatial haystack indexes provide additional +support for certain classes of region-based queries. + +This document provides an overview of the core concepts and designs +that underpin geospatial queries in MongoDB. For most cases, the +:doc:`/applications/geospatial-indexes` provide complete documentation +of all location-based operations and queries. .. include:: /includes/geospatial-coordinates.rst @@ -36,7 +37,7 @@ When you query for locations against the geospatial index, MongoDB will automatically query against this geospatial index, as well as other index configuration. This index is a :term:`geohash` calculated based on the range and data points. For more information on :term:`geohash`, please -refer to :ref:`geohash` +refer to :ref:`geohash`. To create a geospatial index, use an operation modeled on the following prototype: @@ -65,8 +66,8 @@ Range All geospatial indexes are bounded. MongoDB will return an error and reject documents with coordinate pairs outside of these boundaries. The default boundaries support global coordinate data are -between -180 inclusive, and 180 non-inclusive. (i.e. latitude and -longitude for points on Earth) +between -180 inclusive, and 180 non-inclusive (i.e. latitude and +longitude.) To specify the boundaries of a geospatial index, use the ``min`` and ``max`` operators with the :func:`ensureIndex() ` @@ -86,11 +87,9 @@ between ``-90`` and ``90``: db.places.ensureIndex( { loc: "2d" } , { min: 90 , max: 90 } ) -For more information on precision with geospatial data, please refer to: -:ref:`precision ` section. - -For more information on resolution or accuracy with geospatial data, -please refer to: :ref:`geohash ` section. +For more information see the :ref:`Geospatial Precision +` and the :ref:`Geohashes +` section. .. _geospatial-indexes-precision: @@ -101,15 +100,13 @@ Geospatial indexes record precision, or resolution, in "bits", which are configurable during index creation. If a geospatial index has a higher bits setting, MongoDB will be able to return more precise results from the index. However, lower resolution indexes provide -faster performance. For more information on how bits affect precision, -please refer to the :ref:`geohash ` section. +faster performance. For more information on the relationship between +bits and precision, see the :ref:`geohash ` section. By default, geospatial indexes in MongoDB have 26 bits of precision and supports as many as 32 bits of precision. With 26 bits of precision, using the default range of -180 to 180, your precision -would be about 1 foot or 30 centimeters. For more information on how -to configure the range for your geospatial data, please refer to the -:ref:`range ` section. +would be about 1 foot or 30 centimeters. You can set the precision of a geospatial index during creation by specifying the ``bits`` option to the :func:`ensureIndex() @@ -124,14 +121,16 @@ You may create an index with fewer than 26 bits *if* your the data in your collection is less precise and/or you're willing to sacrifice precision in exchange for query speed. +For more information on how to configure the range for your geospatial +data, please refer to the :ref:`range ` section. + Compound Indexes ~~~~~~~~~~~~~~~~ MongoDB supports :ref:`compound indexes ` where -one component is a geospatial index, and the other component is -another document field. For queries which use these fields, MongoDB -will be able to use this index for a larger portion of operations, -which will improve performance for these queries. +one component holds coordinate data. For queries that include these +fields, MongoDB will use this index for a larger portion of these +operations, which will improve performance for these queries. Use an operation that resembles the following prototype command to create a compound geospatial index. @@ -146,18 +145,14 @@ list of restaurants near a given point, but you want to optionally select only restaurants that match a certain type (i.e. "take-out," or "bar" stored in a ``type`` field.) -See the :ref:`` section for more information on -compound indexes. - -To improve performance based on the distribution of your data, please -refer to the :ref:`` section. - .. note:: Limits in geospatial queries are always applied to the geospatial component first. This will affect your result set if you specify additional sort operations. +.. seealso: ":ref:``" and ":ref:``" + .. _geospatial-haystack-index: Haystack Index @@ -178,7 +173,7 @@ refer to the :ref:`compound index ` section. a particular location, as the closest documents could be far away compared to the bucket size. -To build a geospatial index, specify the ``geoHaystack`` for the +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 where keys within 1 unit of @@ -208,10 +203,10 @@ Spatial Representation Systems MongoDB supports two systems for representing and returning geospatial results. The default representation is flat and assumes coordinates -points are on a flat plane. While this representation is sufficient -for many applications, points that refer to locations on a spherical -plane (i.e. coordinates on Earth) then spherical queries will provide -more proper results. +points are on a flat surface. This representation is sufficient +for many applications. For coordinate points that refer to locations on a spherical +surface, (i.e. coordinates on Earth) spherical queries will provide +results that factor in the Earth's curvature. .. note:: @@ -219,10 +214,6 @@ more proper results. in MongoDB. Rather, the only difference between spherical and flat geospatial systems in MongoDB is in the **queries**. -In general, the flat system is easier and accurate for certain data -sets, but may return imprecise or skewed results if your coordinate -system reflects points on a curved plane, like the Earth's surface. - For more information on query operations for spherical systems see the :ref:`spherical queries ` section. @@ -231,12 +222,11 @@ For more information on query operations for spherical systems see the Geohash ------- -When creating a geospatial index, MongoDB will compute a location's -geohash value. A geohash value is a binary representation of the -location on a coordinate grid. +To create a geospatial index, MongoDB computes the :term:`geohash` +value for the coordinate pair in the specified values. Geohash values are generated by continuously dividing a 2D map into -quadrants. Each quadrant is assigned a two bit value. A basic two bit +quadrants. Each quadrant is assigned a two bit value. An example two bit assignment for each quadrant could be: .. code-block:: javascript @@ -245,23 +235,22 @@ assignment for each quadrant could be: 00 10 -.. TODO @Sam: how to best format this? - -These two bit values (00, 01, 10, 11) each represent one of the four -quadrants. If a point exists in any of these quadrants, a set of two -bits will be assigned to describe the location. (i.e. top left is 01 ) - -To describe the point's location in more detail, the map will be -further divided within the same quadrant and the same bit values -applied within the new division. Another two bits will be assigned to -the point, giving another two bits describing the location. This point -now has 2x two bits representing its location, four bits -total. (i.e. if the point is in the middle of the top left quadrant, -the new bits will be 10, and the geohash will be: 0110) - -As the map is further divided, another two bit value is -assigned. Further divisions will provide additional accuracy with more -bits. +These two bit values, ``00``, ``01``, ``10``, and ``11``, each +represent one of the four quadrants. If a point exists in any of these +quadrants, a set of two bits will be assigned to describe the +location. (i.e. top left is ``01`` ) + +To provide greater precision, the geohash representation divides each +original quadrant into sub-quadrants. The geohash identifies each +sub-quandrant by the concatenation of the geohash of the containing +quadrant (e.g. 01) and the quadrant's own identifier. Therefore, for +the upper-right quadrant, ``01``, the sub-quadrants would be: +``0100``, ``0101``, ``0110``, and ``0111``. + +As the :term:`geoHash` calculation continues to divide the coordinate +plane, another two bit value is assigned. To increase the accuracy of +this representation, create a :term:`geohash` with more divisions, or +a higher number of ``bits``. .. TODO later - this is a great insert graphical example diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 455b68c6019..463bcd98607 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -810,3 +810,7 @@ Glossary of being unique when generated. The most significant digits in an ObjectId represent the time when the Object. MongoDB uses ObjectId values as the default values for :term:`_id` fields. + + Geohash + A value is a binary representation of the location on a + coordinate grid. From a36fd8699b58d67549c9b52e023d34c23781c9ab Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 16 Jul 2012 11:42:33 -0400 Subject: [PATCH 6/6] updated precision from 1 foot to 2 feet --- draft/core/geospatial-indexes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/core/geospatial-indexes.txt b/draft/core/geospatial-indexes.txt index 6ebe55d5a94..4de58cd21c4 100644 --- a/draft/core/geospatial-indexes.txt +++ b/draft/core/geospatial-indexes.txt @@ -106,7 +106,7 @@ bits and precision, see the :ref:`geohash ` section. By default, geospatial indexes in MongoDB have 26 bits of precision and supports as many as 32 bits of precision. With 26 bits of precision, using the default range of -180 to 180, your precision -would be about 1 foot or 30 centimeters. +would be about 2 feet or about 60 centimeters. You can set the precision of a geospatial index during creation by specifying the ``bits`` option to the :func:`ensureIndex()