DOCSP-45853 Backport Limit Results (#168)

(cherry picked from commit 56d9808)

Author: stephmarie17

source/fundamentals/crud/read-operations.txt

@@ -14,11 +14,12 @@ Read Operations
    Search Text </fundamentals/crud/read-operations/text-search>
    Sort Data </fundamentals/crud/read-operations/sort>
    Skip Results </fundamentals/crud/read-operations/skip>
+   Limit Results </fundamentals/crud/read-operations/limit>
 
 ..
    /fundamentals/crud/read-operations/count
    /fundamentals/crud/read-operations/distinct
-   /fundamentals/crud/read-operations/limit
+
    /fundamentals/crud/read-operations/project
 
 - :ref:`rust-query-guide`
@@ -28,11 +29,9 @@ Read Operations
 - :ref:`rust-search-text-guide`
 - :ref:`rust-sort-guide`
 - :ref:`rust-skip-guide`
+- :ref:`rust-limit-guide`
 
 .. - :ref:`rust-query-guide`
 .. - :ref:`rust-count-guide`
 .. - :ref:`rust-distinct-guide`
-
-
-.. - :ref:`rust-limit-guide`
 .. - :ref:`rust-project-guide`

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

@@ -0,0 +1,145 @@
+.. _rust-limit-guide:
+
+====================================
+Limit the Number of Returned Results
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: read operation, code example, pipeline, customize output 
+
+.. 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 **limit**
+operations. These operations specify the number of documents returned from a
+read operation.
+
+Use the ``limit()`` method to cap the number of documents that a read operation
+can return. The operation returns fewer documents if there are not enough
+documents present to reach the specified limit. 
+
+If you use the ``limit()`` method with the ``skip()`` method, the skip applies
+first, and the limit only applies to the remaining documents. To learn more
+about skip operations, see the :ref:`Skip Returned Results <rust-skip-guide>`
+guide.
+
+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/limit.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/limit.rs
+   :start-after: start-sample-data
+   :end-before: end-sample-data
+   :language: rust
+   :dedent:
+
+Limit Documents
+---------------
+
+You can specify the maximum number of documents to return in a query or in an
+aggregation pipeline.
+
+.. _rust-limit-method:
+
+Query Results Example
+~~~~~~~~~~~~~~~~~~~~~
+
+To limit the number of documents returned, you can initialize a ``FindOptions``
+instance and specify the number of documents you want to limit using the
+``limit()`` method. Then, pass your ``FindOptions`` struct as a parameter to the
+``find()`` method.
+
+This example runs a ``find()`` operation that performs the following actions:
+
+- Filters the results to only include documents where the ``length`` field is
+  greater than ``1000``
+- Sorts the results in ascending order of their ``length`` field values
+- Limits the results to the first two documents
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/crud/limit.rs
+      :start-after: start-limit-example
+      :end-before: end-limit-example
+      :language: rust
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Book { name: "Atlas Shrugged", author: "Rand", length: 1088 }
+      Book { name: "A Dance with Dragons", author: "Martin", length: 1104 }
+
+.. _rust-aggregation-limit:
+
+Aggregation Example
+~~~~~~~~~~~~~~~~~~~
+
+You can use the ``$limit`` stage in an aggregation pipeline to limit returned
+results. 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 descending order of their ``length`` field values
+- Limits the returned results to the first two documents
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/crud/limit.rs
+      :start-after: start-aggregation-limit-example
+      :end-before: end-aggregation-limit-example
+      :language: rust
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      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)})
+
+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-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>`__
+- `Cursor <{+api+}/struct.Cursor.html>`__
+- `aggregate() <{+api+}/struct.Collection.html#method.aggregate>`__

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

@@ -169,7 +169,6 @@ The following table describes commonly used settings that you can specify in
        | Default: ``None``
 
 .. TODO link to projection fundamentals page under projection setting
-.. TODO link to skip fundamentals page under skip setting
 
 .. note:: Instantiating Options
 
@@ -396,8 +395,7 @@ following documentation:
 - :ref:`rust-aggregation` guide
 - :ref:`rust-sort-guide` guide
 - :ref:`rust-skip-guide` guide
-
-.. - :ref:`rust-limit-guide`
+- :ref:`rust-limit-guide` guide
 .. - :ref:`rust-project-guide`
 .. - :ref:`rust-collations-guide`
 

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

@@ -130,8 +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`
+- :ref:`rust-limit-guide`
 
 API Documentation
 ~~~~~~~~~~~~~~~~~

source/includes/fundamentals/code-snippets/crud/limit.rs

@@ -0,0 +1,83 @@
+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<Book> = client.database("db").collection("books");
+
+    let books = vec![
+        Book {
+            name: "The Brothers Karamazov".to_string(),
+            author: "Dostoyevsky".to_string(),
+            length: 824,
+        },
+        Book {
+            name: "Atlas Shrugged".to_string(),
+            author: "Rand".to_string(),
+            length: 1088,
+        },
+        Book {
+            name: "Les Misérables".to_string(),
+            author: "Hugo".to_string(),
+            length: 1462,
+        },
+        Book {
+            name: "A Dance with Dragons".to_string(),
+            author: "Martin".to_string(),
+            length: 1104,
+        },
+    ];
+
+    my_coll.insert_many(books, None).await?;
+// end-sample-data
+
+// Filters the results to only include documents where the "length" field value
+// is greater than 1000, then sorts results by their "length" field values, and
+// limits the results to the first two documents.
+// start-limit-example
+    let filter = doc! { "length": { "$gt": 1000 } };
+
+    let find_options = FindOptions::builder()
+        .sort(doc! { "length": 1 })
+        .limit(2)
+        .build();
+
+    let mut cursor = my_coll.find(filter, find_options).await?;
+
+    while let Some(result) = cursor.try_next().await? {
+        println!("{:?}", result);
+    }
+// end-limit-example
+
+// Retrieves documents in the collection, sorts results by their "length" field
+// values, then limits the results to the first document.
+// start-aggregation-limit-example
+let pipeline = vec![
+    doc! { "$match": {} },
+    doc! { "$sort": { "length": -1 } },
+    doc! { "$limit": 2 },
+];
+
+let mut cursor = my_coll.aggregate(pipeline, None).await?;
+
+while let Some(result) = cursor.try_next().await? {
+    println!("{:?}", result);
+}
+// end-aggregation-limit-example
+
+    Ok(())
+}

source/includes/fundamentals/code-snippets/crud/skip.rs

@@ -64,7 +64,7 @@ async fn main() -> mongodb::error::Result<()> {
 // start-aggregation-example
 let pipeline = vec![
     doc! { "$match": {} },
-    doc! { "$sort": { "author": 1 } }
+    doc! { "$sort": { "author": 1 } },
     doc! { "$skip": 1 },
 ];