From 91e49ad5922df22b8289fd6894a7882c13d2e52b Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 30 Oct 2024 15:03:32 -0400 Subject: [PATCH 1/8] DOCSP-44853: Data modeling in usage examples --- .../code-snippets/find-one-async.rs | 3 +- .../code-snippets/find-one-sync.rs | 3 +- source/usage-examples/findOne.txt | 92 ++++++++++++------- 3 files changed, 61 insertions(+), 37 deletions(-) diff --git a/source/includes/usage-examples/code-snippets/find-one-async.rs b/source/includes/usage-examples/code-snippets/find-one-async.rs index ed2c5c30..5de01b78 100644 --- a/source/includes/usage-examples/code-snippets/find-one-async.rs +++ b/source/includes/usage-examples/code-snippets/find-one-async.rs @@ -16,7 +16,8 @@ async fn main() -> mongodb::error::Result<()> { let uri = ""; let client = Client::with_uri_str(uri).await?; - let my_coll: Collection = client + // Replace with the or type parameter + let my_coll: Collection = client .database("sample_restaurants") .collection("restaurants"); diff --git a/source/includes/usage-examples/code-snippets/find-one-sync.rs b/source/includes/usage-examples/code-snippets/find-one-sync.rs index d138e2af..6517589f 100644 --- a/source/includes/usage-examples/code-snippets/find-one-sync.rs +++ b/source/includes/usage-examples/code-snippets/find-one-sync.rs @@ -14,7 +14,8 @@ fn main() -> mongodb::error::Result<()> { let uri = ""; let client = Client::with_uri_str(uri)?; - let my_coll: Collection = client + // Replace with the or type parameter + let my_coll: Collection = client .database("sample_restaurants") .collection("restaurants"); diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index d34156bd..e96f6d01 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -22,12 +22,16 @@ Example ------- This example retrieves a document that matches a query filter from the ``restaurants`` -collection in the ``sample_restaurants`` database. The example populates a ``Restaurant`` -struct with data from the retrieved document. +collection in the ``sample_restaurants`` database. The ``find_one()`` method returns the +first document in which the value of the ``name`` field is ``"Tompkins Square Bagels"``. -This example uses a query filter that matches documents in which the value of the -``name`` field is ``"Tompkins Square Bagels"``. MongoDB retrieves the -first document that matches the query filter. +You can model the retrieved document as a BSON data type or a custom data type. To specify +which data type models the collection's data, replace the ```` type parameter on the +highlighted line with one of the following values: + +- ````: Retrieves and prints collection documents as BSON documents +- ````: Retrieves and prints collection documents as instances of the ``Restaurant`` + struct, defined at the top of the code Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to see the corresponding code for each runtime: @@ -37,41 +41,59 @@ see the corresponding code for each runtime: .. tab:: Asynchronous :tabid: find-one-async - .. io-code-block:: - :copyable: true + .. literalinclude:: /includes/usage-examples/code-snippets/find-one-async.rs + :language: rust + :emphasize-lines: 19 + :dedent: - .. input:: /includes/usage-examples/code-snippets/find-one-async.rs - :language: rust - :dedent: + .. tab:: Synchronous + :tabid: find-one-sync - .. output:: - :language: console - :visible: false + .. literalinclude:: /includes/usage-examples/code-snippets/find-one-sync.rs + :language: rust + :emphasize-lines: 17 + :dedent: - Some( - Restaurant { - name: "Tompkins Square Bagels", - cuisine: "American", - }, - ) +Output +~~~~~~ - .. tab:: Synchronous - :tabid: find-one-sync +Select the :guilabel:`BSON Document Result` or :guilabel:`Restaurant Struct Result` tab to +see the corresponding code output based on your collection's type parameter: - .. io-code-block:: - :copyable: true +.. tabs:: - .. input:: /includes/usage-examples/code-snippets/find-one-sync.rs - :language: rust - :dedent: + .. tab:: BSON Document Result + :tabid: find-one-async + + .. code-block:: none + :copyable: false + + Some( + Document({ + "_id": ObjectId( + "...", + ), + + ... + + "name": String( + "Tompkins Square Bagels", + ), + "restaurant_id": String( + "41605054", + ), + }), + ) + + .. tab:: Restaurant Struct Result + :tabid: find-one-sync - .. output:: - :language: console - :visible: false + .. code-block:: none + :copyable: false - Some( - Restaurant { - name: "Tompkins Square Bagels", - cuisine: "American", - }, - ) + Some( + Restaurant { + name: "Tompkins Square Bagels", + cuisine: "American", + }, + ) \ No newline at end of file From e2367803db1cdfac69b8595acc2e8c54ab51a1e1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 30 Oct 2024 15:09:03 -0400 Subject: [PATCH 2/8] fix highlight --- source/usage-examples/findOne.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index e96f6d01..c4fd3b81 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -43,7 +43,7 @@ see the corresponding code for each runtime: .. literalinclude:: /includes/usage-examples/code-snippets/find-one-async.rs :language: rust - :emphasize-lines: 19 + :emphasize-lines: 20 :dedent: .. tab:: Synchronous @@ -51,7 +51,7 @@ see the corresponding code for each runtime: .. literalinclude:: /includes/usage-examples/code-snippets/find-one-sync.rs :language: rust - :emphasize-lines: 17 + :emphasize-lines: 18 :dedent: Output From 9e99d76164dc4ec6d43d4890b9e8d89fb70603ac Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 30 Oct 2024 15:41:10 -0400 Subject: [PATCH 3/8] page nav --- source/usage-examples/findOne.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index c4fd3b81..7321bd67 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -4,6 +4,19 @@ Find a Document =============== +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: first, retrieve, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + You can retrieve a single document from a collection by calling the `find_one() <{+api+}/struct.Collection.html#method.find_one>`__ method on a ``Collection`` instance. From 742a27c51f83028f09fbe448a608d5e4da584058 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 30 Oct 2024 15:42:33 -0400 Subject: [PATCH 4/8] wording --- source/usage-examples/findOne.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index 7321bd67..ea9ebb83 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -39,7 +39,7 @@ collection in the ``sample_restaurants`` database. The ``find_one()`` method ret first document in which the value of the ``name`` field is ``"Tompkins Square Bagels"``. You can model the retrieved document as a BSON data type or a custom data type. To specify -which data type models the collection's data, replace the ```` type parameter on the +which data type represents the collection's data, replace the ```` type parameter on the highlighted line with one of the following values: - ````: Retrieves and prints collection documents as BSON documents From bd65415b1d07cd25579e298da5dd1d4f84aeb112 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 31 Oct 2024 10:59:22 -0400 Subject: [PATCH 5/8] find multiple --- .../code-snippets/find-async.rs | 5 +- .../usage-examples/code-snippets/find-sync.rs | 5 +- source/usage-examples/find.txt | 125 +++++++++++++----- 3 files changed, 95 insertions(+), 40 deletions(-) diff --git a/source/includes/usage-examples/code-snippets/find-async.rs b/source/includes/usage-examples/code-snippets/find-async.rs index 86d46ba7..59f515ca 100644 --- a/source/includes/usage-examples/code-snippets/find-async.rs +++ b/source/includes/usage-examples/code-snippets/find-async.rs @@ -17,7 +17,8 @@ async fn main() -> mongodb::error::Result<()> { let uri = ""; let client = Client::with_uri_str(uri).await?; - let my_coll: Collection = client + // Replace with the or type parameter + let my_coll: Collection = client .database("sample_restaurants") .collection("restaurants"); @@ -26,7 +27,7 @@ async fn main() -> mongodb::error::Result<()> { ).await?; while let Some(doc) = cursor.try_next().await? { - println!("{:?}", doc); + println!("{:#?}", doc); } Ok(()) diff --git a/source/includes/usage-examples/code-snippets/find-sync.rs b/source/includes/usage-examples/code-snippets/find-sync.rs index 8dd49f6e..b639187d 100644 --- a/source/includes/usage-examples/code-snippets/find-sync.rs +++ b/source/includes/usage-examples/code-snippets/find-sync.rs @@ -14,7 +14,8 @@ fn main() -> mongodb::error::Result<()> { let uri = ""; let client = Client::with_uri_str(uri)?; - let my_coll: Collection = client + // Replace with the or type parameter + let my_coll: Collection = client .database("sample_restaurants") .collection("restaurants"); @@ -23,7 +24,7 @@ fn main() -> mongodb::error::Result<()> { ).run()?; for result in cursor { - println!("{:?}", result?); + println!("{:#?}", result?); } Ok(()) diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt index 44eb622e..847deed9 100644 --- a/source/usage-examples/find.txt +++ b/source/usage-examples/find.txt @@ -4,6 +4,19 @@ Find Multiple Documents ======================= +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + You can query for multiple documents in a collection by calling the `find() <{+api+}/struct.Collection.html#method.find>`__ method on a ``Collection`` instance. @@ -26,12 +39,16 @@ Example ------- This example retrieves documents that match a query filter from the ``restaurants`` -collection in the ``sample_restaurants`` database. The example populates -instances of the ``Restaurant`` struct with data from the retrieved -documents. +collection in the ``sample_restaurants`` database. The ``find()`` method returns +all documents in which the value of the ``cuisine`` field is ``"French"``. -The following code uses a query filter that matches documents in which the value -of the ``cuisine`` field is ``"French"``. +You can model each retrieved document as a BSON data type or a custom data type. To specify +which data type represents the collection's data, replace the ```` type parameter on the +highlighted line with one of the following values: + +- ````: Retrieves and prints collection documents as BSON documents +- ````: Retrieves and prints collection documents as instances of the ``Restaurant`` + struct, defined at the top of the code Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to see the corresponding code for each runtime: @@ -39,41 +56,77 @@ see the corresponding code for each runtime: .. tabs:: .. tab:: Asynchronous - :tabid: find-async - - .. io-code-block:: - :copyable: true + :tabid: find-one-async - .. input:: /includes/usage-examples/code-snippets/find-async.rs - :language: rust - :dedent: - - .. output:: - :language: console - :visible: false - - // Results truncated - ... - Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" } - Restaurant { name: "Calliope", cuisine: "French" } - ... + .. literalinclude:: /includes/usage-examples/code-snippets/find-async.rs + :language: rust + :emphasize-lines: 22 + :dedent: .. tab:: Synchronous - :tabid: find-sync + :tabid: find-one-sync - .. io-code-block:: - :copyable: true + .. literalinclude:: /includes/usage-examples/code-snippets/find-sync.rs + :language: rust + :emphasize-lines: 19 + :dedent: - .. input:: /includes/usage-examples/code-snippets/find-sync.rs - :language: rust - :dedent: +Output +~~~~~~ - .. output:: - :language: console - :visible: false +Select the :guilabel:`BSON Document Results` or :guilabel:`Restaurant Struct Results` tab to +see the corresponding code output based on your collection's type parameter: + +.. tabs:: - // Results truncated - ... - Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" } - Restaurant { name: "Calliope", cuisine: "French" } - ... + .. tab:: BSON Document Results + :tabid: find-one-async + + .. code-block:: none + :copyable: false + + ... + Some( + Document({ + "_id": ObjectId( + "...", + ), + + ... + + "name": String( + "Cafe Un Deux Trois", + ), + "restaurant_id": String( + "40369461", + ), + }), + ), + Some( + Document({ + "_id": ObjectId( + "...", + ), + + ... + + "name": String( + "Calliope", + ), + "restaurant_id": String( + "41665122", + ), + }), + ) + ... + + .. tab:: Restaurant Struct Results + :tabid: find-one-sync + + .. code-block:: none + :copyable: false + + ... + Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" } + Restaurant { name: "Calliope", cuisine: "French" } + ... \ No newline at end of file From 2808e8bafea63c9fc3adfce58b74738c111ab403 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 31 Oct 2024 11:33:27 -0400 Subject: [PATCH 6/8] edits --- source/usage-examples/find.txt | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt index 847deed9..33c1b068 100644 --- a/source/usage-examples/find.txt +++ b/source/usage-examples/find.txt @@ -60,7 +60,7 @@ see the corresponding code for each runtime: .. literalinclude:: /includes/usage-examples/code-snippets/find-async.rs :language: rust - :emphasize-lines: 22 + :emphasize-lines: 21 :dedent: .. tab:: Synchronous @@ -68,7 +68,7 @@ see the corresponding code for each runtime: .. literalinclude:: /includes/usage-examples/code-snippets/find-sync.rs :language: rust - :emphasize-lines: 19 + :emphasize-lines: 18 :dedent: Output @@ -127,6 +127,12 @@ see the corresponding code output based on your collection's type parameter: :copyable: false ... - Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" } - Restaurant { name: "Calliope", cuisine: "French" } + Restaurant { + name: "Cafe Un Deux Trois", + cuisine: "French", + } + Restaurant { + name: "Calliope", + cuisine: "French", + } ... \ No newline at end of file From 9d617492e8a82243130301c90b16b73ab0885fe8 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 4 Nov 2024 09:58:47 -0500 Subject: [PATCH 7/8] fix build error --- source/fundamentals/crud/read-operations/skip.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 08046d33..84b8b3d1 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -171,6 +171,7 @@ To learn more about the operations mentioned in this guide, see the following gu - :ref:`rust-compound-operations` - :ref:`rust-aggregation` - :ref:`rust-sort-guide` + .. - :ref:`rust-limit-guide` API Documentation From 979cdbf97cd0baf36c5e06c580333c62ebc0526b Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 4 Nov 2024 15:45:19 -0500 Subject: [PATCH 8/8] RR feedback --- source/usage-examples/find.txt | 12 ++---------- source/usage-examples/findOne.txt | 6 +----- 2 files changed, 3 insertions(+), 15 deletions(-) diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt index 33c1b068..7bbb5c77 100644 --- a/source/usage-examples/find.txt +++ b/source/usage-examples/find.txt @@ -91,15 +91,11 @@ see the corresponding code output based on your collection's type parameter: "_id": ObjectId( "...", ), - ... - "name": String( "Cafe Un Deux Trois", ), - "restaurant_id": String( - "40369461", - ), + ... }), ), Some( @@ -107,15 +103,11 @@ see the corresponding code output based on your collection's type parameter: "_id": ObjectId( "...", ), - ... - "name": String( "Calliope", ), - "restaurant_id": String( - "41665122", - ), + ... }), ) ... diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index ea9ebb83..d3d0a2af 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -86,15 +86,11 @@ see the corresponding code output based on your collection's type parameter: "_id": ObjectId( "...", ), - ... - "name": String( "Tompkins Square Bagels", ), - "restaurant_id": String( - "41605054", - ), + ... }), )