Skip to content

Commit 1db6789

Browse files
mcmorisimcmorisi
authored
DOCSP-41134: Retrieve Data (#6)
1 parent 65fff1e commit 1db6789

File tree

3 files changed

+220
-1
lines changed

3 files changed

+220
-1
lines changed

‎source/includes/read/retrieve.kt

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.kotlin.client.*
4+
import com.mongodb.client.model.Filters.*
5+
6+
// start-data-class
7+
data class Restaurant(
8+
val name: String,
9+
val cuisine: String
10+
)
11+
// end-data-class
12+
13+
fun main() {
14+
val uri = "<connection string URI>"
15+
16+
val settings = MongoClientSettings.builder()
17+
.applyConnectionString(ConnectionString(uri))
18+
.retryWrites(true)
19+
.build()
20+
21+
val mongoClient = MongoClient.create(settings)
22+
val database = mongoClient.getDatabase("sample_restaurants")
23+
val collection = database.getCollection<Restaurant>("restaurants")
24+
25+
// start-find
26+
val results = collection.find(eq(Restaurant::cuisine.name, "Spanish"))
27+
// end-find
28+
29+
// start-find-iterate
30+
val results = collection.find(eq(Restaurant::cuisine.name, "Spanish"))
31+
results.forEach { result ->
32+
println(result)
33+
}
34+
// end-find-iterate
35+
36+
// start-find-all
37+
val results = collection.find()
38+
// end-find-all
39+
40+
// start-modified-find
41+
val results = collection
42+
.find(eq(Restaurant::cuisine.name, "Spanish"))
43+
.limit(10)
44+
.maxTime(10000)
45+
// end-modified-find
46+
}

‎source/read.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Read Data from MongoDB
2222
:titlesonly:
2323
:maxdepth: 1
2424

25+
/read/retrieve
2526
/read/count
2627

2728
Overview
@@ -67,7 +68,7 @@ given filter:
6768
:copyable:
6869
:dedent:
6970

70-
.. TODO: To learn more about the ``find()`` method, see the :ref:`kotlin-sync-retrieve-find` guide.
71+
To learn more about the ``find()`` method, see the :ref:`kotlin-sync-retrieve-find` guide.
7172

7273
Count Documents in a Collection
7374
-------------------------------

‎source/read/retrieve.txt

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _kotlin-sync-retrieve:
2+
3+
=============
4+
Retrieve Data
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: code examples, read, search, cursor
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to retrieve data from a
24+
MongoDB collection by using read operations. You can call the ``find()`` method to
25+
retrieve documents that match a set of criteria specified in a query filter.
26+
27+
Sample Data
28+
~~~~~~~~~~~
29+
30+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
31+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
32+
free MongoDB Atlas cluster and load the sample datasets, see the
33+
:atlas:`Get Started with Atlas </getting-started>` guide.
34+
35+
The documents in this collection are modeled by the following {+language+} data class:
36+
37+
.. literalinclude:: /includes/read/retrieve.kt
38+
:start-after: start-data-class
39+
:end-before: end-data-class
40+
:language: kotlin
41+
:copyable:
42+
43+
.. _kotlin-sync-retrieve-find:
44+
45+
Find Documents
46+
--------------
47+
48+
The ``find()`` method retrieves documents from a collection. This
49+
method takes a **query filter** and returns all matching documents. A query filter is a
50+
document that specifies the criteria that the driver uses to match documents from the
51+
collection.
52+
53+
.. TODO: To learn more about query filters, see :ref:`kotlin-sync-specify-query`.
54+
55+
Find Documents Example
56+
~~~~~~~~~~~~~~~~~~~~~~
57+
58+
The following example uses the ``find()`` method to find all documents in which the
59+
value of the ``cuisine`` field is ``"Spanish"``:
60+
61+
.. literalinclude:: /includes/read/retrieve.kt
62+
:start-after: start-find
63+
:end-before: end-find
64+
:language: kotlin
65+
:copyable:
66+
:dedent:
67+
68+
The ``find()`` operation in the preceding example returns a ``FindIterable`` object,
69+
which you can iterate through by using the ``forEach()`` method, as shown in the following
70+
example:
71+
72+
.. io-code-block::
73+
:copyable: true
74+
75+
.. input:: /includes/read/retrieve.kt
76+
:start-after: start-find-iterate
77+
:end-before: end-find-iterate
78+
:language: kotlin
79+
:dedent:
80+
81+
.. output::
82+
:visible: false
83+
84+
Restaurant(name=Tropicoso Club, cuisine=Spanish)
85+
Restaurant(name=Beso, cuisine=Spanish)
86+
Restaurant(name=Sabor Latino Restaurant, cuisine=Spanish)
87+
...
88+
89+
.. note:: Find All Documents
90+
91+
To find all documents in a collection, pass an empty filter to the ``find()`` method:
92+
93+
.. literalinclude:: /includes/read/retrieve.kt
94+
:start-after: start-find-all
95+
:end-before: end-find-all
96+
:language: kotlin
97+
:copyable:
98+
:dedent:
99+
100+
Modify Find Behavior
101+
~~~~~~~~~~~~~~~~~~~~
102+
103+
You can modify the behavior of the ``find()`` method by chaining methods to
104+
the ``find()`` method call. The following table describes commonly used methods used for
105+
modifying queries:
106+
107+
.. list-table::
108+
:widths: 30 70
109+
:header-rows: 1
110+
111+
* - Method
112+
- Description
113+
114+
* - ``batchSize()``
115+
- | Limits the number of documents to return per batch. To learn more about
116+
batch size, see :manual:`cursor.batchSize() </reference/method/cursor.batchSize/>`
117+
in the MongoDB Server manual.
118+
119+
* - ``collation()``
120+
- | Sets the collation options for the query.
121+
122+
* - ``comment()``
123+
- | Specifies a string to attach to the query. This can help you trace and interpret the
124+
operation in the server logs and in profile data. To learn more about query comments,
125+
see :manual:`$comment </reference/operator/query/comment/>` in the MongoDB Server
126+
manual.
127+
128+
* - ``hint()``
129+
- | Specifies the index to use for the query.
130+
131+
* - ``limit()``
132+
- | Limits the number of documents to be returned from the query.
133+
134+
* - ``maxTime()``
135+
- | Sets the maximum execution time on the server for this operation.
136+
137+
* - ``skip()``
138+
- | Sets the number of documents to skip.
139+
140+
* - ``sort()``
141+
- | Defines the sort criteria to apply to the query.
142+
143+
The following example chains the ``limit()`` and ``maxTime()`` methods to limit the
144+
number of documents returned by the query to ``10`` and set a maximum execution time of
145+
``10000`` milliseconds on the operation:
146+
147+
.. literalinclude:: /includes/read/retrieve.kt
148+
:start-after: start-modified-find
149+
:end-before: end-modified-find
150+
:language: kotlin
151+
:copyable:
152+
:dedent:
153+
154+
For a full list of methods that modify the behavior of ``find()``, see the `API documentation <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/index.html>`__
155+
for the ``FindIterable`` class.
156+
157+
Additional Information
158+
----------------------
159+
160+
.. TODO: To learn more about query filters, see :ref:`kotlin-sync-specify-query`.
161+
162+
To view runnable code examples that retrieve documents by using the {+driver-short+}, see
163+
:ref:`kotlin-sync-read`.
164+
165+
API Documentation
166+
~~~~~~~~~~~~~~~~~
167+
168+
To learn more about any of the methods or types discussed in this guide, see the following
169+
API documentation:
170+
171+
- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__
172+
- `FindIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/index.html>`__

0 commit comments

Comments
 (0)