Skip to content

Commit 3ee3889

Browse files
mcmorisimcmorisi
committed
DOCSP-40574: Add Geospatial page (#215)
(cherry picked from commit 627d6ec)
1 parent 629c189 commit 3ee3889

File tree

5 files changed

+284
-2
lines changed

5 files changed

+284
-2
lines changed

‎source/fundamentals.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Fundamentals
2929
/fundamentals/logging
3030
/fundamentals/time-series
3131
/fundamentals/encrypt-fields
32+
/fundamentals/geo
3233

3334
- :ref:`Connecting to MongoDB <csharp-connection>`
3435
- :ref:`csharp-db-coll`
@@ -48,3 +49,4 @@ Fundamentals
4849
- :ref:`csharp-logging`
4950
- :ref:`csharp-time-series`
5051
- :ref:`Encrypt Fields <csharp-fle>`
52+
- :ref:`csharp-geo`

‎source/fundamentals/builders.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -448,7 +448,7 @@ perform the following operations:
448448
.Include(m => m.Title)
449449
.Include(m => m.Plot));
450450

451-
The results of the preeding example contain the following documents:
451+
The results of the preceding example contain the following documents:
452452

453453
.. code-block:: json
454454

‎source/fundamentals/geo.txt

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
.. _csharp-geo:
2+
3+
===================
4+
Search Geospatially
5+
===================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, coordinates, location, geographic
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to work with **geospatial data**, data formats,
24+
indexes, and queries.
25+
26+
Geospatial data represents a geographic location on the surface of the Earth.
27+
28+
Examples of geospatial data include:
29+
30+
- Locations of movie theaters
31+
- Borders of countries
32+
- Routes of bicycle rides
33+
- Dog exercise areas in New York City
34+
- Points on a graph
35+
36+
Geospatial Data Formats
37+
-----------------------
38+
39+
All geospatial data in MongoDB is stored in one of the following formats:
40+
41+
- GeoJSON, a format that represents geospatial data on an earth-like
42+
sphere.
43+
44+
- Legacy coordinate pairs, a format that represents geospatial data
45+
on a Euclidean plane.
46+
47+
GeoJSON
48+
~~~~~~~
49+
50+
Use GeoJSON to store data that represents geospatial information on
51+
an earth-like sphere. GeoJSON is composed of one or more **positions**
52+
and a **type**.
53+
54+
Positions
55+
`````````
56+
57+
A position represents a single location and exists in code as an array
58+
containing the following values:
59+
60+
- Longitude in the first position (required)
61+
- Latitude in the second position (required)
62+
- Elevation in the third position (optional)
63+
64+
The following is the position of the MongoDB Headquarters in New York City, NY.
65+
66+
.. code-block:: csharp
67+
68+
GeoJson.Position(-73.986805, 40.7620853)
69+
70+
Alternatively, you can use the ``GeoJson.Geographic()`` method to construct a coordinate
71+
pair.
72+
73+
.. code-block:: csharp
74+
75+
GeoJson.Geographic(-73.986805, 40.7620853)
76+
77+
.. important:: Longitude then Latitude
78+
79+
GeoJSON orders coordinates with longitude first and latitude second.
80+
Make sure to check what format any other tools you are working with use, since many popular
81+
tools such as OpenStreetMap and Google Maps list coordinates with latitude first and
82+
longitude second.
83+
84+
Types
85+
`````
86+
87+
The type of your GeoJSON object determines the geometric shape it represents. Geometric
88+
shapes are made up of positions.
89+
90+
Here are some common GeoJSON types and how you can specify them with positions:
91+
92+
- ``Point``: a single position. The following ``Point`` represents the location of
93+
the MongoDB Headquarters:
94+
95+
.. code-block:: csharp
96+
97+
GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853))
98+
99+
- ``LineString``: an array of two or more positions that forms a series of line
100+
segments. A ``LineString`` can represent a path, route, border, or any other linear
101+
geospatial data. The following ``LineString`` represents a segment of
102+
the Great Wall of China:
103+
104+
.. code-block:: csharp
105+
106+
GeoJson.LineString
107+
(
108+
GeoJson.Position(116.572, 40.430),
109+
GeoJson.Position(116.570, 40.434),
110+
GeoJson.Position(116.567, 40.436),
111+
GeoJson.Position(116.566, 40.441)
112+
)
113+
114+
- ``Polygon``: an array of positions in which the first and last
115+
position are the same and enclose some space. The following
116+
``Polygon`` roughly represents the land within the Vatican City:
117+
118+
.. code-block:: csharp
119+
120+
GeoJson.Polygon
121+
(
122+
GeoJson.Position(12.446086, 41.901977),
123+
GeoJson.Position(12.457952, 41.901559),
124+
GeoJson.Position(12.455375, 41.907351),
125+
GeoJson.Position(12.449863, 41.905186),
126+
GeoJson.Position(12.446086, 41.901977)
127+
}
128+
129+
To learn more about the GeoJSON types you can use in MongoDB, see the
130+
:manual:`GeoJSON manual entry </reference/geojson/>`.
131+
132+
For more information on the GeoJSON format, see the
133+
`official IETF specification <https://datatracker.ietf.org/doc/html/rfc7946>`__.
134+
135+
Legacy Coordinate Pairs
136+
~~~~~~~~~~~~~~~~~~~~~~~
137+
138+
Use legacy coordinate pairs to store data that represents geospatial information
139+
on a two-dimensional plane.
140+
141+
Legacy coordinate pairs are represented by an array of two values, in which the first
142+
represents the ``x`` axis value and the second represents the ``y`` axis value.
143+
144+
For more information on legacy coordinate pairs, see the
145+
:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
146+
147+
Geospatial Indexes
148+
------------------
149+
150+
To enable querying on geospatial data, you must create an index that
151+
corresponds to the data format. The following index types enable geospatial
152+
queries:
153+
154+
- ``2dsphere``, used for GeoJSON data
155+
- ``2d``, used for legacy coordinate pairs
156+
157+
To learn more about how to create geospatial indexes, see the :ref:`geospatial-indexes`
158+
section of the Indexes guide.
159+
160+
Query Operators
161+
~~~~~~~~~~~~~~~
162+
163+
To query geospatial data, use one of the following query operators:
164+
165+
- ``$near``
166+
- ``$geoWithin``
167+
- ``$nearSphere``
168+
- ``$geoIntersects`` (*requires a 2dsphere index*)
169+
170+
When using the ``$near`` operator, you can specify the following distance operators:
171+
172+
- ``$minDistance``
173+
- ``$maxDistance``
174+
175+
When using the ``$geoWithin`` operator, you can specify the following shape operators:
176+
177+
- ``$box``
178+
- ``$polygon``
179+
- ``$center``
180+
- ``$centerSphere``
181+
182+
For more information on geospatial query operators, see
183+
:manual:`Geospatial Query Operators </geospatial-queries/#geospatial-query-operators>` in
184+
the server manual.
185+
186+
Examples
187+
--------
188+
189+
The following examples uses the MongoDB Atlas sample dataset. To obtain this sample
190+
dataset, see :ref:`csharp-quickstart`.
191+
192+
The examples use the ``theaters`` collection in the ``sample_mflix`` database
193+
from the sample dataset. The ``theaters`` collection contains a ``2dsphere`` index
194+
on the ``location.geo`` field.
195+
196+
Query by Proximity
197+
~~~~~~~~~~~~~~~~~~
198+
199+
The following example queries for documents with a ``location.geo`` field value
200+
within 1000 meters of the MongoDB Headquarters in New York City, NY. It returns documents
201+
from nearest to farthest.
202+
203+
.. code-block:: csharp
204+
205+
// Point representation of the MongoDB Headquarters
206+
var point = GeoJson.Point(GeoJson.Position(-73.986805, 40.7620853));
207+
208+
// Specifies a maxDistance of 1000 meters and a minDistance of 0 meters
209+
var filter = Builders<Theater>.Filter.Near(m => m.Location.Geo, point, 1000.0, 0.0);
210+
211+
// Only fetches the _id and theaterId fields
212+
var projection = Builders<Theater>.Projection.Include("theaterId");
213+
214+
var results = collection.Find(filter).Project(projection);
215+
216+
The results of the preceding example contain the following documents:
217+
218+
.. code-block:: json
219+
:copyable: False
220+
221+
{ "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
222+
{ "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }
223+
224+
Query by Polygon
225+
~~~~~~~~~~~~~~~~
226+
227+
The following example queries for documents with a ``location.geo`` field value that exists
228+
within the boundaries of Manhattan.
229+
230+
.. code-block:: csharp
231+
232+
// Polygon representation of Manhattan
233+
var polygon = GeoJson.Polygon
234+
(
235+
GeoJson.Position(-73.925492, 40.877410),
236+
GeoJson.Position(-73.910372, 40.872366),
237+
GeoJson.Position(-73.935127, 40.834020),
238+
GeoJson.Position(-73.929049, 40.798569),
239+
GeoJson.Position(-73.976485, 40.711432),
240+
GeoJson.Position(-74.015747, 40.701229),
241+
GeoJson.Position(-74.018859, 40.708367),
242+
GeoJson.Position(-74.008007, 40.754307),
243+
GeoJson.Position(-73.925492, 40.877410)
244+
);
245+
246+
var filter = Builders<Theater>.Filter.GeoWithin(m => m.Location.Geo, polygon);
247+
248+
// Only fetches the _id and theaterId fields
249+
var projection = Builders<Theater>.Projection.Include("theaterId");
250+
251+
var results = collection.Find(filter).Project(projection);
252+
253+
The results of the preceding example contain the following documents:
254+
255+
.. code-block:: json
256+
:copyable: False
257+
258+
{ "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
259+
{ "_id" : ObjectId("59a47287cfa9a3a73e51eccb"), "theaterId" : 835 }
260+
{ "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }
261+
{ "_id" : ObjectId("59a47286cfa9a3a73e51e744"), "theaterId" : 1028 }
262+
{ "_id" : ObjectId("59a47287cfa9a3a73e51ebe1"), "theaterId" : 609 }
263+
{ "_id" : ObjectId("59a47287cfa9a3a73e51e8ed"), "theaterId" : 1906 }
264+
{ "_id" : ObjectId("59a47287cfa9a3a73e51e87d"), "theaterId" : 1531 }
265+
{ "_id" : ObjectId("59a47287cfa9a3a73e51eb63"), "theaterId" : 482 }
266+
267+
Additional Resources
268+
--------------------
269+
270+
- For more information about working with geospatial data, see the
271+
:ref:`manual entry for geospatial data <geo-overview-location-data>`.
272+
273+
- For more information about supported GeoJSON types, see the the
274+
:manual:`GeoJSON manual entry </reference/geojson/>`.
275+
276+
- For more information about geospatial query operators, see the
277+
:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
278+

‎source/fundamentals/indexes.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,6 +308,8 @@ fields within the ``sample_mflix.movies`` collection:
308308
For more information, see :manual:`Compound Text Index Restrictions </core/indexes/index-types/index-text/text-index-restrictions/#compound-text-index>`
309309
and :manual:`Text Indexes </core/index-text>` in the Server manual.
310310

311+
.. _geospatial-indexes:
312+
311313
Geospatial Indexes
312314
~~~~~~~~~~~~~~~~~~
313315

‎source/fundamentals/linq.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -547,7 +547,7 @@ the ``plot_embedding`` field using vector embeddings for the string ``"time trav
547547
.VectorSearch(m => m.Embedding, vector, 10, options)
548548
.Select(m => new { m.Title, m.Plot });
549549

550-
The results of the preeding example contain the following documents:
550+
The results of the preceding example contain the following documents:
551551

552552
.. code-block:: json
553553

0 commit comments

Comments
 (0)