Skip to content

Commit ea7d5b9

Browse files
committed
Merge remote-tracking branch 'upstream/master' into DOCSP-44853-update-usage-exs
2 parents 979cdbf + 179c64e commit ea7d5b9

File tree

20 files changed

+339
-64
lines changed

20 files changed

+339
-64
lines changed

source/fundamentals/aggregation.txt

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -183,11 +183,11 @@ month.
183183

184184
The aggregation pipeline contains the following stages:
185185

186-
- A ``$project`` stage to extract the month from the ``last_active``
187-
field as a number into the ``month_last_active`` field.
188-
- A ``$group`` stage to group documents by the ``month_last_active``
189-
field and count the number of documents for each month.
190-
- A ``$sort`` stage to set an ascending sort on the month.
186+
- ``$project`` stage to extract the month from the ``last_active``
187+
field as a number into the ``month_last_active`` field
188+
- ``$group`` stage to group documents by the ``month_last_active``
189+
field and count the number of documents for each month
190+
- ``$sort`` stage to set an ascending sort on the month
191191

192192
.. io-code-block::
193193

@@ -216,12 +216,12 @@ often they appear in users' interests.
216216

217217
The aggregation pipeline contains the following stages:
218218

219-
- An ``$unwind`` stage to separate each array entry in the
220-
``genre_interests`` field into a new document.
221-
- A ``$group`` stage to group documents by the ``genre_interests``
222-
field and count the number of documents for each genre.
223-
- A ``$sort`` stage to set a descending sort on the genre popularity.
224-
- A ``$limit`` stage to show only the first three genres.
219+
- ``$unwind`` stage to separate each array entry in the
220+
``genre_interests`` field into a new document
221+
- ``$group`` stage to group documents by the ``genre_interests``
222+
field and count the number of documents for each genre
223+
- ``$sort`` stage to set a descending sort on the genre popularity
224+
- ``$limit`` stage to show only the first three genres
225225

226226
.. io-code-block::
227227

source/fundamentals/connections/tls.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ Select from the following :guilabel:`Connection String` and
8181
:emphasize-lines: 4-5
8282

8383
let uri = "<connection string>"
84-
let mut client_options = ClientOptions::parse_async(uri).await?;
84+
let mut client_options = ClientOptions::parse(uri).await?;
8585

8686
let tls_opts = TlsOptions::builder().build();
8787
client_options.tls = Some(Tls::Enabled(tls_opts));

source/fundamentals/crud/read-operations.txt

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ Read Operations
1414
/fundamentals/crud/read-operations/text-search
1515
/fundamentals/crud/read-operations/sort
1616
/fundamentals/crud/read-operations/skip
17+
/fundamentals/crud/read-operations/limit
1718

1819
..
1920
/fundamentals/crud/read-operations/count
2021
/fundamentals/crud/read-operations/distinct
21-
/fundamentals/crud/read-operations/limit
22+
2223
/fundamentals/crud/read-operations/project
2324

2425

@@ -29,11 +30,9 @@ Read Operations
2930
- :ref:`rust-search-text-guide`
3031
- :ref:`rust-sort-guide`
3132
- :ref:`rust-skip-guide`
33+
- :ref:`rust-limit-guide`
3234

