diff --git a/examples/src/test/kotlin/RetrieveDataTest.kt b/examples/src/test/kotlin/RetrieveDataTest.kt index a94b3fda..6ffc2f62 100644 --- a/examples/src/test/kotlin/RetrieveDataTest.kt +++ b/examples/src/test/kotlin/RetrieveDataTest.kt @@ -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("paint_order") + val collection = database.getCollection("orders") @BeforeAll @JvmStatic diff --git a/source/fundamentals/aggregation.txt b/source/fundamentals/aggregation.txt index 1088fec6..86d728fb 100644 --- a/source/fundamentals/aggregation.txt +++ b/source/fundamentals/aggregation.txt @@ -1,3 +1,5 @@ +.. _kotlin-aggregation: + =========== Aggregation =========== @@ -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 diff --git a/source/fundamentals/crud/query-document.txt b/source/fundamentals/crud/query-document.txt index af9f44d7..1e422f13 100644 --- a/source/fundamentals/crud/query-document.txt +++ b/source/fundamentals/crud/query-document.txt @@ -1,3 +1,5 @@ +.. _kotlin-fundamentals-query: + =============== Specify a Query =============== diff --git a/source/fundamentals/crud/read-operations/geo.txt b/source/fundamentals/crud/read-operations/geo.txt index 3665d5d4..53a8fc8b 100644 --- a/source/fundamentals/crud/read-operations/geo.txt +++ b/source/fundamentals/crud/read-operations/geo.txt @@ -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 @@ -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: @@ -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] } @@ -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) @@ -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 ~~~~~~~~~~~~~ @@ -66,46 +76,46 @@ 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 `__. -- ``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 `__. +- ``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 `__. -- ``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 `__. - -To learn more about the shapes you can use in MongoDB, see the -:manual:`GeoJSON manual entry `. +To learn more about the shapes you can use in MongoDB, see +:manual:`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 `. +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 - "" : [ 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 @@ -113,23 +123,26 @@ 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 `. +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 `. +:manual:`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 `. + not all, of the same query operators. To view a full list of operators + and their index compatibility, see the :manual:`Geospatial Query + Operators ` section + of the Geospatial Queries guide in the Server manual. Geospatial Queries ------------------ @@ -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 `. +To learn more about geospatial query operators, see the :manual:`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 `. +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 `. +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. @@ -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:: @@ -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 ` + MongoDB uses the :manual:`same reference system ` as GPS satellites to calculate geometries over the Earth. -For more information on the ``$near`` operator, see the -:manual:`reference documentation for $near `. - -For more information on ``Filters``, see -:doc:`our guide on the Filters builder `. +To learn more about the ``$near`` operator, see the +:manual:`$near ` reference in the +Server manual. Query Within a Range ~~~~~~~~~~~~~~~~~~~~ @@ -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 ` + :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 ` +To learn more about the ``$geoWithin`` operator, see the +:manual:`$geoWithin ` reference in +the Server manual. diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt index b8a7b185..2419fb89 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -1,8 +1,15 @@ .. _kotlin-fundamentals-retrieve-data: -============== +============= Retrieve Data -============== +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, read, query, filter .. contents:: On this page :local: @@ -14,23 +21,27 @@ Overview -------- In this guide, you can learn how to retrieve data from your MongoDB -database. To retrieve data, use read operations. +database by using the {+driver-short+}. You can perform **read +operations** to retrieve data from MongoDB. -Read operations allow you to do the following: +Read operations enable you to perform the following tasks: -- Retrieve a subset of documents from your collection using a :ref:`find operation ` -- Perform transformations on retrieved documents from your collection using an :ref:`aggregate operation ` -- Monitor real-time changes to your database using :ref:`change streams ` +- Retrieve a subset of documents from your collection using a :ref:`find + operation ` +- Perform transformations on retrieved documents from your collection + using an :ref:`aggregate operation ` +- Monitor real-time changes to your database using :ref:`change streams + ` .. _retrieve-paint-order-collection: Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ -The following sections feature examples of how the owner of a paint -store manages their customers' orders. For each order, the owner keeps +The following sections include examples that demonstrate how you can +manage customer orders for cans of paint. For each order, you keep track of the color and quantity, which corresponds to the ``color`` and -``qty`` fields in their ``paint_order`` collection: +``qty`` fields in documents in the ``orders`` collection: .. code-block:: json @@ -39,7 +50,7 @@ track of the color and quantity, which corresponds to the ``color`` and { "_id": 3, "color": "purple", "qty": 4 } { "_id": 4, "color": "green", "qty": 11 } -This data is modeled with the following Kotlin data class: +This data is modeled by the following {+language+} data class: .. literalinclude:: /examples/generated/RetrieveDataTest.snippet.retrieve-data-model.kt :language: kotlin @@ -56,16 +67,15 @@ to retrieve, in what order to retrieve them, and how many to retrieve. To perform a find operation, call the ``find()`` method on an instance of a ``MongoCollection``. This method searches a collection for documents that match the query filter you provide. For more information on how to -specify a query, see our :doc:`Specify a Query -` guide. +specify a query, see the :ref:`kotlin-fundamentals-query` guide. Example ~~~~~~~ -The owner would like to know which orders contain greater than three, but -less than nine cans of paint from their :ref:`paint_order collection `. +You want to know which orders contain greater than ``3``, but +less than ``9`` cans of paint. -To address this scenario, the owner finds orders to match the criteria: +Run the following code to find orders to match the criteria: .. io-code-block:: @@ -78,40 +88,37 @@ To address this scenario, the owner finds orders to match the criteria: PaintOrder(id=2, qty=8, color=green) PaintOrder(id=3, qty=4, color=purple) -After the owner runs this query, they find two orders that matched the -criteria. - -For more information on how to build filters, see our :doc:`Filters Builders -` guide. +To learn more about the ``Filters`` builder, see the +:ref:`filters-builders` guide. -For a runnable ``find()`` example, see our :doc:`Find Multiple -Documents ` page. +To view a runnable ``find()`` example, see the :ref:`kotlin-usage-find` +usage example. .. _retrieve-aggregate: Aggregate Operation ------------------- -Use the aggregate operation to perform the stages in an aggregation -pipeline. An aggregation pipeline is a multi-staged transformation that -produces an aggregated result. +Use aggregation operations to run an aggregation pipeline on your data. +An aggregation pipeline is a multi-staged transformation that produces +an aggregated result. -To perform an aggregate operation, call the ``aggregate()`` method on an -instance of a ``MongoCollection``. This method accepts aggregation +To perform an aggregation operation, call the ``aggregate()`` method on an +instance of ``MongoCollection``. This method accepts aggregation expressions to run in sequence. To perform aggregations, you can define aggregation stages that specify how to match documents, rename -fields, and group values. For more information, see our -:doc:`Aggregation ` guide. +fields, and group values. To learn more, see the +:ref:`kotlin-aggregation` guide. Example ~~~~~~~ -The owner would like to know which paint color is the most purchased -(highest quantity sold) from their :ref:`paint_order collection `. +You want to know which paint color is the most popular by finding the +color that is bought the most. -To address the scenario, the owner creates an aggregation pipeline that: +You can create an aggregation pipeline that performs the following actions: -- Matches all the documents in the ``paint_order`` collection +- Matches all the documents in the ``orders`` collection - Groups orders by colors - Sums up the quantity field by color - Orders the results by highest-to-lowest quantity @@ -124,16 +131,13 @@ To address the scenario, the owner creates an aggregation pipeline that: .. output:: :language: console - PaintOrder(id=2, qty=8, color=green) - PaintOrder(id=3, qty=4, color=purple) - -After the owner runs the aggregation, they find that "green" is the most -purchased color. + PaintOrder(id=2, qty=19, color=green) + PaintOrder(id=3, qty=14, color=purple) -For more information on how to construct an aggregation pipeline, see -the MongoDB server manual page on :manual:`Aggregation `. +To learn more about constructing aggregation pipelines, see +:manual:`Aggregation ` in the Server manual. -For additional information on the methods mentioned on this page, see +To learn more about the methods mentioned on this page, see the following API Documentation: - `MongoCollection.find() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/find.html>`__