diff --git a/source/fundamentals.txt b/source/fundamentals.txt index af35b550..9ef0956e 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -29,6 +29,7 @@ Fundamentals /fundamentals/logging /fundamentals/time-series /fundamentals/encrypt-fields + /fundamentals/geo - :ref:`Connecting to MongoDB ` - :ref:`csharp-db-coll` @@ -48,3 +49,4 @@ Fundamentals - :ref:`csharp-logging` - :ref:`csharp-time-series` - :ref:`Encrypt Fields ` +- :ref:`csharp-geo` diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index f54494da..88adf7a9 100644 --- a/source/fundamentals/builders.txt +++ b/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 diff --git a/source/fundamentals/geo.txt b/source/fundamentals/geo.txt new file mode 100644 index 00000000..951e3246 --- /dev/null +++ b/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 `. + +For more information on the GeoJSON format, see the +`official IETF specification `__. + +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 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 ` 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.Filter.Near(m => m.Location.Geo, point, 1000.0, 0.0); + + // Only fetches the _id and theaterId fields + var projection = Builders.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.Filter.GeoWithin(m => m.Location.Geo, polygon); + + // Only fetches the _id and theaterId fields + var projection = Builders.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 `. + +- For more information about supported GeoJSON types, see the the + :manual:`GeoJSON manual entry `. + +- For more information about geospatial query operators, see the + :manual:`manual entry for geospatial queries `. + diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index 7b0cf10e..a2542b3c 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -308,6 +308,8 @@ fields within the ``sample_mflix.movies`` collection: For more information, see :manual:`Compound Text Index Restrictions ` and :manual:`Text Indexes ` in the Server manual. +.. _geospatial-indexes: + Geospatial Indexes ~~~~~~~~~~~~~~~~~~ diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index be74c543..00c445c6 100644 --- a/source/fundamentals/linq.txt +++ b/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