3335
.. - :ref:`rust-query-guide`
3436
.. - :ref:`rust-count-guide`
3537
.. - :ref:`rust-distinct-guide`
36-
37-
38-
.. - :ref:`rust-limit-guide`
3938
.. - :ref:`rust-project-guide`
Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
.. _rust-limit-guide:
2+
3+
====================================
4+
Limit the Number of Returned Results
5+
====================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: read operation, code example, pipeline, customize output
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-long+} to perform **limit**
24+
operations. These operations specify the number of documents returned from a
25+
read operation.
26+
27+
Use the ``limit()`` method to cap the number of documents that a read operation
28+
can return. The operation returns fewer documents if there are not enough
29+
documents present to reach the specified limit.
30+
31+
If you use the ``limit()`` method with the ``skip()`` method, the skip applies
32+
first, and the limit only applies to the remaining documents. To learn more
33+
about skip operations, see the :ref:`Skip Returned Results <rust-skip-guide>`
34+
guide.
35+
36+
Sample Data for Examples
37+
------------------------
38+
39+
The examples in this guide use the following ``Book`` struct as a model for
40+
documents in the ``books`` collection:
41+
42+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/limit.rs
43+
:start-after: start-book-struct
44+
:end-before: end-book-struct
45+
:language: rust
46+
:dedent:
47+
48+
The following code shows how to insert sample data into the ``books``
49+
collection:
50+
51+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/limit.rs
52+
:start-after: start-sample-data
53+
:end-before: end-sample-data
54+
:language: rust
55+
:dedent:
56+
57+
Limit Documents
58+
---------------
59+
60+
You can specify the maximum number of documents to return in a query or in an
61+
aggregation pipeline.
62+
63+
This section describes how to limit results in the following ways:
64+
65+
- :ref:`limit() method <rust-limit-method>`: Chain the ``limit()`` method to the
66+
``find()`` method
67+
- :ref:`FindOptions struct <rust-findoptions-limit>`: Use the ``limit`` option
68+
- :ref:`Aggregation pipleline <rust-aggregation-limit>`: Create a pipeline that uses the ``$limit`` stage
69+
70+
.. _rust-limit-method:
71+
72+
limit() Method Example
73+
~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
To limit the number of documents returned, you can chain the ``limit()`` method
76+
to the ``find()`` method.
77+
78+
This example runs a ``find()`` operation that performs the following actions:
79+
80+
- Sorts the results in ascending order of their ``length`` field values
81+
- Limits the results to the first three documents
82+
83+
.. io-code-block::
84+
:copyable: true
85+
86+
.. input:: /includes/fundamentals/code-snippets/crud/limit.rs
87+
:start-after: start-limit-example
88+
:end-before: end-limit-example
89+
:language: rust
90+
:dedent:
91+
92+
.. output::
93+
:language: console
94+
:visible: false
95+
96+
Book { name: "The Brothers Karamazov", author: "Dostoyevsky", length: 824 }
97+
Book { name: "Atlas Shrugged", author: "Rand", length: 1088 }
98+
Book { name: "A Dance with Dragons", author: "Martin", length: 1104 }
99+
100+
.. _rust-findoptions-limit:
101+
102+
Options Example
103+
~~~~~~~~~~~~~~~
104+
105+
Alternatively, if you are setting and reusing options for your query, you can
106+
use ``FindOptions``. Set the ``limit`` field of the ``FindOptions`` struct by
107+
using the ``limit()`` option builder method. Then, chain the ``with_options()``
108+
method to the ``find()`` method and pass your ``FindOptions`` struct as a
109+
parameter to the ``with_options()`` method.
110+
111+
This example runs a ``find()`` operation that performs the following actions:
112+
113+
- Filters the results to only include documents where the ``length`` field is
114+
greater than ``1000``
115+
- Sorts the results in ascending order of their ``length`` field values
116+
- Limits the results to the first two documents
117+
118+
.. io-code-block::
119+
:copyable: true
120+
121+
.. input:: /includes/fundamentals/code-snippets/crud/limit.rs
122+
:start-after: start-limit-options-example
123+
:end-before: end-limit-options-example
124+
:language: rust
125+
:dedent:
126+
127+
.. output::
128+
:language: console
129+
:visible: false
130+
131+
Book { name: "Atlas Shrugged", author: "Rand", length: 1088 }
132+
Book { name: "A Dance with Dragons", author: "Martin", length: 1104 }
133+
134+
.. _rust-aggregation-limit:
135+
136+
Aggregation Example
137+
~~~~~~~~~~~~~~~~~~~
138+
139+
You can use the ``$limit`` stage in an aggregation pipeline to limit returned
140+
results. To learn more about aggregation operations, see the
141+
:ref:`rust-aggregation` guide.
142+
143+
This example runs an aggregation pipeline that performs the following actions:
144+
145+
- Sorts the results in descending order of their ``length`` field values
146+
- Limits the returned results to the first two documents
147+
148+
.. io-code-block::
149+
:copyable: true
150+
151+
.. input:: /includes/fundamentals/code-snippets/crud/limit.rs
152+
:start-after: start-aggregation-limit-example
153+
:end-before: end-aggregation-limit-example
154+
:language: rust
155+
:dedent:
156+
157+
.. output::
158+
:language: console
159+
:visible: false
160+
161+
Document({"_id": Int32(3), "name": String("Les Misérables"), "author": String("Hugo"), "length": Int32(1462)})
162+
Document({"_id": Int32(4), "name": String("A Dance with Dragons"), "author": String("Martin"), "length": Int32(1104)})
163+
164+
Additional Information
165+
----------------------
166+
167+
To learn more about the operations mentioned in this guide, see the following guides:
168+
169+
- :ref:`rust-query-guide`
170+
- :ref:`rust-retrieve-guide`
171+
- :ref:`rust-aggregation`
172+
- :ref:`rust-sort-guide`
173+
174+
API Documentation
175+
~~~~~~~~~~~~~~~~~
176+
177+
To learn more about any of the methods or types discussed in this guide, see the
178+
following API documentation:
179+
180+
- `find() <{+api+}/struct.Collection.html#method.find>`__
181+
- `FindOptions <{+api+}/options/struct.FindOptions.html>`__
182+
- `Cursor <{+api+}/struct.Cursor.html>`__
183+
- `aggregate() <{+api+}/struct.Collection.html#method.aggregate>`__

source/fundamentals/crud/read-operations/query.txt

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,9 @@ The examples in the following sections query a collection of documents described
111111
:start-after: begin-sample-docs
112112
:end-before: end-sample-docs
113113

114+
To learn how to insert this data into a collection, see the
115+
:ref:`rust-insert-guide` guide.
116+
114117
.. _rust-literal-values:
115118

116119
Literal Values
@@ -240,7 +243,7 @@ divisible by ``3``:
240243
.. code-block:: rust
241244

