Skip to content

Commit a728f4d

Browse files
norareidynorareidy
committed
DOCSP-44963: Data modeling in find usage examples (#137)
(cherry picked from commit 592712d)
1 parent 02c4305 commit a728f4d

File tree

7 files changed

+165
-77
lines changed

7 files changed

+165
-77
lines changed

‎source/fundamentals/crud/read-operations/skip.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,8 @@ To learn more about the operations mentioned in this guide, see the following gu
172172
- :ref:`rust-aggregation`
173173
- :ref:`rust-sort-guide`
174174

175+
.. - :ref:`rust-limit-guide`
176+
175177
API Documentation
176178
~~~~~~~~~~~~~~~~~
177179

‎source/includes/usage-examples/code-snippets/find-async.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@ async fn main() -> mongodb::error::Result<()> {
1717
let uri = "<connection string>";
1818
let client = Client::with_uri_str(uri).await?;
1919

20-
let my_coll: Collection<Restaurant> = client
20+
// Replace <T> with the <Document> or <Restaurant> type parameter
21+
let my_coll: Collection<T> = client
2122
.database("sample_restaurants")
2223
.collection("restaurants");
2324

@@ -26,7 +27,7 @@ async fn main() -> mongodb::error::Result<()> {
2627
).await?;
2728

2829
while let Some(doc) = cursor.try_next().await? {
29-
println!("{:?}", doc);
30+
println!("{:#?}", doc);
3031
}
3132

3233
Ok(())

‎source/includes/usage-examples/code-snippets/find-one-async.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ async fn main() -> mongodb::error::Result<()> {
1616
let uri = "<connection string>";
1717
let client = Client::with_uri_str(uri).await?;
1818

19-
let my_coll: Collection<Restaurant> = client
19+
// Replace <T> with the <Document> or <Restaurant> type parameter
20+
let my_coll: Collection<T> = client
2021
.database("sample_restaurants")
2122
.collection("restaurants");
2223

‎source/includes/usage-examples/code-snippets/find-one-sync.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ fn main() -> mongodb::error::Result<()> {
1414
let uri = "<connection string>";
1515
let client = Client::with_uri_str(uri)?;
1616

17-
let my_coll: Collection<Restaurant> = client
17+
// Replace <T> with the <Document> or <Restaurant> type parameter
18+
let my_coll: Collection<T> = client
1819
.database("sample_restaurants")
1920
.collection("restaurants");
2021

‎source/includes/usage-examples/code-snippets/find-sync.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ fn main() -> mongodb::error::Result<()> {
1414
let uri = "<connection string>";
1515
let client = Client::with_uri_str(uri)?;
1616

17-
let my_coll: Collection<Restaurant> = client
17+
// Replace <T> with the <Document> or <Restaurant> type parameter
18+
let my_coll: Collection<T> = client
1819
.database("sample_restaurants")
1920
.collection("restaurants");
2021

@@ -23,7 +24,7 @@ fn main() -> mongodb::error::Result<()> {
2324
).run()?;
2425

2526
for result in cursor {
26-
println!("{:?}", result?);
27+
println!("{:#?}", result?);
2728
}
2829

2930
Ok(())

‎source/usage-examples/find.txt

Lines changed: 87 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,19 @@
44
Find Multiple Documents
55
=======================
66

7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: read, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
720
You can query for multiple documents in a collection by calling the
821
`find() <{+api+}/struct.Collection.html#method.find>`__ method on a
922
``Collection`` instance.
@@ -26,54 +39,92 @@ Example
2639
-------
2740

2841
This example retrieves documents that match a query filter from the ``restaurants``
29-
collection in the ``sample_restaurants`` database. The example populates
30-
instances of the ``Restaurant`` struct with data from the retrieved
31-
documents.
42+
collection in the ``sample_restaurants`` database. The ``find()`` method returns
43+
all documents in which the value of the ``cuisine`` field is ``"French"``.
3244

33-
The following code uses a query filter that matches documents in which the value
34-
of the ``cuisine`` field is ``"French"``.
45+
You can model each retrieved document as a BSON data type or a custom data type. To specify
46+
which data type represents the collection's data, replace the ``<T>`` type parameter on the
47+
highlighted line with one of the following values:
48+
49+
- ``<Document>``: Retrieves and prints collection documents as BSON documents
50+
- ``<Restaurant>``: Retrieves and prints collection documents as instances of the ``Restaurant``
51+
struct, defined at the top of the code
3552

3653
Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to
3754
see the corresponding code for each runtime:
3855

3956
.. tabs::
4057

4158
.. tab:: Asynchronous
42-
:tabid: find-async
43-
44-
.. io-code-block::
45-
:copyable: true
59+
:tabid: find-one-async
4660

47-
.. input:: /includes/usage-examples/code-snippets/find-async.rs
48-
:language: rust
49-
:dedent:
50-
51-
.. output::
52-
:language: console
53-
:visible: false
54-
55-
// Results truncated
56-
...
57-
Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" }
58-
Restaurant { name: "Calliope", cuisine: "French" }
59-
...
61+
.. literalinclude:: /includes/usage-examples/code-snippets/find-async.rs
62+
:language: rust
63+
:emphasize-lines: 21
64+
:dedent:
6065

6166
.. tab:: Synchronous
62-
:tabid: find-sync
67+
:tabid: find-one-sync
6368

64-
.. io-code-block::
65-
:copyable: true
69+
.. literalinclude:: /includes/usage-examples/code-snippets/find-sync.rs
70+
:language: rust
71+
:emphasize-lines: 18
72+
:dedent:
6673

67-
.. input:: /includes/usage-examples/code-snippets/find-sync.rs
68-
:language: rust
69-
:dedent:
74+
Output
75+
~~~~~~
7076

71-
.. output::
72-
:language: console
73-
:visible: false
77+
Select the :guilabel:`BSON Document Results` or :guilabel:`Restaurant Struct Results` tab to
78+
see the corresponding code output based on your collection's type parameter:
79+
80+
.. tabs::
7481

75-
// Results truncated
76-
...
77-
Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" }
78-
Restaurant { name: "Calliope", cuisine: "French" }
79-
...
82+
.. tab:: BSON Document Results
83+
:tabid: find-one-async
84+
85+
.. code-block:: none
86+
:copyable: false
87+
88+
...
89+
Some(
90+
Document({
91+
"_id": ObjectId(
92+
"...",
93+
),
94+
...
95+
"name": String(
96+
"Cafe Un Deux Trois",
97+
),
98+
...
99+
}),
100+
),
101+
Some(
102+
Document({
103+
"_id": ObjectId(
104+
"...",
105+
),
106+
...
107+
"name": String(
108+
"Calliope",
109+
),
110+
...
111+
}),
112+
)
113+
...
114+
115+
.. tab:: Restaurant Struct Results
116+
:tabid: find-one-sync
117+
118+
.. code-block:: none
119+
:copyable: false
120+
121+
...
122+
Restaurant {
123+
name: "Cafe Un Deux Trois",
124+
cuisine: "French",
125+
}
126+
Restaurant {
127+
name: "Calliope",
128+
cuisine: "French",
129+
}
130+
...

‎source/usage-examples/findOne.txt

Lines changed: 66 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,19 @@
44
Find a Document
55
===============
66

7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: first, retrieve, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
720
You can retrieve a single document from a collection by calling the `find_one()
821
<{+api+}/struct.Collection.html#method.find_one>`__ method on a ``Collection`` instance.
922

@@ -22,12 +35,16 @@ Example
2235
-------
2336

2437
This example retrieves a document that matches a query filter from the ``restaurants``
25-
collection in the ``sample_restaurants`` database. The example populates a ``Restaurant``
26-
struct with data from the retrieved document.
38+
collection in the ``sample_restaurants`` database. The ``find_one()`` method returns the
39+
first document in which the value of the ``name`` field is ``"Tompkins Square Bagels"``.
2740

28-
This example uses a query filter that matches documents in which the value of the
29-
``name`` field is ``"Tompkins Square Bagels"``. MongoDB retrieves the
30-
first document that matches the query filter.
41+
You can model the retrieved document as a BSON data type or a custom data type. To specify
42+
which data type represents the collection's data, replace the ``<T>`` type parameter on the
43+
highlighted line with one of the following values:
44+
45+
- ``<Document>``: Retrieves and prints collection documents as BSON documents
46+
- ``<Restaurant>``: Retrieves and prints collection documents as instances of the ``Restaurant``
47+
struct, defined at the top of the code
3148

3249
Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to
3350
see the corresponding code for each runtime:
@@ -37,41 +54,55 @@ see the corresponding code for each runtime:
3754
.. tab:: Asynchronous
3855
:tabid: find-one-async
3956

40-
.. io-code-block::
41-
:copyable: true
57+
.. literalinclude:: /includes/usage-examples/code-snippets/find-one-async.rs
58+
:language: rust
59+
:emphasize-lines: 20
60+
:dedent:
61+
62+
.. tab:: Synchronous
63+
:tabid: find-one-sync
4264

43-
.. input:: /includes/usage-examples/code-snippets/find-one-async.rs
44-
:language: rust
45-
:dedent:
65+
.. literalinclude:: /includes/usage-examples/code-snippets/find-one-sync.rs
66+
:language: rust
67+
:emphasize-lines: 18
68+
:dedent:
4669

47-
.. output::
48-
:language: console
49-
:visible: false
70+
Output
71+
~~~~~~
5072

51-
Some(
52-
Restaurant {
53-
name: "Tompkins Square Bagels",
54-
cuisine: "American",
55-
},
56-
)
73+
Select the :guilabel:`BSON Document Result` or :guilabel:`Restaurant Struct Result` tab to
74+
see the corresponding code output based on your collection's type parameter:
5775

58-
.. tab:: Synchronous
59-
:tabid: find-one-sync
76+
.. tabs::
6077

61-
.. io-code-block::
62-
:copyable: true
78+
.. tab:: BSON Document Result
79+
:tabid: find-one-async
6380

64-
.. input:: /includes/usage-examples/code-snippets/find-one-sync.rs
65-
:language: rust
66-
:dedent:
81+
.. code-block:: none
82+
:copyable: false
83+
84+
Some(
85+
Document({
86+
"_id": ObjectId(
87+
"...",
88+
),
89+
...
90+
"name": String(
91+
"Tompkins Square Bagels",
92+
),
93+
...
94+
}),
95+
)
96+
97+
.. tab:: Restaurant Struct Result
98+
:tabid: find-one-sync
6799

68-
.. output::
69-
:language: console
70-
:visible: false
100+
.. code-block:: none
101+
:copyable: false
71102

72-
Some(
73-
Restaurant {
74-
name: "Tompkins Square Bagels",
75-
cuisine: "American",
76-
},
77-
)
103+
Some(
104+
Restaurant {
105+
name: "Tompkins Square Bagels",
106+
cuisine: "American",
107+
},
108+
)

0 commit comments

Comments
 (0)