Skip to content

DOCSP-48207: 404s + cleanup #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 11, 2025
Merged

DOCSP-48207: 404s + cleanup #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion examples/src/test/kotlin/RetrieveDataTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ internal class RetrieveDataTest {
private val config = getConfig()
private val client = MongoClient.create(config.connectionUri)
private val database = client.getDatabase("retrieve_data")
val collection = database.getCollection<PaintOrder>("paint_order")
val collection = database.getCollection<PaintOrder>("orders")

@BeforeAll
@JvmStatic
Expand Down
4 changes: 2 additions & 2 deletions source/fundamentals/aggregation.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _kotlin-aggregation:

===========
Aggregation
===========
Expand All @@ -11,8 +13,6 @@ Aggregation
Overview
--------

.. _kotlin-aggregation:

In this guide, you can learn how to use **aggregation operations** in the MongoDB Kotlin driver.

Aggregation operations process data in your MongoDB collections and return computed results. MongoDB's Aggregation
Expand Down
2 changes: 2 additions & 0 deletions source/fundamentals/crud/query-document.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _kotlin-fundamentals-query:

===============
Specify a Query
===============
Expand Down
158 changes: 82 additions & 76 deletions source/fundamentals/crud/read-operations/geo.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,16 @@
.. _kotlin-fundamentals-geospatial-search:

===================
Search Geospatially
===================

.. facet::
:name: genre
:values: reference

.. meta::
:keywords: code example, coordinates, plane, earth

.. contents:: On this page
:local:
:backlinks: none
Expand All @@ -11,8 +20,9 @@ Search Geospatially
Overview
--------

In this guide, you can learn how to search **geospatial data** with the
MongoDB Kotlin Driver, and the different geospatial data formats supported by MongoDB.
In this guide, you can learn how to query **geospatial data** by using
the {+driver-short+}. You can also learn about different geospatial data
formats supported by MongoDB.

Geospatial data is data that represents a geographical location on
the surface of the Earth. Examples of geospatial data include:
Expand All @@ -32,7 +42,7 @@ Here is the location of MongoDB headquarters in GeoJSON:

.. code-block:: json

