Docsp 9562 geospatial queries (#78)

Co-authored-by: Nathan <[email protected]>
Co-authored-by: Chris <[email protected]>

Author: 3 people

source/fundamentals/crud/read-operations.txt

@@ -9,10 +9,10 @@ Read Operations
 - :doc:`/fundamentals/crud/read-operations/sort`
 - :doc:`/fundamentals/crud/read-operations/skip`
 - :doc:`/fundamentals/crud/read-operations/limit`
+- :doc:`/fundamentals/crud/read-operations/geo`
 
 ..
   - :doc:`/fundamentals/crud/read-operations/project`
-  - :doc:`/fundamentals/crud/read-operations/geo`
   - :doc:`/fundamentals/crud/read-operations/text`
 
 .. toctree::
@@ -23,8 +23,9 @@ Read Operations
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
    /fundamentals/crud/read-operations/limit
+   /fundamentals/crud/read-operations/geo
+
 ..
   /fundamentals/crud/read-operations/project
-  /fundamentals/crud/read-operations/geo
   /fundamentals/crud/read-operations/text
 

source/fundamentals/crud/read-operations/geo.txt

@@ -0,0 +1,300 @@
+===================
+Search Geospatially
+===================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+On this page you will learn how to search **geospatial data** with the
+MongoDB Java Driver, and the different geospatial data formats supported by MongoDB.
+
+Geospatial data is data that represents a geographical location on
+the surface of the Earth. Examples of geospatial data include:
+
+- Locations of movie theaters
+- Borders of countries
+- Routes of bicycle rides
+- Dog exercise areas in New York City
+
+Coordinates on Earth
+--------------------
+
+To store and query your geospatial data in MongoDB, use **GeoJSON**. GeoJSON is
+a data format created by the Internet Engineering Task Force (IETF). 
+
+Here is the location of MongoDB headquarters in GeoJSON:
+
+.. code-block:: json
+
+   "MongoDB Headquarters" : {
+      "type": "point",
+      "coordinates": [-73.986805, 40.7620853]
+   }
+
+For definitive information on GeoJSON, see the
+:rfc:`official IETF specification <7946>`.
+
+.. external resource
+
+GeoJSON Positions
+~~~~~~~~~~~~~~~~~
+
+A position represents a single place on Earth, and exists in code as an array
+containing two or three number values: 
+
+- Longitude in the first position (required)
+- Latitude in the second position (required)
+- Elevation in the third position (optional)
+
+.. tip:: Longitude then Latitude
+
+  GeoJSON orders coordinates as longitude first and latitude second. This may
+  be surprising as geographic coordinate system conventions generally list
+  latitude first and longitude second. Make sure to check what format any other
+  tools you are working with use. Popular tools such as OpenStreetMap and Google
+  Maps list coordinates as latitude first and longitude second.
+
+GeoJSON Types
+~~~~~~~~~~~~~
+
+Your GeoJSON object's type determines its geometric shape. Geometric shapes are
+made up of positions.
+
+Here are some common GeoJSON types and how you can specify them with positions:
+
+- ``Point``: a single position. This could represent the location of a
+  `sculpture <https://en.wikipedia.org/wiki/Chicago_Picasso>`__. 
+- ``LineString``: an array of two or more positions, thus forming a series of line
+  segments. This could represent
+  `the route of the Great Wall of China <https://commons.wikimedia.org/wiki/File:GreatWallChina4.png>`__. 
+- ``Polygon``: an array of positions in which the first and last
+  position are the same, thus enclosing some space. This could represent 
+  `the land within Vatican City <https://commons.wikimedia.org/wiki/File:Vatican_City_map_EN.png>`__.
+
+
+To learn more about the shapes you can use in MongoDB, see the
+:manual:`GeoJSON manual entry </reference/geojson/>`.
+
+.. external resource
+
+Index
+~~~~~
+
+To query data stored in the GeoJSON format, add the field containing
+GeoJSON data to a ``2dsphere`` index. The following snippet creates a
+``2dsphere`` index on the ``location.geo`` field using the ``Indexes`` builder:
+
+.. code-block:: java
+
+   // <MongoCollection setup code here>
+   collection.createIndex(Indexes.geo2dsphere("location.geo"));
+
+For more information on the ``Indexes`` builder, see our 
+:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
+
+.. guide resource
+
+Coordinates on a 2D Plane
+-------------------------
+
+You can store geospatial data using ``x`` and ``y`` coordinates on 
+a two-dimensional Euclidean plane. We refer to coordinates on a two-dimensional
+plane as "legacy coordinate pairs".
+
+Legacy coordinate pairs have the following structure:
+
+.. code-block:: json
+
+   "<field name>" : [ x, y ]
+
+Your field should contain an array of two values in which the first represents 
+the ``x`` axis value and the second represents the ``y`` axis value.
+
+Index
+~~~~~
+
+To query data stored as legacy coordinate pairs, you must add the field containing
+legacy coordinate pairs to  a ``2d`` index. The following snippet creates a
+``2d`` index on the ``coordinates`` field using the ``Indexes`` builder:
+
+.. code-block:: java
+
+   // <MongoCollection setup code here>
+   collection.createIndex(Indexes.geo2d("coordinates"));
+
+For more information on the ``Indexes`` builder, see our 
+:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`. 
+   
+For more information on legacy coordinate pairs, see the
+:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
+
+.. external resource
+
+.. note:: Supported Operators
+
+   Spherical (``2dsphere``) and flat (``2d``) indexes support some, but
+   not all, of the same query operators. For a full list of operators
+   and their index compatibility, see the
+   :manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
+
+   .. external resource
+
+Geospatial Queries
+------------------
+
+Geospatial queries consist of a query operator and GeoJSON shapes as query
+parameters.
+
+Query Operators
+~~~~~~~~~~~~~~~
+
+To query your geospatial data, use one of the following query operators: 
+
+- ``$near``
+- ``$geoWithin``
+- ``$nearSphere``
+- ``$geoIntersects`` *requires a 2dsphere index*
+
+You can specify these query operators in the MongoDB Java driver with the
+``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility
+methods of the ``Filters`` builder class.
+
+For more information on geospatial query operators, see the
+:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
+
+.. external resource
+
+For more information on ``Filters``, see our 
+:doc:`guide on the Filters builder </fundamentals/builders/filters>`.  
+
+Query Parameters
+~~~~~~~~~~~~~~~~
+
+To specify a shape to use in a geospatial query, use the
+``Position``, ``Point``, ``LineString``, and ``Polygon`` classes of the MongoDB
+Java driver.
+
+For a full list of the GeoJSON shapes available in the MongoDB Java driver, see the
+:java-docs:`GeoJSON package </apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`.
+
+.. external resource
+
+Examples
+--------
+
+The following examples use the MongoDB Atlas sample dataset. You can learn how
+to  set up your own free-tier Atlas cluster and how to load the sample dataset
+in our :doc:`quick start guide </quick-start>`.
+
+The examples use the ``theaters`` collection in the ``sample_mflix`` database
+from the sample dataset. The ``theaters`` collection contains a ``2dsphere`` index
+on the ``location.geo`` field.
+
+The examples require the following imports:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
+   :language: java
+   :dedent:
+   :start-after: begin exampleImports
+   :end-before: end exampleImports
+
+You can find the  
+`source code for the examples on Github here <https://github.com/mongodb/docs-java/blob/master/source/includes/fundamentals/code-snippets/Geo.java>`__.
+
+.. external resource
+
+Query by Proximity
+~~~~~~~~~~~~~~~~~~
+
+To search for and return documents from nearest to farthest from a point, use
+the ``near()`` static utility method of the ``Filters`` builder class. The
+``near()`` method constructs a query with the ``$near`` query operator. 
+
+The following example queries for theaters between ``10,000`` and ``5,000``
+meters from the 
+`Great Lawn of Central Park <https://en.wikipedia.org/wiki/Great_Lawn_and_Turtle_Pond>`__.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
+   :language: java
+   :dedent:
+   :start-after: begin findExample
+   :end-before: end findExample
+
+The output of the code snippet should look something like this:
+
+.. code-block:: json
+   
+   {"location": {"address": {"city": "Bronx"}}}
+   {"location": {"address": {"city": "New York"}}}
+   {"location": {"address": {"city": "New York"}}}
+   {"location": {"address": {"city": "Long Island City"}}}
+   {"location": {"address": {"city": "New York"}}}
+   {"location": {"address": {"city": "Secaucus"}}}
+   {"location": {"address": {"city": "Jersey City"}}}
+   {"location": {"address": {"city": "Elmhurst"}}}
+   {"location": {"address": {"city": "Flushing"}}}
+   {"location": {"address": {"city": "Flushing"}}}
+   {"location": {"address": {"city": "Flushing"}}}
+   {"location": {"address": {"city": "Elmhurst"}}}
+
+.. note:: Fun Fact
+
+   MongoDB uses the
+   :manual:`same reference system </reference/glossary/#std-term-WGS84>`
+   as GPS satellites to calculate geometries over the Earth.
+
+For more information on the ``$near`` operator, see  
+:manual:`the reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
+
+For more information on ``Filters``,
+:doc:`see our guide on the Filters builder </fundamentals/builders/filters>`.
+
+Query Within a Range
+~~~~~~~~~~~~~~~~~~~~
+
+To search for geospatial data within a specified shape use the ``geoWithin()``
+static utility method of the ``Filters`` builder class. The ``geoWithin()``
+method constructs a query with the ``$geoWithin`` query operator. 
+
+.. figure:: /includes/figures/geo_geometry.png
+   :alt: Area of Long Island we are searching for movie theaters
+
+The following example searches for movie theaters in the section of Long Island
+described in the figure above.
+
+.. _example_range_query:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
+   :language: java
+   :dedent:
+   :start-after: begin rangeExample
+   :end-before: end rangeExample
+
+The output of the code snippet should look something like this:
+
+.. code-block:: json
+
+   {"location": {"address": {"city": "Baldwin"}}}
+   {"location": {"address": {"city": "Levittown"}}}
+   {"location": {"address": {"city": "Westbury"}}}
+   {"location": {"address": {"city": "Mount Vernon"}}}
+   {"location": {"address": {"city": "Massapequa"}}}
+
+
+For more information on the ``$geoWithin`` operator, see the
+:manual:`reference documentation for $geoWithin </reference/operator/query/geoWithin/>`
+
+.. external resource
+
+For more information on the operators you can use in your query, see the
+:manual:`MongoDB server manual page on geospatial query operators </geospatial-queries/index.html>`
+
+.. external resource