From cdfdcb5cc296c317079e55a6f66ca7a950140ce3 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 26 Jun 2024 09:09:44 -0400 Subject: [PATCH 1/6] DOCSP-40574: Add Geospatial page --- source/fundamentals.txt | 2 + source/fundamentals/builders.txt | 2 +- source/fundamentals/geo.txt | 272 +++++++++++++++++++++++++++++++ source/fundamentals/indexes.txt | 2 + source/fundamentals/linq.txt | 2 +- 5 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 source/fundamentals/geo.txt 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..c0290a5f --- /dev/null +++ b/source/fundamentals/geo.txt @@ -0,0 +1,272 @@ +.. _csharp-geo: + +========================= +Work with Geospatial Data +========================= + +.. 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** formats, +indexes, and queries. + +Geospatial data represents a geographic location on the surface of the Earth, or data +on a Euclidean plane. + +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 + +Store Geospatial Data +--------------------- + +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 place on Earth 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) + +.. 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 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 Euclidean 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 your 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 the sample dataset +used in the following example, 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 + + 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 Island. + +.. code-block:: csharp + + // Polygon representation of Manhattan Island + 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 From ddc19e8d4df708a22c051646d42ee0377db374b5 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 26 Jun 2024 09:11:10 -0400 Subject: [PATCH 2/6] Fixes --- source/fundamentals/geo.txt | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/source/fundamentals/geo.txt b/source/fundamentals/geo.txt index c0290a5f..aa7f61d7 100644 --- a/source/fundamentals/geo.txt +++ b/source/fundamentals/geo.txt @@ -1,8 +1,8 @@ .. _csharp-geo: -========================= -Work with Geospatial Data -========================= +================== +Geospatial Queries +================== .. facet:: :name: genre @@ -23,7 +23,7 @@ Overview In this guide, you can learn how to work with **geospatial data** formats, indexes, and queries. -Geospatial data represents a geographic location on the surface of the Earth, or data +Geospatial data represents a geographic location on the surface of the Earth or data on a Euclidean plane. Examples of geospatial data include: @@ -62,8 +62,7 @@ containing the following values: - 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. +The following is the position of the MongoDB Headquarters in New York City, NY. .. code-block:: csharp @@ -94,7 +93,7 @@ Here are some common GeoJSON types and how you can specify them with positions: - ``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 `__: + the Great Wall of China: .. code-block:: csharp @@ -108,8 +107,7 @@ Here are some common GeoJSON types and how you can specify them with positions: - ``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 Vatican City - `__: + ``Polygon`` roughly represents the land within the Vatican City: .. code-block:: csharp @@ -182,8 +180,8 @@ the server manual. Examples -------- -The following examples uses the MongoDB Atlas sample dataset. To obtain the sample dataset -used in the following example, see :ref:`csharp-quickstart`.. +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 From d9227bdf67d3b8d0f0090fa4eb048f99ed52f2de Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 26 Jun 2024 09:19:18 -0400 Subject: [PATCH 3/6] Tweaks --- source/fundamentals/geo.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/geo.txt b/source/fundamentals/geo.txt index aa7f61d7..6ae66b0b 100644 --- a/source/fundamentals/geo.txt +++ b/source/fundamentals/geo.txt @@ -34,8 +34,8 @@ Examples of geospatial data include: - Dog exercise areas in New York City - Points on a graph -Store Geospatial Data ---------------------- +Geospatial Data Formats +----------------------- All geospatial data in MongoDB is stored in one of the following formats: @@ -196,6 +196,7 @@ 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 @@ -223,7 +224,8 @@ within the boundaries of Manhattan Island. .. code-block:: csharp // Polygon representation of Manhattan Island - var polygon = GeoJson.Polygon( + var polygon = GeoJson.Polygon + ( GeoJson.Position(-73.925492, 40.877410), GeoJson.Position(-73.910372, 40.872366), GeoJson.Position(-73.935127, 40.834020), From 3b123986362da4df6020885beb06489136d7a56b Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 26 Jun 2024 13:06:33 -0400 Subject: [PATCH 4/6] Address feedback --- source/fundamentals/geo.txt | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/geo.txt b/source/fundamentals/geo.txt index 6ae66b0b..a2921f93 100644 --- a/source/fundamentals/geo.txt +++ b/source/fundamentals/geo.txt @@ -1,8 +1,8 @@ .. _csharp-geo: -================== -Geospatial Queries -================== +=================== +Search Geospatially +=================== .. facet:: :name: genre @@ -23,8 +23,7 @@ Overview In this guide, you can learn how to work with **geospatial data** formats, indexes, and queries. -Geospatial data represents a geographic location on the surface of the Earth or data -on a Euclidean plane. +Geospatial data represents a geographic location on the surface of the Earth. Examples of geospatial data include: @@ -55,7 +54,7 @@ and a **type**. Positions ````````` -A position represents a single place on Earth and exists in code as an array +A position represents a single location and exists in code as an array containing the following values: - Longitude in the first position (required) @@ -130,7 +129,7 @@ Legacy Coordinate Pairs ~~~~~~~~~~~~~~~~~~~~~~~ Use legacy coordinate pairs to store data that represents geospatial information -on a two-dimensional Euclidean plane. +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. @@ -154,7 +153,7 @@ section of the Indexes guide. Query Operators ~~~~~~~~~~~~~~~ -To query your geospatial data, use one of the following query operators: +To query geospatial data, use one of the following query operators: - ``$near`` - ``$geoWithin`` @@ -219,11 +218,11 @@ Query by Polygon ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example queries for documents with a ``location.geo`` field value that exists -within the boundaries of Manhattan Island. +within the boundaries of Manhattan. .. code-block:: csharp - // Polygon representation of Manhattan Island + // Polygon representation of Manhattan var polygon = GeoJson.Polygon ( GeoJson.Position(-73.925492, 40.877410), From e1ba94ddd1165f61c96a240ca508852e1c87fc0e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 3 Jul 2024 12:34:26 -0400 Subject: [PATCH 5/6] Address technical feedback --- source/fundamentals/geo.txt | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/geo.txt b/source/fundamentals/geo.txt index a2921f93..951e3246 100644 --- a/source/fundamentals/geo.txt +++ b/source/fundamentals/geo.txt @@ -20,7 +20,7 @@ Search Geospatially Overview -------- -In this guide, you can learn how to work with **geospatial data** formats, +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. @@ -67,6 +67,13 @@ The following is the position of the MongoDB Headquarters in New York City, NY. 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. @@ -215,7 +222,7 @@ The results of the preceding example contain the following documents: { "_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. From 3911a4e425581d02e6386566b15a59d71f6d2cca Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 3 Jul 2024 12:42:00 -0400 Subject: [PATCH 6/6] Trigger build