"MongoDB Headquarters" : {
"location" : {
"type": "point",
"coordinates": [-73.986805, 40.7620853]
}
Expand All @@ -43,7 +53,7 @@ For definitive information on GeoJSON, see the
GeoJSON Positions
~~~~~~~~~~~~~~~~~

A position represents a single place on Earth, and exists in code as an array
A position represents a single place on Earth and is given as an array
containing two or three number values:

- Longitude in the first position (required)
Expand All @@ -52,11 +62,11 @@ containing two or three number values:

.. important:: Longitude then Latitude

GeoJSON orders coordinates as longitude first and latitude second. This may
be surprising as geographic coordinate system conventions generally list
latitude first and longitude second. Make sure to check what format any other
tools you are working with use. Popular tools such as OpenStreetMap and Google
Maps list coordinates as latitude first and longitude second.
GeoJSON orders coordinates as longitude first and latitude second. This may
be surprising as geographic coordinate system conventions generally list
latitude first and longitude second. Make sure to check what format any other
tools you are working with use. Popular tools such as OpenStreetMap and Google
Maps list coordinates as latitude first and longitude second.

GeoJSON Types
~~~~~~~~~~~~~
Expand All @@ -66,70 +76,73 @@ made up of positions.

Here are some common GeoJSON types and how you can specify them with positions:

- ``Point``: a single position. This could represent the location of a
`sculpture <https://en.wikipedia.org/wiki/Chicago_Picasso>`__.
- ``LineString``: an array of two or more positions, thus forming a series of line
- ``Point``: Single position. This could represent the location of a
`sculpture <https://en.wikipedia.org/wiki/Chicago_Picasso>`__.
- ``LineString``: Array of two or more positions, thus forming a series of line
segments. This could represent
`the route of the Great Wall of China <https://commons.wikimedia.org/wiki/File:GreatWallChina4.png>`__.
- ``Polygon``: an array of positions in which the first and last
position are the same, thus enclosing some space. This could represent
- ``Polygon``: Array of positions in which the first and last
position are the same, enclosing some space. This could represent
`the land within Vatican City <https://commons.wikimedia.org/wiki/File:Vatican_City_map_EN.png>`__.


To learn more about the shapes you can use in MongoDB, see the
:manual:`GeoJSON manual entry </reference/geojson/>`.
To learn more about the shapes you can use in MongoDB, see
:manual:`GeoJSON </reference/geojson/>` in the Server manual.

Index
~~~~~

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

.. literalinclude:: /examples/generated/GeoTest.snippet.geo2dsphere-index.kt
:language: kotlin

For more information on the ``Indexes`` builder, see our
:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
To learn more about the ``Indexes`` builder, see the
:ref:`indexes-builders` guide.

Coordinates on a 2D Plane
-------------------------

You can store geospatial data using ``x`` and ``y`` coordinates on
a two-dimensional Euclidean plane. We refer to coordinates on a two-dimensional
plane as "legacy coordinate pairs".
plane as *legacy coordinate pairs*.

Legacy coordinate pairs have the following structure:

.. code-block:: json

"<field name>" : [ x, y ]
{ "location" : [ x, y ] }

Your field should contain an array of two values in which the first represents
The field value contains an array of two values in which the first represents
the ``x`` axis value and the second represents the ``y`` axis value.

Index
~~~~~

To query data stored as legacy coordinate pairs, you must add the field containing
legacy coordinate pairs to a ``2d`` index. The following snippet creates a
``2d`` index on the ``coordinates`` field using the ``Indexes`` builder:
``2d`` index on the ``coordinates`` field by using the ``Indexes`` builder:

.. literalinclude:: /examples/generated/GeoTest.snippet.geo2d-index.kt
:language: kotlin

For more information on the ``Indexes`` builder, see our
:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
To learn more about the ``Indexes`` builder, see the
:ref:`indexes-builders` guide.

For more information on legacy coordinate pairs, see the
:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
:manual:`Legacy Coordinate Pairs
</geospatial-queries/#legacy-coordinate-pairs>` section of the
Geospatial Queries guide in the Server manual.

.. tip:: Supported Operators

Spherical (``2dsphere``) and flat (``2d``) indexes support some, but
not all, of the same query operators. For a full list of operators
and their index compatibility, see the
:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
not all, of the same query operators. To view a full list of operators
and their index compatibility, see the :manual:`Geospatial Query
Operators </geospatial-queries/#geospatial-query-operators>` section
of the Geospatial Queries guide in the Server manual.

Geospatial Queries
------------------
Expand All @@ -151,58 +164,56 @@ You can specify these query operators in the MongoDB Kotlin driver with the
``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility
methods of the ``Filters`` builder class.

For more information on geospatial query operators, see the
:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
To learn more about geospatial query operators, see the :manual:`Geospatial Query
Operators </geospatial-queries/#geospatial-query-operators>` section
of the Geospatial Queries guide in the Server manual.

For more information on ``Filters``, see our
:doc:`guide on the Filters builder </fundamentals/builders/filters>`.
To learn more about the ``Filters`` builder, see the
:ref:`filters-builders` guide.

Query Parameters
~~~~~~~~~~~~~~~~

To specify a shape to use in a geospatial query, use the
``Position``, ``Point``, ``LineString``, and ``Polygon`` classes of the MongoDB
Kotlin driver.
To specify a shape to use in a geospatial query, use the ``Position``,
``Point``, ``LineString``, and ``Polygon`` classes from the {+driver-short+}.

For a full list of the GeoJSON shapes available in the MongoDB Kotlin driver, see the
`GeoJSON package
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
To learn more about the GeoJSON shape classes, see the
`GeoJSON package <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
API Documentation.

Examples
--------
Geospatial Query Examples
-------------------------

The following examples use the MongoDB Atlas sample dataset. You can learn how
to set up your own free-tier Atlas cluster and how to load the sample dataset
in our :doc:`quick start guide </quick-start>`.
in the :ref:`kotlin-quickstart` guide.

The examples use the ``theaters`` collection in the ``sample_mflix`` database
from the sample dataset.

The examples require the following imports:
The examples in this section require the following imports:

.. code-block::
:source: kotlin
.. code-block:: kotlin

import com.mongodb.client.model.geojson.Point
import com.mongodb.client.model.geojson.Polygon
import com.mongodb.client.model.geojson.Position
import com.mongodb.client.model.Filters.near
import com.mongodb.client.model.Filters.geoWithin
import com.mongodb.client.model.Projections.fields
import com.mongodb.client.model.Projections.include
import com.mongodb.client.model.Projections.excludeId
import com.mongodb.client.model.geojson.Point
import com.mongodb.client.model.geojson.Polygon
import com.mongodb.client.model.geojson.Position
import com.mongodb.client.model.Filters.near
import com.mongodb.client.model.Filters.geoWithin
import com.mongodb.client.model.Projections.fields
import com.mongodb.client.model.Projections.include
import com.mongodb.client.model.Projections.excludeId

The data is modeled using the following Kotlin data class:
The sample documents are modeled by the following {+language+} data class:

.. literalinclude:: /examples/generated/GeoTest.snippet.theater-data-class.kt
:language: kotlin
:language: kotlin

The results are modeled using the following Kotlin data class:
The result documents are modeled by the following {+language+} data class:

.. literalinclude:: /examples/generated/GeoTest.snippet.results-data-class.kt
:language: kotlin
:language: kotlin

The ``theaters`` collection already contains a ``2dsphere`` index on the
``"${Theater::location.name}.${Theater.Location::geo.name}"`` field.

Expand All @@ -213,8 +224,8 @@ To search for and return documents from nearest to farthest from a point, use
the ``near()`` static utility method of the ``Filters`` builder class. The
``near()`` method constructs a query with the ``$near`` query operator.

The following example queries for theaters between ``10,000`` and ``5,000``
meters from the Great Lawn of Central Park:
The following example queries for movie theaters between ``10000`` and
``5000`` meters from the Great Lawn of Central Park:

.. io-code-block::

Expand All @@ -237,17 +248,14 @@ meters from the Great Lawn of Central Park:
TheaterResults(location=Location(address=Address(city=Flushing)))
TheaterResults(location=Location(address=Address(city=Elmhurst)))

.. tip:: Fun Fact
.. tip::

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

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

For more information on ``Filters``, see
:doc:`our guide on the Filters builder </fundamentals/builders/filters>`.
To learn more about the ``$near`` operator, see the
:manual:`$near </reference/operator/query/near/>` reference in the
Server manual.

Query Within a Range
~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -276,13 +284,11 @@ The following example searches for movie theaters in a section of Long Island.

The following figure shows the polygon defined by the
``longIslandTriangle`` variable and dots representing the locations of
the movie theaters returned by our query.
the movie theaters returned by our query.

.. figure:: /includes/figures/geo_geometry.png
:alt: Area of Long Island we are searching for movie theaters

For more information on the ``$geoWithin`` operator, see the
:manual:`reference documentation for $geoWithin </reference/operator/query/geoWithin/>`
:alt: Area of Long Island in which to search for movie theaters

For more information on the operators you can use in your query, see the
:manual:`MongoDB server manual page on geospatial query operators </geospatial-queries/index.html>`
To learn more about the ``$geoWithin`` operator, see the
:manual:`$geoWithin </reference/operator/query/geoWithin/>` reference in
the Server manual.
Loading
Loading