Skip to content

Commit 83432bc

Browse files
mcmorisimcmorisi
authored
DOCSP-41136: Specify Documents to Return (#10)
1 parent 53751bb commit 83432bc

File tree

3 files changed

+269
-1
lines changed

3 files changed

+269
-1
lines changed

‎source/includes/read/specify-documents-to-return.kt

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
package org.example
2+
import com.mongodb.ConnectionString
3+
import com.mongodb.MongoClientSettings
4+
import com.mongodb.client.model.Filters.eq
5+
import com.mongodb.client.model.Sorts
6+
import com.mongodb.kotlin.client.MongoClient
7+
8+
// start-data-class
9+
data class Restaurant(
10+
val name: String,
11+
val borough: String,
12+
val cuisine: String
13+
)
14+
// end-data-class
15+
16+
fun main() {
17+
val uri = "<connection string URI>"
18+
19+
val settings = MongoClientSettings.builder()
20+
.applyConnectionString(ConnectionString(uri))
21+
.retryWrites(true)
22+
.build()
23+
24+
val mongoClient = MongoClient.create(settings)
25+
val database = mongoClient.getDatabase("sample_restaurants")
26+
val collection = database.getCollection<Restaurant>("restaurants")
27+
28+
// start-limit
29+
val results = collection
30+
.find(eq(Restaurant::cuisine.name, "Italian"))
31+
.limit(5)
32+
33+
results.forEach { result ->
34+
println(result)
35+
}
36+
// end-limit
37+
38+
// start-sort
39+
val results = collection
40+
.find(eq(Restaurant::cuisine.name, "Italian"))
41+
.sort(Sorts.ascending(Restaurant::name.name))
42+
43+
results.forEach { result ->
44+
println(result)
45+
}
46+
// end-sort
47+
48+
// start-skip
49+
val results = collection
50+
.find(eq(Restaurant::cuisine.name, "Italian"))
51+
.skip(10)
52+
53+
results.forEach { result ->
54+
println(result)
55+
}
56+
// end-skip
57+
58+
// start-limit-sort-skip
59+
val results = collection
60+
.find(eq(Restaurant::cuisine.name, "Italian"))
61+
.sort(Sorts.ascending(Restaurant::name.name))
62+
.skip(10)
63+
.limit(5)
64+
65+
results.forEach { result ->
66+
println(result)
67+
}
68+
// end-limit-sort-skip
69+
}

‎source/read.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,9 @@ Read Data from MongoDB
2323
:maxdepth: 1
2424

2525
/read/retrieve
26-
/read/count
2726
/read/project
27+
/read/specify-documents-to-return
28+
/read/count
2829

2930
Overview
3031
--------

‎source/read/specify-documents-to-return.txt

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
.. _kotlin-sync-specify-documents-to-return:
2+
3+
===========================
4+
Specify Documents to Return
5+
===========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, paginate, pagination, order, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify which documents to return from a read
24+
operation by using the following methods:
25+
26+
- ``limit()``: Specifies the maximum number of documents to return from a query
27+
- ``sort()``: Specifies the sort order for the returned documents
28+
- ``skip()``: Specifies the number of documents to skip before returning query results
29+
30+
Sample Data
31+
~~~~~~~~~~~
32+
33+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
34+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
35+
free MongoDB Atlas cluster and load the sample datasets, see the
36+
:atlas:`Get Started with Atlas </getting-started>` guide.
37+
38+
The documents in this collection are modeled by the following {+language+} data class:
39+
40+
.. literalinclude:: /includes/read/specify-documents-to-return.kt
41+
:start-after: start-data-class
42+
:end-before: end-data-class
43+
:language: kotlin
44+
:copyable:
45+
46+
.. _kotlin-sync-limit:
47+
48+
Limit
49+
-----
50+
51+
To specify the maximum number of documents returned from a read operation,
52+
call the ``limit()`` method.
53+
54+
The following example finds all restaurants that have a ``cuisine`` field value
55+
of ``"Italian"`` and limits the results to 5 documents:
56+
57+
.. io-code-block::
58+
:copyable: true
59+
60+
.. input:: /includes/read/specify-documents-to-return.kt
61+
:start-after: start-limit
62+
:end-before: end-limit
63+
:language: kotlin
64+
:dedent:
65+
66+
.. output::
67+
:visible: false
68+
69+
Restaurant(name=Philadelphia Grille Express, borough=Brooklyn, cuisine=Italian)
70+
Restaurant(name=Isle Of Capri Resturant, borough=Manhattan, cuisine=Italian)
71+
Restaurant(name=Marchis Restaurant, borough=Manhattan, cuisine=Italian)
72+
Restaurant(name=Crystal Room, borough=Staten Island, cuisine=Italian)
73+
Restaurant(name=Forlinis Restaurant, borough=Manhattan, cuisine=Italian)
74+
75+
.. tip::
76+
77+
The preceding example returns the first five documents returned by the query in
78+
:manual:`natural order </reference/glossary/#std-term-natural-order>`. The following
79+
section describes how to return the documents in a specified sort order.
80+
81+
.. _kotlin-sync-sort:
82+
83+
Sort
84+
----
85+
86+
To return documents in a specified order, call the ``sort()`` method. The ``sort()``
87+
method takes a sort direction as a parameter. To specify the sort direction,
88+
use the ``Sorts.ascending()`` or ``Sorts.descending()`` method. The ``Sorts.ascending()``
89+
method sorts values from lowest to highest, and the ``Sorts.descending()`` method sorts
90+
values from highest to lowest. If you don't specify a sort direction, ``sort()`` returns
91+
the documents in ascending order.
92+
93+
The following example returns all documents with a ``cuisine`` field value of
94+
``"Italian"``, sorted by the value of the ``name`` field in ascending order:
95+
96+
.. io-code-block::
97+
:copyable: true
98+
99+
.. input:: /includes/read/specify-documents-to-return.kt
100+
:start-after: start-sort
101+
:end-before: end-sort
102+
:language: kotlin
103+
:dedent:
104+
105+
.. output::
106+
:visible: false
107+
108+
Restaurant(name=(Lewis Drug Store) Locanda Vini E Olii, borough=Brooklyn, cuisine=Italian)
109+
Restaurant(name=101 Restaurant And Bar, borough=Brooklyn, cuisine=Italian)
110+
Restaurant(name=44 Sw Ristorante & Bar, borough=Manhattan, cuisine=Italian)
111+
Restaurant(name=900 Park, borough=Bronx, cuisine=Italian)
112+
Restaurant(name=A Voce, borough=Manhattan, cuisine=Italian)
113+
...
114+
115+
.. _kotlin-sync-skip:
116+
117+
Skip
118+
----
119+
120+
To skip a specified number of documents before returning your query results,
121+
call the ``skip()`` method and pass in the number of documents to skip. The
122+
``skip()`` method ignores the specified number of documents in your query
123+
results and returns the rest.
124+
125+
The following example returns all documents that have a ``cuisine`` field value
126+
of ``"Italian"`` and skips the first 10 documents:
127+
128+
.. io-code-block::
129+
:copyable: true
130+
131+
.. input:: /includes/read/specify-documents-to-return.kt
132+
:start-after: start-skip
133+
:end-before: end-skip
134+
:language: kotlin
135+
:dedent:
136+
137+
.. output::
138+
:visible: false
139+
140+
Restaurant(name=San Pietro, borough=Manhattan, cuisine=Italian)
141+
Restaurant(name=Manetta's Ristorante, borough=Queens, cuisine=Italian)
142+
Restaurant(name=Salvi Restaurant, borough=Brooklyn, cuisine=Italian)
143+
Restaurant(name=Tommaso Restaurant, borough=Brooklyn, cuisine=Italian)
144+
Restaurant(name=Da Rosina Restaurant, borough=Manhattan, cuisine=Italian)
145+
...
146+
147+
Combine Limit, Sort, and Skip
148+
-----------------------------
149+
150+
You can combine the ``limit()``, ``sort()``, and ``skip()`` methods in a single
151+
operation. This allows you to set a maximum number of sorted documents to
152+
return, skipping a specified number of documents before returning.
153+
154+
The following example returns documents with the ``cuisine`` field value of
155+
``"Italian"``. The results are sorted in alphabetical order, skipping the first
156+
10 documents and limiting the results to 5 documents:
157+
158+
.. io-code-block::
159+
:copyable: true
160+
161+
.. input:: /includes/read/specify-documents-to-return.kt
162+
:start-after: start-limit-sort-skip
163+
:end-before: end-limit-sort-skip
164+
:language: kotlin
165+
:dedent:
166+
167+
.. output::
168+
:visible: false
169+
170+
Restaurant(name=Acqua, borough=Manhattan, cuisine=Italian)
171+
Restaurant(name=Acqua Restaurant, borough=Manhattan, cuisine=Italian)
172+
Restaurant(name=Acqua Santa, borough=Brooklyn, cuisine=Italian)
173+
Restaurant(name=Acquista Trattoria, borough=Queens, cuisine=Italian)
174+
Restaurant(name=Acquolina Catering, borough=Manhattan, cuisine=Italian)
175+
176+
.. note::
177+
178+
The order in which you call these methods doesn't change the documents
179+
that are returned. The driver automatically reorders the calls to perform the
180+
sort and skip operations first, and the limit operation afterward.
181+
182+
Additional Information
183+
----------------------
184+
185+
.. TODO: For more information about specifying a query, see :ref:`kotlin-sync-specify-query`.
186+
187+
For more information about retrieving documents, see :ref:`kotlin-sync-retrieve`.
188+
189+
API Documentation
190+
~~~~~~~~~~~~~~~~~
191+
192+
To learn more about any of the methods or types discussed in this
193+
guide, see the following API documentation:
194+
195+
- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__
196+
- `limit() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/limit.html>`__
197+
- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__
198+
- `skip() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/skip.html>`__

0 commit comments

Comments
 (0)