8000 (DOCSP-29210): CRUD > Search Geospatially page (#13) · nickldp/docs-kotlin@a765961 · GitHub
[go: up one dir, main page]
Skip to content

Commit a765961

Browse files
cbullingercbullinger
authored
(DOCSP-29210): CRUD > Search Geospatially page (mongodb#13)
# Pull Request Info JIRA - https://jira.mongodb.org/browse/DOCSP-29210 Staging - https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/docsp-29210-geo/fundamentals/crud/read-operations/geo/ [PR Reviewing Guidelines](https://github.com/mongodb/docs-java/blob/master/REVIEWING.md) ## Pages Updated CRUD > Read Operations > Search Geospatially page ## Changes Made - Copy is unchanged from ([Java version](https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/crud/read-operations/geo/)) of page, except where noted - Replace all code examples with generated, tested Kotlin examples ## Checklist - [ ] Are TOCs updated? If landing page, is page added to `snooty.toml`? - [ ] Is .rst file renamed to .txt to ensure it's published? - [ ] Are all API links flagged for TODO (to be updated when API Ref docs are published)? ### Self-Review Checklist - [ ] Is this free of any warnings or errors in the RST? - [ ] Did you run a spell-check? - [ ] Did you run a grammar-check? - [ ] Are all the links working?
1 parent 36f12bf commit a765961

File tree

8 files changed

+527
-79
lines changed

8 files changed

+527
-79
lines changed

‎examples/src/test/kotlin/GeoTest.kt

Lines changed: 401 additions & 0 deletions
Large diffs are not rendered by default.

‎source/examples/generated/GeoTest.snippet.geo2d-index.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
collection.createIndex((Indexes.geo2d("coordinates")))

‎source/examples/generated/GeoTest.snippet.geo2dsphere-index.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
collection.createIndex((Indexes.geo2dsphere("location.geo")))

‎source/examples/generated/GeoTest.snippet.proximity-query.kt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
val database = client.getDatabase("sample_mflix")
2+
val collection = database.getCollection<TheaterResults>("theaters")
3+
val centralPark = Point(Position(-73.9667, 40.78))
4+
val query = Filters.near(
5+
"${Theater::location.name}.${Theater.Location::geo.name}", centralPark, 10000.0, 5000.0
6+
)
7+
val projection = Projections.fields(
8+
Projections.include(
9+
"${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
10+
Projections.excludeId()
11+
)
12+
val resultsFlow = collection.find(query).projection(projection)
13+
resultsFlow.collect { println(it) }

‎source/examples/generated/GeoTest.snippet.query-range.kt

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
val longIslandTriangle = Polygon(
2+
listOf(
3+
Position(-72.0, 40.0),
4+
Position(-74.0, 41.0),
5+
Position(-72.0, 39.0),
6+
Position(-72.0, 40.0)
7+
)
8+
)
9+
val projection = Projections.fields(
10+
Projections.include(
11+
"${Theater::location.name}.${Theater.Location::address.name}.${Theater.Location.Address::city.name}"),
12+
Projections.excludeId()
13+
)
14+
val geoWithinComparison = Filters.geoWithin(
15+
"${Theater::location.name}.${Theater.Location::geo.name}", longIslandTriangle
16+
)
17+
val resultsFlow = collection.find<TheaterResults>(geoWithinComparison)
18+
.projection(projection)
19+
resultsFlow.collect { println(it) }

‎source/examples/generated/GeoTest.snippet.results-data-class.kt

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
data class TheaterResults(
2+
val location: Location
3+
) {
4+
data class Location(
5+
val address: Address
6+
) {
7+
data class Address(
8+
val city: String
9+
)
10+
}
11+
}
12+

‎source/examples/generated/GeoTest.snippet.theater-data-class.kt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
data class Theater(
2+
val theaterId: Int,
3+
val location: Location
4+
) {
5+
data class Location(
6+
val address: Address,
7+
val geo: Point
8+
) {
9+
data class Address(
10+
val street1: String,
11+
val street2: String? = null,
12+
val city: String,
13+
val state: String,
14+
val zipcode: String
15+
)
16+
}
17+
}

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

Lines changed: 63 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Overview
1414
--------
1515

1616
In this guide, you can learn how to search **geospatial data** with the
17-
MongoDB Java Driver, and the different geospatial data formats supported by MongoDB.
17+
MongoDB Kotlin Driver, and the different geospatial data formats supported by MongoDB.
1818

1919
Geospatial data is data that represents a geographical location on
2020
the surface of the Earth. Examples of geospatial data include:
@@ -42,8 +42,6 @@ Here is the location of MongoDB headquarters in GeoJSON:
4242
For definitive information on GeoJSON, see the
4343
`official IETF specification <https://datatracker.ietf.org/doc/html/rfc7946>`__.
4444

45-
.. external resource
46-
4745
GeoJSON Positions
4846
~~~~~~~~~~~~~~~~~
4947

@@ -83,25 +81,19 @@ Here are some common GeoJSON types and how you can specify them with positions:
8381
To learn more about the shapes you can use in MongoDB, see the
8482
:manual:`GeoJSON manual entry </reference/geojson/>`.
8583

86-
.. external resource
87-
8884
Index
8985
~~~~~
9086

9187
To query data stored in the GeoJSON format, add the field containing
9288
GeoJSON data to a ``2dsphere`` index. The following snippet creates a
9389
``2dsphere`` index on the ``location.geo`` field using the ``Indexes`` builder:
9490

95-
.. code-block:: java
96-
97-
// <MongoCollection setup code here>
98-
collection.createIndex(Indexes.geo2dsphere("location.geo"));
91+
.. literalinclude:: /examples/generated/GeoTest.snippet.geo2dsphere-index.kt
92+
:language: kotlin
9993

10094
For more information on the ``Indexes`` builder, see our
10195
:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
10296

103-
.. guide resource
104-
10597
Coordinates on a 2D Plane
10698
-------------------------
10799

@@ -125,28 +117,22 @@ To query data stored as legacy coordinate pairs, you must add the field containi
125117
legacy coordinate pairs to a ``2d`` index. The following snippet creates a
126118
``2d`` index on the ``coordinates`` field using the ``Indexes`` builder:
127119

128-
.. code-block:: java
129-
130-
// <MongoCollection setup code here>
131-
collection.createIndex(Indexes.geo2d("coordinates"));
120+
.. literalinclude:: /examples/generated/GeoTest.snippet.geo2d-index.kt
121+
:language: kotlin
132122

133123
For more information on the ``Indexes`` builder, see our
134124
:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
135125

136126
For more information on legacy coordinate pairs, see the
137127
:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
138128

139-
.. external resource
140-
141129
.. tip:: Supported Operators
142130

143131
Spherical (``2dsphere``) and flat (``2d``) indexes support some, but
144132
not all, of the same query operators. For a full list of operators
145133
and their index compatibility, see the
146134
:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
147135

148-
.. external resource
149-
150136
Geospatial Queries
151137
------------------
152138

@@ -163,15 +149,13 @@ To query your geospatial data, use one of the following query operators:
163149
- ``$nearSphere``
164150
- ``$geoIntersects`` *requires a 2dsphere index*
165151

166-
You can specify these query operators in the MongoDB Java driver with the
152+
You can specify these query operators in the MongoDB Kotlin driver with the
167153
``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility
168154
methods of the ``Filters`` builder class.
169155

170156
For more information on geospatial query operators, see the
171157
:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
172158

173-
.. external resource
174-
175159
For more information on ``Filters``, see our
176160
:doc:`guide on the Filters builder </fundamentals/builders/filters>`.
177161

@@ -180,15 +164,13 @@ Query Parameters
180164

181165
To specify a shape to use in a geospatial query, use the
182166
``Position``, ``Point``, ``LineString``, and ``Polygon`` classes of the MongoDB
183-
Java driver.
167+
Kotlin driver.
184168

185-
For a full list of the GeoJSON shapes available in the MongoDB Java driver, see the
169+
For a full list of the GeoJSON shapes available in the MongoDB Kotlin driver, see the
186170
`GeoJSON package
187171
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
188172
API Documentation.
189173

190-
.. external resource
191-
192174
Examples
193175
--------
194176

@@ -197,21 +179,34 @@ to set up your own free-tier Atlas cluster and how to load the sample dataset
197179
in our :doc:`quick start guide </quick-start>`.
198180

199181
The examples use the ``theaters`` collection in the ``sample_mflix`` database
200-
from the sample dataset. The ``theaters`` collection contains a ``2dsphere`` index
201-
on the ``location.geo`` field.
182+
from the sample dataset.
202183

203184
The examples require the following imports:
204185

205-
.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
206-
:language: java
207-
:dedent:
208-
:start-after: begin exampleImports
209-
:end-before: end exampleImports
186+
.. code-block::
187+
:source: kotlin
188+
189+
import com.mongodb.client.model.geojson.Point
190+
import com.mongodb.client.model.geojson.Polygon
191+
import com.mongodb.client.model.geojson.Position
192+
import com.mongodb.client.model.Filters.near
193+
import com.mongodb.client.model.Filters.geoWithin
194+
import com.mongodb.client.model.Projections.fields
195+
import com.mongodb.client.model.Projections.include
196+
import com.mongodb.client.model.Projections.excludeId
197+
198+
The data is modeled using the following Kotlin data class:
199+
200+
.. literalinclude:: /examples/generated/GeoTest.snippet.theater-data-class.kt
201+
:language: kotlin
210202

211-
You can find the
212-
`source code for the examples on Github here <https://github.com/mongodb/docs-java/blob/master/source/includes/fundamentals/code-snippets/Geo.java>`__.
203+
The results are modeled using the following Kotlin data class:
213204

214-
.. external resource
205+
.. literalinclude:: /examples/generated/GeoTest.snippet.results-data-class.kt
206+
:language: kotlin
207+
208+
The ``theaters`` collection already contains a ``2dsphere`` index on the
209+
``"${Theater::location.name}.${Theater.Location::geo.name}"`` field.
215210

216211
Query by Proximity
217212
~~~~~~~~~~~~~~~~~~
@@ -221,44 +216,40 @@ the ``near()`` static utility method of the ``Filters`` builder class. The
221216
``near()`` method constructs a query with the ``$near`` query operator.
222217

223218
The following example queries for theaters between ``10,000`` and ``5,000``
224-
meters from the
225-
`Great Lawn of Central Park <https://en.wikipedia.org/wiki/Great_Lawn_and_Turtle_Pond>`__.
219+
meters from the Great Lawn of Central Park:
226220

227-
.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
228-
:language: java
229-
:dedent:
230-
:start-after: begin findExample
231-
:end-before: end findExample
221+
.. io-code-block::
232222

233-
The output of the code snippet should look something like this:
223+
.. input:: /examples/generated/GeoTest.snippet.proximity-query.kt
224+
:language: kotlin
234225

235-
.. code-block:: json
236-
:copyable: false
226+
.. output::
227+
:language: console
237228

238-
{"location": {"address": {"city": "Bronx"}}}
239-
{"location": {"address": {"city": "New York"}}}
240-
{"location": {"address": {"city": "New York"}}}
241-
{"location": {"address": {"city": "Long Island City"}}}
242-
{"location": {"address": {"city": "New York"}}}
243-
{"location": {"address": {"city": "Secaucus"}}}
244-
{"location": {"address": {"city": "Jersey City"}}}
245-
{"location": {"address": {"city": "Elmhurst"}}}
246-
{"location": {"address": {"city": "Flushing"}}}
247-
{"location": {"address": {"city": "Flushing"}}}
248-
{"location": {"address": {"city": "Flushing"}}}
249-
{"location": {"address": {"city": "Elmhurst"}}}
229+
TheaterResults(location=Location(address=Address(city=Bronx)))
230+
TheaterResults(location=Location(address=Address(city=New York)))
231+
TheaterResults(location=Location(address=Address(city=New York)))
232+
TheaterResults(location=Location(address=Address(city=Long Island City)))
233+
TheaterResults(location=Location(address=Address(city=New York)))
234+
TheaterResults(location=Location(address=Address(city=Secaucus)))
235+
TheaterResults(location=Location(address=Address(city=Jersey City)))
236+
TheaterResults(location=Location(address=Address(city=Elmhurst)))
237+
TheaterResults(location=Location(address=Address(city=Flushing)))
238+
TheaterResults(location=Location(address=Address(city=Flushing)))
239+
TheaterResults(location=Location(address=Address(city=Flushing)))
240+
TheaterResults(location=Location(address=Address(city=Elmhurst)))
250241

251242
.. tip:: Fun Fact
252243

253244
MongoDB uses the
254245
:manual:`same reference system </reference/glossary/#std-term-WGS84>`
255246
as GPS satellites to calculate geometries over the Earth.
256247

257-
For more information on the ``$near`` operator, see
258-
:manual:`the reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
248+
For more information on the ``$near`` operator, see the
249+
:manual:`reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
259250

260-
For more information on ``Filters``,
261-
:doc:`see our guide on the Filters builder </fundamentals/builders/filters>`.
251+
For more information on ``Filters``, see
252+
:doc:`our guide on the Filters builder </fundamentals/builders/filters>`.
262253

263254
Query Within a Range
264255
~~~~~~~~~~~~~~~~~~~~
@@ -271,22 +262,19 @@ The following example searches for movie theaters in a section of Long Island.
271262

272263
.. _example_range_query:
273264

274-
.. literalinclude:: /includes/fundamentals/code-snippets/Geo.java
275-
:language: java
276-
:dedent:
277-
:start-after: begin rangeExample
278-
:end-before: end rangeExample
265+
.. io-code-block::
279266

280-
The output of the code snippet should look something like this:
267+
.. input:: /examples/generated/GeoTest.snippet.query-range.kt
268+
:language: kotlin
281269

282-
.. code-block:: json
283-
:copyable: false
270+
.. output::
271+
:language: console
284272

285-
{"location": {"address": {"city": "Baldwin"}}}
286-
{"location": {"address": {"city": "Levittown"}}}
287-
{"location": {"address": {"city": "Westbury"}}}
288-
{"location": {"address": {"city": "Mount Vernon"}}}
289-
{"location": {"address": {"city": "Massapequa"}}}
273+
TheaterResults(location=Location(address=Address(city=Baldwin))))
274+
TheaterResults(location=Location(address=Address(city=Levittown)))
275+
TheaterResults(location=Location(address=Address(city=Westbury)))
276+
TheaterResults(location=Location(address=Address(city=Mount Vernon)))
277+
TheaterResults(location=Location(address=Address(city=Massapequa)))
290278

291279
The following figure shows the polygon defined by the
292280
``longIslandTriangle`` variable and dots representing the locations of
@@ -298,9 +286,5 @@ the movie theaters returned by our query.
298286
For more information on the ``$geoWithin`` operator, see the
299287
:manual:`reference documentation for $geoWithin </reference/operator/query/geoWithin/>`
300288

301-
.. external resource
302-
303289
For more information on the operators you can use in your query, see the
304290
:manual:`MongoDB server manual page on geospatial query operators </geospatial-queries/index.html>`
305-
306-
.. external resource

0 commit comments

Comments
 (0)
0