DOCSP-40574: Add Geospatial page

source/fundamentals.txt

@@ -29,6 +29,7 @@ Fundamentals
    /fundamentals/logging
    /fundamentals/time-series
    /fundamentals/encrypt-fields
+   /fundamentals/geo
 
 - :ref:`Connecting to MongoDB <csharp-connection>`
 - :ref:`csharp-db-coll`
@@ -48,3 +49,4 @@ Fundamentals
 - :ref:`csharp-logging`
 - :ref:`csharp-time-series`
 - :ref:`Encrypt Fields <csharp-fle>`
+- :ref:`csharp-geo`

source/fundamentals/builders.txt

@@ -448,7 +448,7 @@ perform the following operations:
          .Include(m => m.Title)
          .Include(m => m.Plot));
 
-The results of the preeding example contain the following documents:
+The results of the preceding example contain the following documents:
 
 .. code-block:: json
 

source/fundamentals/geo.txt

@@ -0,0 +1,278 @@
+.. _csharp-geo:
+
+===================
+Search Geospatially
+===================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, coordinates, location, geographic
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to work with **geospatial data**, data formats,
+indexes, and queries.
+
+Geospatial data represents a geographic 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
+- Points on a graph
+
+Geospatial Data Formats
+-----------------------
+
+All geospatial data in MongoDB is stored in one of the following formats:
+
+- GeoJSON, a format that represents geospatial data on an earth-like
+  sphere.
+
+- Legacy coordinate pairs, a format that represents geospatial data
+  on a Euclidean plane.
+
+GeoJSON
+~~~~~~~
+
+Use GeoJSON to store data that represents geospatial information on
+an earth-like sphere. GeoJSON is composed of one or more **positions**
+and a **type**.
+
+Positions
+`````````
+
+A position represents a single location and exists in code as an array
+containing the following values:
+
+- Longitude in the first position (required)
+- Latitude in the second position (required)
+- Elevation in the third position (optional)
+
+The following is the position of the MongoDB Headquarters in New York City, NY.
+
+.. code-block:: csharp
+
+   GeoJson.Position(-73.986805, 40.7620853)
+
+Alternatively, you can use the ``GeoJson.Geographic()`` method to construct a coordinate
+pair.
+
+.. code-block:: csharp
+
+   GeoJson.Geographic(-73.986805, 40.7620853)
+
+.. important:: Longitude then Latitude
+
+  GeoJSON orders coordinates with longitude first and latitude second.
+  Make sure to check what format any other tools you are working with use, since many popular
+  tools such as OpenStreetMap and Google Maps list coordinates with latitude first and
+  longitude second.
+
+Types
+`````
+
+The type of your GeoJSON object determines the geometric shape it represents. 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. The following ``Point`` represents the location of
+  the MongoDB Headquarters:
+
+  .. code-block:: csharp
+
+     GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853))
+
+- ``LineString``: an array of two or more positions that forms a series of line
+  segments. A ``LineString`` can represent a path, route, border, or any other linear
+  geospatial data. The following ``LineString`` represents a segment of
+  the Great Wall of China:
+
+  .. code-block:: csharp
+
+     GeoJson.LineString
+     (
+        GeoJson.Position(116.572, 40.430),
+        GeoJson.Position(116.570, 40.434),
+        GeoJson.Position(116.567, 40.436),
+        GeoJson.Position(116.566, 40.441)
+     )
+
+- ``Polygon``: an array of positions in which the first and last
+  position are the same and enclose some space. The following
+  ``Polygon`` roughly represents the land within the Vatican City:
+
+  .. code-block:: csharp
+
+     GeoJson.Polygon
+     (
+         GeoJson.Position(12.446086, 41.901977),
+         GeoJson.Position(12.457952, 41.901559),
+         GeoJson.Position(12.455375, 41.907351),
+         GeoJson.Position(12.449863, 41.905186),
+         GeoJson.Position(12.446086, 41.901977)
+     }
+
+To learn more about the GeoJSON types you can use in MongoDB, see the
+:manual:`GeoJSON manual entry </reference/geojson/>`.
+
+For more information on the GeoJSON format, see the
+`official IETF specification <https://datatracker.ietf.org/doc/html/rfc7946>`__.
+
+Legacy Coordinate Pairs
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Use legacy coordinate pairs to store data that represents geospatial information
+on a two-dimensional plane.
+
+Legacy coordinate pairs are represented by an array of two values, in which the first
+represents the ``x`` axis value and the second represents the ``y`` axis value.
+
+For more information on legacy coordinate pairs, see the
+:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
+
+Geospatial Indexes
+------------------
+
+To enable querying on geospatial data, you must create an index that
+corresponds to the data format. The following index types enable geospatial
+queries:
+
+- ``2dsphere``, used for GeoJSON data
+- ``2d``, used for legacy coordinate pairs
+
+To learn more about how to create geospatial indexes, see the :ref:`geospatial-indexes`
+section of the Indexes guide.
+
+Query Operators
+~~~~~~~~~~~~~~~
+
+To query geospatial data, use one of the following query operators:
+
+- ``$near``
+- ``$geoWithin``
+- ``$nearSphere``
+- ``$geoIntersects`` (*requires a 2dsphere index*)
+
+When using the ``$near`` operator, you can specify the following distance operators:
+
+- ``$minDistance``
+- ``$maxDistance``
+
+When using the ``$geoWithin`` operator, you can specify the following shape operators:
+
+- ``$box``
+- ``$polygon``
+- ``$center``
+- ``$centerSphere``
+
+For more information on geospatial query operators, see
+:manual:`Geospatial Query Operators </geospatial-queries/#geospatial-query-operators>` in
+the server manual.
+
+Examples
+--------
+
+The following examples uses the MongoDB Atlas sample dataset. To obtain this sample
+dataset, see :ref:`csharp-quickstart`.
+
+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.
+
+Query by Proximity
+~~~~~~~~~~~~~~~~~~
+
+The following example queries for documents with a ``location.geo`` field value
+within 1000 meters of the MongoDB Headquarters in New York City, NY. It returns documents
+from nearest to farthest.
+
+.. code-block:: csharp
+
+   // Point representation of the MongoDB Headquarters
+   var point = GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853));
+
+   // Specifies a maxDistance of 1000 meters and a minDistance of 0 meters
+   var filter = Builders<Theater>.Filter.Near(m => m.Location.Geo, point, 1000.0, 0.0);
+
+   // Only fetches the _id and theaterId fields 
+   var projection = Builders<Theater>.Projection.Include("theaterId");
+
+   var results = collection.Find(filter).Project(projection);
+
+The results of the preceding example contain the following documents:
+
+.. code-block:: json
+   :copyable: False
+
+   { "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
+   { "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }
+
+Query by Polygon
+~~~~~~~~~~~~~~~~
+
+The following example queries for documents with a ``location.geo`` field value that exists
+within the boundaries of Manhattan.
+
+.. code-block:: csharp
+
+   // Polygon representation of Manhattan
+   var polygon = GeoJson.Polygon
+   (
+      GeoJson.Position(-73.925492, 40.877410),
+      GeoJson.Position(-73.910372, 40.872366),
+      GeoJson.Position(-73.935127, 40.834020),
+      GeoJson.Position(-73.929049, 40.798569),
+      GeoJson.Position(-73.976485, 40.711432),
+      GeoJson.Position(-74.015747, 40.701229),
+      GeoJson.Position(-74.018859, 40.708367),
+      GeoJson.Position(-74.008007, 40.754307),
+      GeoJson.Position(-73.925492, 40.877410)
+   );
+
+   var filter = Builders<Theater>.Filter.GeoWithin(m => m.Location.Geo, polygon);
+
+   // Only fetches the _id and theaterId fields 
+   var projection = Builders<Theater>.Projection.Include("theaterId");
+
+   var results = collection.Find(filter).Project(projection);
+
+The results of the preceding example contain the following documents:
+
+.. code-block:: json
+   :copyable: False
+
+   { "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
+   { "_id" : ObjectId("59a47287cfa9a3a73e51eccb"), "theaterId" : 835 }
+   { "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }
+   { "_id" : ObjectId("59a47286cfa9a3a73e51e744"), "theaterId" : 1028 }
+   { "_id" : ObjectId("59a47287cfa9a3a73e51ebe1"), "theaterId" : 609 }
+   { "_id" : ObjectId("59a47287cfa9a3a73e51e8ed"), "theaterId" : 1906 }
+   { "_id" : ObjectId("59a47287cfa9a3a73e51e87d"), "theaterId" : 1531 }
+   { "_id" : ObjectId("59a47287cfa9a3a73e51eb63"), "theaterId" : 482 }
+
+Additional Resources
+--------------------
+
+- For more information about working with geospatial data, see the
+  :ref:`manual entry for geospatial data <geo-overview-location-data>`.
+
+- For more information about supported GeoJSON types, see the the
+  :manual:`GeoJSON manual entry </reference/geojson/>`.
+
+- For more information about geospatial query operators, see the
+  :manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
+

source/fundamentals/indexes.txt

@@ -308,6 +308,8 @@ fields within the ``sample_mflix.movies`` collection:
 For more information, see :manual:`Compound Text Index Restrictions </core/indexes/index-types/index-text/text-index-restrictions/#compound-text-index>`
 and :manual:`Text Indexes </core/index-text>` in the Server manual.
 
+.. _geospatial-indexes:
+
 Geospatial Indexes
 ~~~~~~~~~~~~~~~~~~
 

source/fundamentals/linq.txt

@@ -554,7 +554,7 @@ the ``plot_embedding`` field using vector embeddings for the string ``"time trav
       .VectorSearch(m => m.Embedding, vector, 10, options)
       .Select(m => new { m.Title, m.Plot });
 
-The results of the preeding example contain the following documents:
+The results of the preceding example contain the following documents:
 
 .. code-block:: json