From 1c56d070cd8034b5642285585b877498d1d11520 Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Fri, 25 Oct 2024 15:11:46 -0700 Subject: [PATCH 1/5] DOCSP-43424 Skip returned results (#133) (cherry picked from commit cb8a4771ed85dea5e22f99ef382db43789580c8b) --- source/fundamentals/crud/read-operations.txt | 4 +- .../crud/read-operations/retrieve.txt | 6 +- .../crud/read-operations/skip.txt | 187 ++++++++++++++++++ .../crud/read-operations/sort.txt | 1 + .../fundamentals/code-snippets/crud/skip.rs | 97 +++++++++ 5 files changed, 290 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 2f30d068..5003b800 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -17,7 +17,6 @@ Read Operations .. /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 @@ -28,11 +27,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 7e646728..ad92a492 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -152,7 +152,8 @@ The following table describes commonly used settings that you can specify in | 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`` @@ -394,8 +395,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..08046d33 --- /dev/null +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -0,0 +1,187 @@ +.. _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 perform a read +operation that skips a specified number of documents when returning results. + +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 Documents +-------------- + +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 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. + +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. + +.. _rust-skip-method: + +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. + +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 + +.. 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 } + +.. _rust-findoptions-skip: + +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()`` 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 +- 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 } + +.. _rust-aggregation-skip: + +Aggregation Example +~~~~~~~~~~~~~~~~~~~ + +You can use the ``$skip`` stage in an aggregation pipeline to skip documents. To +learn more about aggregation operations, see the :ref:`rust-aggregation` guide. + +This example runs an aggregation pipeline that performs the following actions: + +- Sorts the results in ascending order of their ``author`` field values +- 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 guides: + +- :ref:`rust-query-guide` +- :ref:`rust-retrieve-guide` +- :ref:`rust-compound-operations` +- :ref:`rust-aggregation` +- :ref:`rust-sort-guide` +.. - :ref:`rust-limit-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 3d5d9721..56d0933d 100644 --- a/source/fundamentals/crud/read-operations/sort.txt +++ b/source/fundamentals/crud/read-operations/sort.txt @@ -174,6 +174,7 @@ To learn more about the operations mentioned in this guide, see the following: - :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..47bd31e0 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -0,0 +1,97 @@ +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 + +// 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! {}) + .sort(doc! { "author": 1 }) + .skip(2).await?; + + while let Some(result) = cursor.try_next().await? { + println!("{:?}", 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 return the remaining results. +// start-options-skip-example + let find_options = FindOptions::builder() + .sort(doc! { "name": -1 }) + .skip(1) + .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 + +// 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": {} }, + 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 From 942dc139f8198fee7abcecf1158e4a0661a7cda7 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 11 Feb 2025 15:00:10 -0800 Subject: [PATCH 2/5] updates for version --- source/fundamentals/crud/read-operations.txt | 1 + .../crud/read-operations/skip.txt | 54 +++---------------- .../fundamentals/code-snippets/crud/skip.rs | 28 +++------- 3 files changed, 15 insertions(+), 68 deletions(-) diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt index 5003b800..7ecab809 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -13,6 +13,7 @@ Read Operations Open Change Streams Search Text Sort Data + Skip Results .. /fundamentals/crud/read-operations/count diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index 08046d33..8508f536 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -50,14 +50,6 @@ Skip Documents 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 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. @@ -66,14 +58,14 @@ 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. -.. _rust-skip-method: +.. _rust-skip-example: -skip() Method Example -~~~~~~~~~~~~~~~~~~~~~~ +Query Results 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. +To skip documents, you can initialize a ``FindOptions`` instance and specify the +number of documents you want to skip using the ``skip()`` option. Then, pass +your ``FindOptions`` struct as a parameter to the ``find()`` method. This example runs a ``find()`` operation that performs the following actions: @@ -97,39 +89,6 @@ This example runs a ``find()`` operation that performs the following actions: Book { name: "A Dance with Dragons", author: "Martin", length: 1104 } Book { name: "Atlas Shrugged", author: "Rand", length: 1088 } -.. _rust-findoptions-skip: - -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()`` 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 -- 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 } - .. _rust-aggregation-skip: Aggregation Example @@ -171,6 +130,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 diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs index 47bd31e0..7ac52b80 100644 --- a/source/includes/fundamentals/code-snippets/crud/skip.rs +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -1,5 +1,5 @@ use std::env; -use mongodb::{ bson::doc, bson::Document, Client, Collection, options::FindOptions }; +use mongodb::{ bson::doc, Client, Collection, options::FindOptions }; use serde::{Deserialize, Serialize}; use futures::stream::TryStreamExt; @@ -46,36 +46,22 @@ async fn main() -> mongodb::error::Result<()> { }, ]; - my_coll.insert_many(books).await?; + my_coll.insert_many(books, None).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! {}) - .sort(doc! { "author": 1 }) - .skip(2).await?; - - while let Some(result) = cursor.try_next().await? { - println!("{:?}", 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 return the remaining results. -// start-options-skip-example let find_options = FindOptions::builder() - .sort(doc! { "name": -1 }) - .skip(1) + .sort(doc! { "author": 1 }) + .skip(2) .build(); - - let mut cursor = my_coll.find(doc! {}).with_options(find_options).await?; + let mut cursor = my_coll.find(doc! {}, find_options).await?; while let Some(result) = cursor.try_next().await? { println!("{:?}", result); } -// end-options-skip-example +// end-skip-example // Retrieves documents in the collection, sorts results by their "author" field, // then skips the first two results in an aggregation pipeline. @@ -86,7 +72,7 @@ let pipeline = vec![ doc! { "$skip": 1 }, ]; -let mut cursor = my_coll.aggregate(pipeline).await?; +let mut cursor = my_coll.aggregate(pipeline, None).await?; while let Some(result) = cursor.try_next().await? { println!("{:?}", result); From caa4f6eb85a5eaa3116bbcb31ce718f6f8a1a800 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 12 Feb 2025 10:01:35 -0800 Subject: [PATCH 3/5] edit --- 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 8508f536..e016b59c 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -64,7 +64,7 @@ Query Results Example ~~~~~~~~~~~~~~~~~~~~~ To skip documents, you can initialize a ``FindOptions`` instance and specify the -number of documents you want to skip using the ``skip()`` option. Then, pass +number of documents you want to skip using the ``skip()`` method. Then, pass your ``FindOptions`` struct as a parameter to the ``find()`` method. This example runs a ``find()`` operation that performs the following actions: From a211035201f3d4f1fce36d420124a54f0e71f0be Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 12 Feb 2025 10:39:30 -0800 Subject: [PATCH 4/5] updates --- source/fundamentals/crud/read-operations/skip.txt | 6 +++--- source/includes/fundamentals/code-snippets/crud/skip.rs | 4 ---- 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt index e016b59c..816d194d 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -116,9 +116,9 @@ This example runs an aggregation pipeline that performs the following actions: :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)}) + Document({"_id": ObjectId("..."), "name": String("Les Misérables"), "author": String("Hugo"), "length": Int32(1462)}) + Document({"_id": ObjectId("..."), "name": String("A Dance with Dragons"), "author": String("Martin"), "length": Int32(1104)}) + Document({"_id": ObjectId("..."), "name": String("Atlas Shrugged"), "author": String("Rand"), "length": Int32(1088)}) Additional Information ---------------------- diff --git a/source/includes/fundamentals/code-snippets/crud/skip.rs b/source/includes/fundamentals/code-snippets/crud/skip.rs index 7ac52b80..89b431ea 100644 --- a/source/includes/fundamentals/code-snippets/crud/skip.rs +++ b/source/includes/fundamentals/code-snippets/crud/skip.rs @@ -21,25 +21,21 @@ async fn main() -> mongodb::error::Result<()> { 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, From 265bcc9b1d5c3f055ddd4acb71c10800e6dc341f Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 12 Feb 2025 10:56:01 -0800 Subject: [PATCH 5/5] edits --- 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 816d194d..2bbd1240 100644 --- a/source/fundamentals/crud/read-operations/skip.txt +++ b/source/fundamentals/crud/read-operations/skip.txt @@ -29,7 +29,7 @@ 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 +.. literalinclude:: /includes/fundamentals/code-snippets/crud/skip.rs :start-after: start-book-struct :end-before: end-book-struct :language: rust @@ -38,7 +38,7 @@ documents in the ``books`` collection: The following code shows how to insert sample data into the ``books`` collection: -.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs +.. literalinclude:: /includes/fundamentals/code-snippets/crud/skip.rs :start-after: start-sample-data :end-before: end-sample-data :language: rust