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..a55a3942 --- /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 01d69855..35d40cd4 100644 --- a/source/read.txt +++ b/source/read.txt @@ -23,8 +23,9 @@ Read Data from MongoDB :maxdepth: 1 /read/retrieve - /read/count /read/project + /read/specify-documents-to-return + /read/count 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..1fd24154 --- /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 + :manual:`natural 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()`` 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: + +.. 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 and limiting the results to 5 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>`__