DOCSP-43423 Add limit returned results page (#134)

(cherry picked from commit 1704aa5)

Author: stephmarie17

source/fundamentals/crud/read-operations.txt

@@ -14,11 +14,12 @@ Read Operations
    /fundamentals/crud/read-operations/text-search
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
+   /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
 
 
@@ -29,11 +30,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,183 @@
+.. _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.
+
+This section describes how to limit results in the following ways:
+
+- :ref:`limit() method <rust-limit-method>`: Chain the ``limit()`` method to the
+  ``find()`` method
+- :ref:`FindOptions struct <rust-findoptions-limit>`: Use the ``limit`` option
+- :ref:`Aggregation pipleline <rust-aggregation-limit>`: Create a pipeline that uses the ``$limit`` stage
+
+.. _rust-limit-method:
+
+limit() Method Example
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To limit the number of documents returned, you can chain the ``limit()`` method
+to the ``find()`` method.
+
+This example runs a ``find()`` operation that performs the following actions:
+
+- Sorts the results in ascending order of their ``length`` field values
+- Limits the results to the first three 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: "The Brothers Karamazov", author: "Dostoyevsky", length: 824 }
+      Book { name: "Atlas Shrugged", author: "Rand", length: 1088 }
+      Book { name: "A Dance with Dragons", author: "Martin", length: 1104 }
+
+.. _rust-findoptions-limit:
+
+Options Example
+~~~~~~~~~~~~~~~
+
+Alternatively, if you are setting and reusing options for your query, you can
+use ``FindOptions``. Set the ``limit`` field of the ``FindOptions`` struct by
+using the ``limit()`` 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:
+
+- 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-options-example
+      :end-before: end-limit-options-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": 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)})
+
+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

@@ -166,7 +166,6 @@ fields that you can set by calling their corresponding builder methods:
        | Default: ``None``
 
 .. TODO link to projection fundamentals page under projection setting
-.. TODO link to skip fundamentals page under skip setting
 
 .. note:: Setting Options
 
@@ -390,8 +389,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

@@ -171,7 +171,6 @@ 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
 ~~~~~~~~~~~~~~~~~

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

@@ -0,0 +1,100 @@
+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 {
+            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 "length" field
+// values, and limits the results to three documents.
+// start-limit-example
+    let mut cursor = my_coll
+        .find(doc! {})
+        .sort(doc! { "length": 1 })
+        .limit(3).await?;
+
+    while let Some(result) = cursor.try_next().await? {
+    println!("{:?}", result);
+    }
+// end-limit-example
+
+// 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-options-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).with_options(find_options).await?;
+
+    while let Some(result) = cursor.try_next().await? {
+        println!("{:?}", result);
+    }
+// end-limit-options-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).await?;
+
+while let Some(result) = cursor.try_next().await? {
+    println!("{:?}", result);
+}
+// end-aggregation-limit-example
+
+    Ok(())
+}

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

@@ -82,7 +82,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 },
 ];