From 6a16610632cc50e98dfb7a9c2e792cb8a3cd4724 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 15 Jul 2024 11:38:49 -0400 Subject: [PATCH 1/5] DOCSP-41136: Specify Documents --- snooty.toml | 3 +- .../read/specify-documents-to-return.kt | 69 ++++++ source/read.txt | 1 + source/read/specify-documents-to-return.txt | 198 ++++++++++++++++++ 4 files changed, 270 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/specify-documents-to-return.kt create mode 100644 source/read/specify-documents-to-return.txt diff --git a/snooty.toml b/snooty.toml index a9043f1f..ac9b7e35 100644 --- a/snooty.toml +++ b/snooty.toml @@ -21,4 +21,5 @@ version = "v{+version-number+}" patch-version-number = "{+version-number+}.0" mdb-server = "MongoDB Server" stable-api = "Stable API" -api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" \ No newline at end of file +api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" +java-api = "https://mongodb.github.io/mongo-java-driver/{+version+}" \ No newline at end of file diff --git a/source/includes/read/specify-documents-to-return.kt b/source/includes/read/specify-documents-to-return.kt new file mode 100644 index 00000000..e5461e1e --- /dev/null +++ b/source/includes/read/specify-documents-to-return.kt @@ -0,0 +1,69 @@ +package org.example +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Filters.eq +import com.mongodb.client.model.Sorts +import com.mongodb.kotlin.client.MongoClient + +// start-data-class +data class Restaurant( + val name: String, + val borough: String, + val cuisine: String +) +// end-data-class + +fun main() { + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .retryWrites(true) + .build() + + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_restaurants") + val collection = database.getCollection("restaurants") + + // start-limit + val results = collection + .find(eq(Restaurant::cuisine.name, "Italian")) + .limit(5) + + results.forEach { result -> + println(result) + } + // end-limit + + // start-sort + val results = collection + .find(eq(Restaurant::cuisine.name, "Italian")) + .sort(Sorts.ascending(Restaurant::name.name)) + + results.forEach { result -> + println(result) + } + // end-sort + + // start-skip + val results = collection + .find(eq(Restaurant::cuisine.name, "Italian")) + .skip(10) + + results.forEach { result -> + println(result) + } + // end-skip + + // start-limit-sort-skip + val results = collection + .find(eq(Restaurant::cuisine.name, "Italian")) + .sort(Sorts.ascending(Restaurant::name.name)) + .skip(10) + .limit(5) + + results.forEach { result -> + println(result) + } + // end-limit-sort-skip +} diff --git a/source/read.txt b/source/read.txt index 0cdf1f55..2f752f11 100644 --- a/source/read.txt +++ b/source/read.txt @@ -23,6 +23,7 @@ Read Data from MongoDB :maxdepth: 1 /read/count + /read/specify-documents-to-return Overview -------- diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt new file mode 100644 index 00000000..096ad8fa --- /dev/null +++ b/source/read/specify-documents-to-return.txt @@ -0,0 +1,198 @@ +.. _kotlin-sync-specify-documents-to-return: + +=========================== +Specify Documents to Return +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, paginate, pagination, order, code example + +Overview +-------- + +In this guide, you can learn how to specify which documents to return from a read +operation by using the following methods: + +- ``limit()``: Specifies the maximum number of documents to return from a query. +- ``sort()``: Specifies the sort order for the returned documents. +- ``skip()``: Specifies the number of documents to skip before returning query results. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +The documents in this collection are modeled by the following {+language+} data class: + +.. literalinclude:: /includes/read/specify-documents-to-return.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + +.. _kotlin-sync-limit: + +Limit +----- + +To specify the maximum number of documents returned from a read operation, +call the ``limit()`` method. + +The following example finds all restaurants that have a ``cuisine`` field value +of ``"Italian"`` and limits the results to 5 documents: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-documents-to-return.kt + :start-after: start-limit + :end-before: end-limit + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(name=Philadelphia Grille Express, borough=Brooklyn, cuisine=Italian) + Restaurant(name=Isle Of Capri Resturant, borough=Manhattan, cuisine=Italian) + Restaurant(name=Marchis Restaurant, borough=Manhattan, cuisine=Italian) + Restaurant(name=Crystal Room, borough=Staten Island, cuisine=Italian) + Restaurant(name=Forlinis Restaurant, borough=Manhattan, cuisine=Italian) + +.. tip:: + + The preceding example returns the first five documents returned by the query in + no particular order. The following section describes how to return the documents + in a specified sort order. + +.. _kotlin-sync-sort: + +Sort +---- + +To return documents in a specified order, call the ``sort()`` method. The ``sort()`` +method takes a sort direction as a parameter. To specify the sort direction, +use the ``Sorts.ascending()`` or ``Sorts.descending()`` methods. ``Sorts.ascending()`` +sorts values from lowest to highest, and ``Sorts.descending()`` sorts values from highest +to lowest. If you don't specify either direction, ``sort()`` defaults to sorting in +ascending order. + +The following example returns all documents with a ``cuisine`` field value of +``"Italian"``, sorted in ascending order: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-documents-to-return.kt + :start-after: start-sort + :end-before: end-sort + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(name=(Lewis Drug Store) Locanda Vini E Olii, borough=Brooklyn, cuisine=Italian) + Restaurant(name=101 Restaurant And Bar, borough=Brooklyn, cuisine=Italian) + Restaurant(name=44 Sw Ristorante & Bar, borough=Manhattan, cuisine=Italian) + Restaurant(name=900 Park, borough=Bronx, cuisine=Italian) + Restaurant(name=A Voce, borough=Manhattan, cuisine=Italian) + ... + +.. _kotlin-sync-skip: + +Skip +---- + +To skip a specified number of documents before returning your query results, +call the ``skip()`` method and pass in the number of documents to skip. The +``skip()`` method ignores the specified number of documents in your query +results and returns the rest. + +The following example returns all documents that have a ``cuisine`` field value +of ``"Italian"`` and skips the first 10 documents: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-documents-to-return.kt + :start-after: start-skip + :end-before: end-skip + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(name=San Pietro, borough=Manhattan, cuisine=Italian) + Restaurant(name=Manetta's Ristorante, borough=Queens, cuisine=Italian) + Restaurant(name=Salvi Restaurant, borough=Brooklyn, cuisine=Italian) + Restaurant(name=Tommaso Restaurant, borough=Brooklyn, cuisine=Italian) + Restaurant(name=Da Rosina Restaurant, borough=Manhattan, cuisine=Italian) + ... + +Combine Limit, Sort, and Skip +----------------------------- + +You can combine the ``limit()``, ``sort()``, and ``skip()`` methods in a single +operation. This allows you to set a maximum number of sorted documents to +return, skipping a specified number of documents before returning. + +The following example returns documents with the ``cuisine`` field value of +``"Italian"``. The results are sorted in alphabetical order, skipping the first +10 documents: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-documents-to-return.kt + :start-after: start-limit-sort-skip + :end-before: end-limit-sort-skip + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(name=Acqua, borough=Manhattan, cuisine=Italian) + Restaurant(name=Acqua Restaurant, borough=Manhattan, cuisine=Italian) + Restaurant(name=Acqua Santa, borough=Brooklyn, cuisine=Italian) + Restaurant(name=Acquista Trattoria, borough=Queens, cuisine=Italian) + Restaurant(name=Acquolina Catering, borough=Manhattan, cuisine=Italian) + +.. note:: + + The order in which you call these methods doesn't change the documents + that are returned. The driver automatically reorders the calls to perform the + sort and skip operations first, and the limit operation afterward. + +Additional Information +---------------------- + +.. TODO: For more information about specifying a query, see :ref:`kotlin-sync-specify-query`. + +For more information about retrieving documents, see :ref:`kotlin-sync-retrieve`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API Documentation: + +- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `limit() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/limit.html>`__ +- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__ +- `skip() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/skip.html>`__ From 005ab564bb8cd9094c45c38ff84c852e150442a3 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 15 Jul 2024 12:01:42 -0400 Subject: [PATCH 2/5] Fix --- snooty.toml | 3 +-- source/includes/read/specify-documents-to-return.kt | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/snooty.toml b/snooty.toml index ac9b7e35..a9043f1f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -21,5 +21,4 @@ version = "v{+version-number+}" patch-version-number = "{+version-number+}.0" mdb-server = "MongoDB Server" stable-api = "Stable API" -api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" -java-api = "https://mongodb.github.io/mongo-java-driver/{+version+}" \ No newline at end of file +api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" \ No newline at end of file diff --git a/source/includes/read/specify-documents-to-return.kt b/source/includes/read/specify-documents-to-return.kt index e5461e1e..a55a3942 100644 --- a/source/includes/read/specify-documents-to-return.kt +++ b/source/includes/read/specify-documents-to-return.kt @@ -14,7 +14,7 @@ data class Restaurant( // end-data-class fun main() { - val uri = "" + val uri = "" val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) From f5c668f025592ff00225de7e2e2456607989c461 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 15 Jul 2024 12:08:42 -0400 Subject: [PATCH 3/5] Fix --- source/read/specify-documents-to-return.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index 096ad8fa..64353e07 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -85,13 +85,13 @@ Sort To return documents in a specified order, call the ``sort()`` method. The ``sort()`` method takes a sort direction as a parameter. To specify the sort direction, -use the ``Sorts.ascending()`` or ``Sorts.descending()`` methods. ``Sorts.ascending()`` -sorts values from lowest to highest, and ``Sorts.descending()`` sorts values from highest +use the ``Sorts.ascending()`` or ``Sorts.descending()`` methods. ``ascending()`` +sorts values from lowest to highest, and ``descending()`` sorts values from highest to lowest. If you don't specify either direction, ``sort()`` defaults to sorting in ascending order. The following example returns all documents with a ``cuisine`` field value of -``"Italian"``, sorted in ascending order: +``"Italian"``, sorted by the value of the ``name`` field in ascending order: .. io-code-block:: :copyable: true From 052cbf50f1644b35e14481fddadc3d49e1fe44ba Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 15 Jul 2024 12:13:31 -0400 Subject: [PATCH 4/5] Fix --- source/read/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index 64353e07..d6d435f4 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -153,7 +153,7 @@ return, skipping a specified number of documents before returning. The following example returns documents with the ``cuisine`` field value of ``"Italian"``. The results are sorted in alphabetical order, skipping the first -10 documents: +10 documents and limiting the results to 5 documents: .. io-code-block:: :copyable: true From b32224e62aa1d18002b797379e92ca966462ff50 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 15 Jul 2024 13:12:35 -0400 Subject: [PATCH 5/5] MW feedback --- source/read/specify-documents-to-return.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index d6d435f4..1fd24154 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -23,9 +23,9 @@ Overview In this guide, you can learn how to specify which documents to return from a read operation by using the following methods: -- ``limit()``: Specifies the maximum number of documents to return from a query. -- ``sort()``: Specifies the sort order for the returned documents. -- ``skip()``: Specifies the number of documents to skip before returning query results. +- ``limit()``: Specifies the maximum number of documents to return from a query +- ``sort()``: Specifies the sort order for the returned documents +- ``skip()``: Specifies the number of documents to skip before returning query results Sample Data ~~~~~~~~~~~ @@ -75,8 +75,8 @@ of ``"Italian"`` and limits the results to 5 documents: .. tip:: The preceding example returns the first five documents returned by the query in - no particular order. The following section describes how to return the documents - in a specified sort order. + :manual:`natural order `. The following + section describes how to return the documents in a specified sort order. .. _kotlin-sync-sort: @@ -85,10 +85,10 @@ Sort To return documents in a specified order, call the ``sort()`` method. The ``sort()`` method takes a sort direction as a parameter. To specify the sort direction, -use the ``Sorts.ascending()`` or ``Sorts.descending()`` methods. ``ascending()`` -sorts values from lowest to highest, and ``descending()`` sorts values from highest -to lowest. If you don't specify either direction, ``sort()`` defaults to sorting in -ascending order. +use the ``Sorts.ascending()`` or ``Sorts.descending()`` method. The ``Sorts.ascending()`` +method sorts values from lowest to highest, and the ``Sorts.descending()`` method sorts +values from highest to lowest. If you don't specify a sort direction, ``sort()`` returns +the documents in ascending order. The following example returns all documents with a ``cuisine`` field value of ``"Italian"``, sorted by the value of the ``name`` field in ascending order: @@ -190,7 +190,7 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: +guide, see the following API documentation: - `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ - `limit() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/limit.html>`__