From 5d00ace779f9d3e91b9b3c57c43f65241051a7f6 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:20:56 -0700 Subject: [PATCH 01/11] add skip page and crosslinks --- source/fundamentals/crud/read-operations.txt | 3 +- .../crud/read-operations/retrieve.txt | 3 +- .../crud/read-operations/skip.txt | 170 ++++++++++++++++++ .../crud/read-operations/sort.txt | 3 +- .../fundamentals/code-snippets/crud/skip.rs | 93 ++++++++++ .../fundamentals/code-snippets/crud/sort.rs | 2 +- 6 files changed, 269 insertions(+), 5 deletions(-) create mode 100644 source/fundamentals/crud/read-operations/skip.txt create mode 100644 source/includes/fundamentals/code-snippets/crud/skip.rs diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt index fb3551f9..e4278d6e 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -28,11 +28,12 @@ Read Operations - :ref:`rust-change-streams-guide` - :ref:`rust-search-text-guide` - :ref:`rust-sort-guide` +- :ref:`rust-skip-guide` .. - :ref:`rust-query-guide` .. - :ref:`rust-count-guide` .. - :ref:`rust-distinct-guide` -.. - :ref:`rust-skip-guide` + .. - :ref:`rust-limit-guide` .. - :ref:`rust-project-guide` diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt index e806c7f8..97d38fd4 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -388,8 +388,7 @@ following documentation: - :ref:`rust-cursor-guide` guide - :ref:`rust-aggregation` guide - :ref:`rust-sort-guide` guide - -.. - :ref:`rust-skip-guide` +- :ref:`rust-skip-guide` guide .. - :ref:`rust-limit-guide` .. - :ref:`rust-project-guide` diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt new file mode 100644 index 00000000..78498da5 --- /dev/null +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -0,0 +1,170 @@ +.. _rust-skip-guide: + +===================== +Skip Returned Results +===================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, read operation, skip, skip results + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the {+driver-long+} to specify the +number of documents to skip in a read operation. + +Sample Data for Examples +------------------------ + +The examples in this guide use the following ``Book`` struct as a model for +documents in the ``books`` collection: + +.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs + :start-after: start-book-struct + :end-before: end-book-struct + :language: rust + :dedent: + +The following code shows how to insert sample data into the ``books`` +collection: + +.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs + :start-after: start-sample-data + :end-before: end-sample-data + :language: rust + :dedent: + +Skip +---- + +To skip results retrieved by a query, you can chain the ``skip()`` method to the +``find()`` method. Alternatively, if you are setting and reusing options for +your query, you can use the ``skip()`` method of the ``FindOptions`` struct. + +If the number of documents exceeds the number of matched documents for a query, +that query returns no documents. + +Find operations return documents in a natural order that is not sorted on any +fields. To avoid skipping random documents, use the ``sort()`` method to sort +documents on a field with a unique value before setting a skip option. To learn +more, see the :ref:`rust-sort-guide` guide. + +Example +~~~~~~~ + +The following example performs a ``find()`` operation with the following behavior: + +- Sorts the results in ascending order on the ``author`` field +- Skips the first two documents +- Returns the remaining documents + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-snippets/crud/skip.rs + :start-after: start-skip-example + :end-before: end-skip-example + :language: rust + :dedent: + + .. output:: + :language: console + :visible: false + + Book { name: "A Dance with Dragons", author: "Martin", length: 1104 } + Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } + +Options Example +~~~~~~~~~~~~~~~ + +Alternatively, you can use the ``skip()`` method of the ``FindOptions`` struct. +The following example performs a ``find()`` operation with the following +behavior: + +- Sorts the results in descending order on the ``name`` field +- Skips the first document +- Limits the results to two documents +- Returns the remaining documents + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-snippets/crud/skip.rs + :start-after: start-options-skip-example + :end-before: end-options-skip-example + :language: rust + :dedent: + + .. output:: + :language: console + :visible: false + + Book { name: "Les Misérables", author: "Hugo", length: 1462 } + Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } + +Aggregation +----------- + +You can use the ``$skip`` stage in an aggegation pipeline to skip documents. To +learn more, see the :ref:`rust-aggregation-guide` guide. + +Example +~~~~~~~ + +The following example uses the ``aggregate()`` method to perform an aggregation +operation with the following behavior: + +- Sorts the results in ascending order on the ``author`` field +- Skips the first document +- Returns the remaining documents + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-snippets/crud/skip.rs + :start-after: start-aggregation-example + :end-before: end-aggregation-example + :language: rust + :dedent: + + .. output:: + :language: console + :visible: false + + Document({"_id": Int32(3), "name": String("Les Misérables"), "author": String("Hugo"), "length": Int32(1462)}) + Document({"_id": Int32(4), "name": String("A Dance with Dragons"), "author": String("Martin"), "length": Int32(1104)}) + Document({"_id": Int32(2), "name": String("Atlas Shrugged"), "author": String("Rand"), "length": Int32(1088)}) + +Additional Information +---------------------- + +To learn more about the operations mentioned in this guide, see the following: + +- :ref:`rust-query-guide` +- :ref:`rust-retrieve-guide` +- :ref:`rust-compound-operations` +- :ref:`rust-aggregation` +- :ref:`rust-sort-guide` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this guide, see the +following API Documentation: + +- `find() <{+api+}/struct.Collection.html#method.find>`__ +- `FindOptions <{+api+}/options/struct.FindOptions.html>`__ +- `FindOneOptions <{+api+}/options/struct.FindOneOptions.html>`__ +- `Cursor <{+api+}/struct.Cursor.html>`__ +- `aggregate() <{+api+}/struct.Collection.html#method.aggregate>`__ +- `AggregateOptions <{+api+}/options/struct.AggregateOptions.html>`__ \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/fundamentals/crud/read-operations/sort.txt index cae330e1..739fb094 100644 --- a/source/fundamentals/crud/read-operations/sort.txt +++ b/source/fundamentals/crud/read-operations/sort.txt @@ -182,12 +182,13 @@ The following example specifies a descending sort on the ``name`` field: Additional Information ---------------------- -To learn more about the operations metnioned in this guide, see the following: +To learn more about the operations mentioned in this guide, see the following: - :ref:`rust-query-guide` - :ref:`rust-retrieve-guide` - :ref:`rust-compound-operations` - :ref:`rust-aggregation` +- :ref:`rust-skip-guide` API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs new file mode 100644 index 00000000..39e91e64 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -0,0 +1,93 @@ +use std::env; +use mongodb::{ bson::doc, bson::Document, Client, Collection, options::FindOptions }; +use serde::{Deserialize, Serialize}; +use futures::stream::TryStreamExt; + +// start-book-struct +#[derive(Debug, Serialize, Deserialize)] +struct Book { + name: String, + author: String, + length: i32, +} +// end-book-struct + +#[tokio::main] +async fn main() -> mongodb::error::Result<()> { +// start-sample-data + let uri = "connection string"; + let client = Client::with_uri_str(uri).await?; + let my_coll: Collection = client.database("db").collection("books"); + + let books = vec![ + Book { + id: 1, + name: "The Brothers Karamazov".to_string(), + author: "Dostoyevsky".to_string(), + length: 824, + }, + Book { + id: 2, + name: "Atlas Shrugged".to_string(), + author: "Rand".to_string(), + length: 1088, + }, + Book { + id: 3, + name: "Les Misérables".to_string(), + author: "Hugo".to_string(), + length: 1462, + }, + Book { + id: 4, + name: "A Dance with Dragons".to_string(), + author: "Martin".to_string(), + length: 1104, + }, + ]; + + my_coll.insert_many(books).await?; +// end-sample-data + +// start-skip-example + let mut cursor = my_coll + .find(doc! {}) + .sort(doc! { "author": 1 }) + .skip(2).await?; + + while let Some(result) = cursor.try_next().await? { + println!("{:?}", result); + } +// end-skip-example + +// start-options-skip-example + let find_options = FindOptions::builder() + .sort(doc! { "name": -1 }) + .skip(1) + .limit(2) + .build(); + + let mut cursor = my_coll.find(doc! {}).with_options(find_options).await?; + + while let Some(result) = cursor.try_next().await? { + println!("{:?}", result); + } +// end-options-skip-example + +// start-aggregation-example +let pipeline = vec![ + doc! { "$match": {} }, + // 1 for ascending order, -1 for descending order + doc! { "$sort": { "author": 1 } } + doc! { "$skip": 1 }, +]; + +let mut cursor = my_coll.aggregate(pipeline).await?; + +while let Some(result) = cursor.try_next().await? { + println!("{:?}", result); +} +// end-aggregation-example + + Ok(()) +} \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/crud/sort.rs b/source/includes/fundamentals/code-snippets/crud/sort.rs index db2edb07..807e244f 100644 --- a/source/includes/fundamentals/code-snippets/crud/sort.rs +++ b/source/includes/fundamentals/code-snippets/crud/sort.rs @@ -77,7 +77,7 @@ while let Some(result) = cursor.try_next().await? { // start-sort-aggregation let pipeline = vec![ - docs! { "$match": {} }, + doc! { "$match": {} }, // 1 for ascending order, -1 for descending order doc! { "$sort": { "author": 1 } } ]; From 661654778d1b17681b19b8066aacbdaa4c3b0e05 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:27:00 -0700 Subject: [PATCH 02/11] add to toc --- source/fundamentals/crud/read-operations.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt index e4278d6e..9462423e 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -13,11 +13,11 @@ Read Operations /fundamentals/crud/read-operations/change-streams /fundamentals/crud/read-operations/text-search /fundamentals/crud/read-operations/sort + /fundamentals/crud/read-operations/skip .. /fundamentals/crud/read-operations/count /fundamentals/crud/read-operations/distinct - /fundamentals/crud/read-operations/skip /fundamentals/crud/read-operations/limit /fundamentals/crud/read-operations/project From 5a5efaf64ad60f55662d1a28e50db08b06fa6a44 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:33:40 -0700 Subject: [PATCH 03/11] edits --- source/fundamentals/crud/read-operations/skip.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 78498da5..30643dc1 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -51,8 +51,8 @@ To skip results retrieved by a query, you can chain the ``skip()`` method to the ``find()`` method. Alternatively, if you are setting and reusing options for your query, you can use the ``skip()`` method of the ``FindOptions`` struct. -If the number of documents exceeds the number of matched documents for a query, -that query returns no documents. +If the number of skipped documents exceeds the number of matched documents for a +query, that query returns no documents. Find operations return documents in a natural order that is not sorted on any fields. To avoid skipping random documents, use the ``sort()`` method to sort @@ -116,7 +116,7 @@ Aggregation ----------- You can use the ``$skip`` stage in an aggegation pipeline to skip documents. To -learn more, see the :ref:`rust-aggregation-guide` guide. +learn more, see the :ref:`rust-aggregation` guide. Example ~~~~~~~ @@ -155,6 +155,7 @@ To learn more about the operations mentioned in this guide, see the following: - :ref:`rust-compound-operations` - :ref:`rust-aggregation` - :ref:`rust-sort-guide` +.. - :ref:`rust-limit-guide` API Documentation ~~~~~~~~~~~~~~~~~ From d103df38facd22429b39bd1c4b69cb7c37ee32df Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:37:31 -0700 Subject: [PATCH 04/11] edit for vale --- source/fundamentals/crud/read-operations/skip.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 30643dc1..0c141dd8 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -52,7 +52,7 @@ To skip results retrieved by a query, you can chain the ``skip()`` method to the your query, you can use the ``skip()`` method of the ``FindOptions`` struct. If the number of skipped documents exceeds the number of matched documents for a -query, that query returns no documents. +query, then that query returns no documents. Find operations return documents in a natural order that is not sorted on any fields. To avoid skipping random documents, use the ``sort()`` method to sort From 858ce5678cb1f0cfe9cf7865e37b008a6d928051 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:42:26 -0700 Subject: [PATCH 05/11] add crosslink --- source/fundamentals/crud/read-operations/retrieve.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt index 97d38fd4..4849f924 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -149,7 +149,8 @@ fields that you can set by calling their corresponding builder methods: | Type: ``ReadConcern`` * - ``skip`` - - | The number of documents to skip when returning results. + - | The number of documents to skip when returning results. To learn more + about how to use the ``skip()`` builder method, see :ref:`rust-skip-guide`. | | Type: ``u64`` | Default: ``None`` From 662f3328de1815048e7662baef8e20598db3d585 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 23 Oct 2024 14:48:15 -0700 Subject: [PATCH 06/11] edits --- source/fundamentals/crud/read-operations/skip.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 0c141dd8..e76b0faa 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -115,7 +115,7 @@ behavior: Aggregation ----------- -You can use the ``$skip`` stage in an aggegation pipeline to skip documents. To +You can use the ``$skip`` stage in an aggregation pipeline to skip documents. To learn more, see the :ref:`rust-aggregation` guide. Example From a07877c8288df6607f80a2575615aff8b307f1a7 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 24 Oct 2024 10:50:46 -0700 Subject: [PATCH 07/11] NR feedback --- .../crud/read-operations/skip.txt | 52 ++++++++++++------- .../crud/read-operations/sort.txt | 2 +- .../fundamentals/code-snippets/crud/skip.rs | 7 +++ 3 files changed, 41 insertions(+), 20 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index e76b0faa..cf1c203c 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -20,8 +20,8 @@ Skip Returned Results Overview -------- -In this guide, you can learn how to use the {+driver-long+} to specify the -number of documents to skip in a read operation. +In this guide, you can learn how to use the {+driver-long+} to perform a read +operation that skips a specified number of documents when returning results. Sample Data for Examples ------------------------ @@ -44,12 +44,16 @@ collection: :language: rust :dedent: -Skip ----- +Skip Documents +-------------- -To skip results retrieved by a query, you can chain the ``skip()`` method to the -``find()`` method. Alternatively, if you are setting and reusing options for -your query, you can use the ``skip()`` method of the ``FindOptions`` struct. +This section describes how to skip results retrieved by a query in the following ways: + +- :ref:`skip() method `: Chain the ``skip()`` method to the + ``find()`` method +- :ref:`FindOptions::skip() method `: Use the ``skip()`` + method of the ``FindOptions`` struct if you are setting and reusing options + for your query If the number of skipped documents exceeds the number of matched documents for a query, then that query returns no documents. @@ -59,12 +63,18 @@ fields. To avoid skipping random documents, use the ``sort()`` method to sort documents on a field with a unique value before setting a skip option. To learn more, see the :ref:`rust-sort-guide` guide. -Example -~~~~~~~ +.. _rust-skip-method: + +skip() Method Example +~~~~~~~~~~~~~~~~~~~~~~ -The following example performs a ``find()`` operation with the following behavior: +The ``skip()`` method takes an integer that specifies the number of documents to +omit from the beginning of the result set. You can chain the ``skip()`` method +to the ``find()`` method to skip documents. -- Sorts the results in ascending order on the ``author`` field +This example runs a ``find()`` operation that performs the following actions: + +- Sorts the results in ascending order of their ``author`` field values - Skips the first two documents - Returns the remaining documents @@ -84,12 +94,17 @@ The following example performs a ``find()`` operation with the following behavio Book { name: "A Dance with Dragons", author: "Martin", length: 1104 } Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } +.. _rust-findoptions-skip: + Options Example ~~~~~~~~~~~~~~~ -Alternatively, you can use the ``skip()`` method of the ``FindOptions`` struct. -The following example performs a ``find()`` operation with the following -behavior: +Alternatively, you can set the ``skip`` field of the ``FindOptions`` struct by +using the ``skip()`` setter method. Then, chain the ``with_options()`` method to +the ``find()`` method and pass your ``FindOptions`` struct as a parameter to the +``with_options()`` method. + +This example runs a ``find()`` operation that performs the following actions: - Sorts the results in descending order on the ``name`` field - Skips the first document @@ -113,7 +128,7 @@ behavior: Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } Aggregation ------------ +~~~~~~~~~~~ You can use the ``$skip`` stage in an aggregation pipeline to skip documents. To learn more, see the :ref:`rust-aggregation` guide. @@ -121,8 +136,7 @@ learn more, see the :ref:`rust-aggregation` guide. Example ~~~~~~~ -The following example uses the ``aggregate()`` method to perform an aggregation -operation with the following behavior: +This example runs an aggregation pipeline that performs the following actions: - Sorts the results in ascending order on the ``author`` field - Skips the first document @@ -148,7 +162,7 @@ operation with the following behavior: Additional Information ---------------------- -To learn more about the operations mentioned in this guide, see the following: +To learn more about the operations mentioned in this guide, see the following guides: - :ref:`rust-query-guide` - :ref:`rust-retrieve-guide` @@ -161,7 +175,7 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this guide, see the -following API Documentation: +following API documentation: - `find() <{+api+}/struct.Collection.html#method.find>`__ - `FindOptions <{+api+}/options/struct.FindOptions.html>`__ diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/fundamentals/crud/read-operations/sort.txt index 739fb094..578fd612 100644 --- a/source/fundamentals/crud/read-operations/sort.txt +++ b/source/fundamentals/crud/read-operations/sort.txt @@ -194,7 +194,7 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this guide, see the -following API Documentation: +following API documentation: - `find() <{+api+}/struct.Collection.html#method.find>`__ - `FindOptions <{+api+}/options/struct.FindOptions.html>`__ diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs index 39e91e64..e35d0a9d 100644 --- a/source/includes/fundamentals/code-snippets/crud/skip.rs +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -49,6 +49,8 @@ async fn main() -> mongodb::error::Result<()> { my_coll.insert_many(books).await?; // end-sample-data +// Retrieves documents in the collection, sorts results by their "author" field +// values, and skips the first two results. // start-skip-example let mut cursor = my_coll .find(doc! {}) @@ -60,6 +62,9 @@ async fn main() -> mongodb::error::Result<()> { } // end-skip-example +// Sets the values for the `FindOptions` struct to sort results by their "name" +// field values, skip the first two results, and limit the results to two +// documents. // start-options-skip-example let find_options = FindOptions::builder() .sort(doc! { "name": -1 }) @@ -74,6 +79,8 @@ async fn main() -> mongodb::error::Result<()> { } // end-options-skip-example +// Retrieves documents in the collection, sorts results by their "author" field, +// then skips the first two results in an aggregation pipeline. // start-aggregation-example let pipeline = vec![ doc! { "$match": {} }, From ffeff33df9a622a792bf33026874957726715686 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 24 Oct 2024 11:29:03 -0700 Subject: [PATCH 08/11] clean up aggregation section --- .../crud/read-operations/skip.txt | 22 +++++++++++-------- .../fundamentals/code-snippets/crud/skip.rs | 1 - 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index cf1c203c..ad949511 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -52,8 +52,12 @@ This section describes how to skip results retrieved by a query in the following - :ref:`skip() method `: Chain the ``skip()`` method to the ``find()`` method - :ref:`FindOptions::skip() method `: Use the ``skip()`` - method of the ``FindOptions`` struct if you are setting and reusing options - for your query + method of the ``FindOptions`` struct + +Alternatively, you can :ref:`skip documents in an aggregation pipeline +`. + +When you skip documents, the driver omits the specified number of documents from If the number of skipped documents exceeds the number of matched documents for a query, then that query returns no documents. @@ -69,7 +73,7 @@ skip() Method Example ~~~~~~~~~~~~~~~~~~~~~~ The ``skip()`` method takes an integer that specifies the number of documents to -omit from the beginning of the result set. You can chain the ``skip()`` method +omit from the beginning of the result set. Chain the ``skip()`` method to the ``find()`` method to skip documents. This example runs a ``find()`` operation that performs the following actions: @@ -99,7 +103,8 @@ This example runs a ``find()`` operation that performs the following actions: Options Example ~~~~~~~~~~~~~~~ -Alternatively, you can set the ``skip`` field of the ``FindOptions`` struct by +Alternatively, if you are setting and reusing options for your query, you can +use ``FindOptions``. Set the ``skip`` field of the ``FindOptions`` struct by using the ``skip()`` setter method. Then, chain the ``with_options()`` method to the ``find()`` method and pass your ``FindOptions`` struct as a parameter to the ``with_options()`` method. @@ -127,15 +132,14 @@ This example runs a ``find()`` operation that performs the following actions: Book { name: "Les Misérables", author: "Hugo", length: 1462 } Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } -Aggregation -~~~~~~~~~~~ +.. _rust-aggregation-skip: + +Aggregation Example +~~~~~~~~~~~~~~~~~~~ You can use the ``$skip`` stage in an aggregation pipeline to skip documents. To learn more, see the :ref:`rust-aggregation` guide. -Example -~~~~~~~ - This example runs an aggregation pipeline that performs the following actions: - Sorts the results in ascending order on the ``author`` field diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs index e35d0a9d..a03d53fa 100644 --- a/source/includes/fundamentals/code-snippets/crud/skip.rs +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -84,7 +84,6 @@ async fn main() -> mongodb::error::Result<()> { // start-aggregation-example let pipeline = vec![ doc! { "$match": {} }, - // 1 for ascending order, -1 for descending order doc! { "$sort": { "author": 1 } } doc! { "$skip": 1 }, ]; From dd023ee2515f83ccf1b9d7a97e33c38fa18e4333 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 24 Oct 2024 11:34:40 -0700 Subject: [PATCH 09/11] update for consistency --- source/fundamentals/crud/read-operations/skip.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index ad949511..e449ec1a 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -111,7 +111,7 @@ the ``find()`` method and pass your ``FindOptions`` struct as a parameter to the This example runs a ``find()`` operation that performs the following actions: -- Sorts the results in descending order on the ``name`` field +- Sorts the results in descending order of their ``name`` field values - Skips the first document - Limits the results to two documents - Returns the remaining documents @@ -142,7 +142,7 @@ learn more, see the :ref:`rust-aggregation` guide. This example runs an aggregation pipeline that performs the following actions: -- Sorts the results in ascending order on the ``author`` field +- Sorts the results in ascending order of their ``author`` field values - Skips the first document - Returns the remaining documents From f13be463d8b1cf41db307e4c04a8ee603755b360 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 24 Oct 2024 11:47:38 -0700 Subject: [PATCH 10/11] edit --- source/fundamentals/crud/read-operations/skip.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index e449ec1a..2a71fddc 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -57,8 +57,6 @@ This section describes how to skip results retrieved by a query in the following Alternatively, you can :ref:`skip documents in an aggregation pipeline `. -When you skip documents, the driver omits the specified number of documents from - If the number of skipped documents exceeds the number of matched documents for a query, then that query returns no documents. From 98ec3adfb0fb180d0674396cb4e38c533dff277f Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 24 Oct 2024 15:30:50 -0700 Subject: [PATCH 11/11] NR feedback --- .../crud/read-operations/skip.txt | 26 +++++++++---------- .../fundamentals/code-snippets/crud/skip.rs | 4 +-- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 2a71fddc..08046d33 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -47,15 +47,16 @@ collection: Skip Documents -------------- -This section describes how to skip results retrieved by a query in the following ways: +You can skip results retrieved by a query, or you can skip results within an +aggregation pipeline. + +This section describes how to skip results in the following ways: - :ref:`skip() method `: Chain the ``skip()`` method to the ``find()`` method -- :ref:`FindOptions::skip() method `: Use the ``skip()`` - method of the ``FindOptions`` struct - -Alternatively, you can :ref:`skip documents in an aggregation pipeline -`. +- :ref:`FindOptions struct `: Use the ``skip()`` option + builder method to configure a ``FindOptions`` struct +- :ref:`Aggregation pipleline `: Create a pipeline that uses the ``$skip`` stage If the number of skipped documents exceeds the number of matched documents for a query, then that query returns no documents. @@ -70,9 +71,9 @@ more, see the :ref:`rust-sort-guide` guide. skip() Method Example ~~~~~~~~~~~~~~~~~~~~~~ +To skip documents, you can chain the ``skip()`` method to the ``find()`` method. The ``skip()`` method takes an integer that specifies the number of documents to -omit from the beginning of the result set. Chain the ``skip()`` method -to the ``find()`` method to skip documents. +omit from the beginning of the result set. This example runs a ``find()`` operation that performs the following actions: @@ -103,15 +104,14 @@ Options Example Alternatively, if you are setting and reusing options for your query, you can use ``FindOptions``. Set the ``skip`` field of the ``FindOptions`` struct by -using the ``skip()`` setter method. Then, chain the ``with_options()`` method to -the ``find()`` method and pass your ``FindOptions`` struct as a parameter to the -``with_options()`` method. +using the ``skip()`` option builder method. Then, chain the ``with_options()`` +method to the ``find()`` method and pass your ``FindOptions`` struct as a +parameter to the ``with_options()`` method. This example runs a ``find()`` operation that performs the following actions: - Sorts the results in descending order of their ``name`` field values - Skips the first document -- Limits the results to two documents - Returns the remaining documents .. io-code-block:: @@ -136,7 +136,7 @@ Aggregation Example ~~~~~~~~~~~~~~~~~~~ You can use the ``$skip`` stage in an aggregation pipeline to skip documents. To -learn more, see the :ref:`rust-aggregation` guide. +learn more about aggregation operations, see the :ref:`rust-aggregation` guide. This example runs an aggregation pipeline that performs the following actions: diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs index a03d53fa..47bd31e0 100644 --- a/source/includes/fundamentals/code-snippets/crud/skip.rs +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -63,13 +63,11 @@ async fn main() -> mongodb::error::Result<()> { // end-skip-example // Sets the values for the `FindOptions` struct to sort results by their "name" -// field values, skip the first two results, and limit the results to two -// documents. +// field values, skip the first two results, and return the remaining results. // start-options-skip-example let find_options = FindOptions::builder() .sort(doc! { "name": -1 }) .skip(1) - .limit(2) .build(); let mut cursor = my_coll.find(doc! {}).with_options(find_options).await?;