242245
my_coll.find(doc! {
243-
$and: [
246+
"$and": [
244247
doc! { "price": { "$eq": 5 }},
245248
doc! { "quantity": { "$gt": 4 }}
246249
]

source/fundamentals/crud/read-operations/retrieve.txt

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ information about its categorization and unit price:
5959
:start-after: start-sample
6060
:end-before: end-sample
6161

62+
To learn how to insert this data into a collection, see the
63+
:ref:`rust-insert-guide` guide.
64+
6265
.. _rust-retrieve-find:
6366

6467
Find Operations
@@ -166,7 +169,6 @@ fields that you can set by calling their corresponding builder methods:
166169
| Default: ``None``
167170

168171
.. TODO link to projection fundamentals page under projection setting
169-
.. TODO link to skip fundamentals page under skip setting
170172

171173
.. note:: Setting Options
172174

@@ -350,9 +352,10 @@ Example
350352
This example shows how to call the ``aggregate()`` method with a
351353
pipeline that contains the following stages:
352354

353-
- A ``$group`` stage to group documents by the ``category`` field and
354-
calculate the average of the ``unit_price`` field by ``category``
355-
- A ``$sort`` stage to by ``avg_price`` in ascending order
355+
- ``$group`` stage to calculate the average of the ``unit_price``
356+
field for each value of the ``category`` field
357+
- ``$sort`` stage to order results by ``avg_price`` in ascending
358+
order
356359

357360
.. io-code-block::
358361
:copyable: true
@@ -390,8 +393,7 @@ following documentation:
390393
- :ref:`rust-aggregation` guide
391394
- :ref:`rust-sort-guide` guide
392395
- :ref:`rust-skip-guide` guide
393-
394-
.. - :ref:`rust-limit-guide`
396+
- :ref:`rust-limit-guide` guide
395397
.. - :ref:`rust-project-guide`
396398
.. - :ref:`rust-collations-guide`
397399

source/fundamentals/performance.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ option. The following code demonstrates how to specify a value for
122122

123123
.. code-block:: rust
124124

125-
let mut client_options = ClientOptions::parse_async("<connection string>").await?;
125+
let mut client_options = ClientOptions::parse("<connection string>").await?;
126126
client_options.max_pool_size = Some(20);
127127

128128
let client = Client::with_options(client_options)?;
@@ -156,7 +156,7 @@ instantiating a ``Client``:
156156

157157
.. code-block:: rust
158158

159-
let mut client_options = ClientOptions::parse_async("<connection string>").await?;
159+
let mut client_options = ClientOptions::parse("<connection string>").await?;
160160
client_options.max_connecting = Some(3);
161161
client_options.min_pool_size = Some(1);
162162

@@ -185,7 +185,7 @@ The following code sets the value of the ``max_idle_time`` option to
185185

186186
.. code-block:: rust
187187

188-
let mut client_options = ClientOptions::parse_async("<connection string>").await?;
188+
let mut client_options = ClientOptions::parse("<connection string>").await?;
189189
client_options.max_idle_time = Some(Duration::new(90, 0));
190190

191191
let client = Client::with_options(client_options)?;

source/fundamentals/stable-api.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ and connects to a server.
7070
:dedent:
7171
:start-after: start-stable-api
7272
:end-before: end-stable-api
73+
:emphasize-lines: 3-4
7374

7475
.. _rust-stable-api-options:
7576

source/includes/fundamentals/code-snippets/aggregation.rs

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
use bson::{ doc, DateTime };
1+
use bson::{ doc, DateTime, Document };
22
use mongodb::{ Client, Collection };
33
use serde::{ Deserialize, Serialize };
4+
use futures::stream::TryStreamExt;
45

56
#[tokio::main]
67
async fn main() -> mongodb::error::Result<()> {
@@ -42,8 +43,7 @@ async fn main() -> mongodb::error::Result<()> {
4243

4344
let mut results = my_coll.aggregate(age_pipeline).await?;
4445
while let Some(result) = results.try_next().await? {
45-
let doc = mongodb::bson::from_document(result)?;
46-
println!("* {:?}", doc);
46+
println!("* {:?}", result);
4747
}
4848
// end-age-agg
4949

@@ -57,8 +57,7 @@ async fn main() -> mongodb::error::Result<()> {
5757

5858
let mut results = my_coll.aggregate(last_active_pipeline).await?;
5959
while let Some(result) = results.try_next().await? {
60-
let doc = mongodb::bson::from_document(result)?;
61-
println!("* {:?}", doc);
60+
println!("* {:?}", result);
6261
}
6362
// end-lastactive-agg
6463

@@ -72,8 +71,7 @@ async fn main() -> mongodb::error::Result<()> {
7271

7372
let mut results = my_coll.aggregate(popularity_pipeline).await?;
7473
while let Some(result) = results.try_next().await? {
75-
let doc = mongodb::bson::from_document(result)?;
76-
println!("* {:?}", doc);
74+
println!("* {:?}", result);
7775
}
7876
// end-popular-agg
7977

0 commit comments

Comments
 (0)