Merge remote-tracking branch 'upstream/master' into DOCSP-44853-update-usage-exs

Author: norareidy

source/fundamentals/aggregation.txt

@@ -183,11 +183,11 @@ month.
 
 The aggregation pipeline contains the following stages:
 
-- A ``$project`` stage to extract the month from the ``last_active``
-  field as a number into the ``month_last_active`` field.
-- A ``$group`` stage to group documents by the ``month_last_active``
-  field and count the number of documents for each month.
-- A ``$sort`` stage to set an ascending sort on the month.
+- ``$project`` stage to extract the month from the ``last_active``
+  field as a number into the ``month_last_active`` field
+- ``$group`` stage to group documents by the ``month_last_active``
+  field and count the number of documents for each month
+- ``$sort`` stage to set an ascending sort on the month
 
 .. io-code-block::
 
@@ -216,12 +216,12 @@ often they appear in users' interests.
 
 The aggregation pipeline contains the following stages:
 
-- An ``$unwind`` stage to separate each array entry in the
-  ``genre_interests`` field into a new document.
-- A ``$group`` stage to group documents by the ``genre_interests``
-  field and count the number of documents for each genre.
-- A ``$sort`` stage to set a descending sort on the genre popularity.
-- A ``$limit`` stage to show only the first three genres.
+- ``$unwind`` stage to separate each array entry in the
+  ``genre_interests`` field into a new document
+- ``$group`` stage to group documents by the ``genre_interests``
+  field and count the number of documents for each genre
+- ``$sort`` stage to set a descending sort on the genre popularity
+- ``$limit`` stage to show only the first three genres
 
 .. io-code-block::
 

source/fundamentals/connections/tls.txt

@@ -81,7 +81,7 @@ Select from the following :guilabel:`Connection String` and
          :emphasize-lines: 4-5
 
          let uri = "<connection string>"
-         let mut client_options = ClientOptions::parse_async(uri).await?;
+         let mut client_options = ClientOptions::parse(uri).await?;
 
          let tls_opts = TlsOptions::builder().build();
          client_options.tls = Some(Tls::Enabled(tls_opts));

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/query.txt

@@ -111,6 +111,9 @@ The examples in the following sections query a collection of documents described
    :start-after: begin-sample-docs
    :end-before: end-sample-docs
 
+To learn how to insert this data into a collection, see the
+:ref:`rust-insert-guide` guide.
+
 .. _rust-literal-values:
 
 Literal Values
@@ -240,7 +243,7 @@ divisible by ``3``:
    .. code-block:: rust
 
       my_coll.find(doc! {
-         $and: [
+         "$and": [
             doc! { "price": { "$eq": 5 }},
             doc! { "quantity": { "$gt": 4 }}
          ]

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

@@ -59,6 +59,9 @@ information about its categorization and unit price:
    :start-after: start-sample
    :end-before: end-sample
 
+To learn how to insert this data into a collection, see the
+:ref:`rust-insert-guide` guide.
+
 .. _rust-retrieve-find:
 
 Find Operations
@@ -166,7 +169,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
 
@@ -350,9 +352,10 @@ Example
 This example shows how to call the ``aggregate()`` method with a
 pipeline that contains the following stages:
 
-- A ``$group`` stage to group documents by the ``category`` field and
-  calculate the average of the ``unit_price`` field by ``category``
-- A ``$sort`` stage to by ``avg_price`` in ascending order
+- ``$group`` stage to calculate the average of the ``unit_price``
+  field for each value of the ``category`` field
+- ``$sort`` stage to order results by ``avg_price`` in ascending
+  order
 
 .. io-code-block::
    :copyable: true
@@ -390,8 +393,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/performance.txt

@@ -122,7 +122,7 @@ option. The following code demonstrates how to specify a value for
 
 .. code-block:: rust
 
-   let mut client_options = ClientOptions::parse_async("<connection string>").await?;
+   let mut client_options = ClientOptions::parse("<connection string>").await?;
    client_options.max_pool_size = Some(20);
 
    let client = Client::with_options(client_options)?;
@@ -156,7 +156,7 @@ instantiating a ``Client``:
 
 .. code-block:: rust
 
-   let mut client_options = ClientOptions::parse_async("<connection string>").await?;
+   let mut client_options = ClientOptions::parse("<connection string>").await?;
    client_options.max_connecting = Some(3);
    client_options.min_pool_size = Some(1);
 
@@ -185,7 +185,7 @@ The following code sets the value of the ``max_idle_time`` option to
 
 .. code-block:: rust
 
-   let mut client_options = ClientOptions::parse_async("<connection string>").await?;
+   let mut client_options = ClientOptions::parse("<connection string>").await?;
    client_options.max_idle_time = Some(Duration::new(90, 0));
 
    let client = Client::with_options(client_options)?;

source/fundamentals/stable-api.txt

@@ -70,6 +70,7 @@ and connects to a server.
    :dedent:
    :start-after: start-stable-api
    :end-before: end-stable-api
+   :emphasize-lines: 3-4
 
 .. _rust-stable-api-options:
 

source/includes/fundamentals/code-snippets/aggregation.rs

@@ -1,6 +1,7 @@
-use bson::{ doc, DateTime };
+use bson::{ doc, DateTime, Document };
 use mongodb::{ Client, Collection };
 use serde::{ Deserialize, Serialize };
+use futures::stream::TryStreamExt;
 
 #[tokio::main]
 async fn main() -> mongodb::error::Result<()> {
@@ -42,8 +43,7 @@ async fn main() -> mongodb::error::Result<()> {
 
     let mut results = my_coll.aggregate(age_pipeline).await?;
     while let Some(result) = results.try_next().await? {
-        let doc = mongodb::bson::from_document(result)?;
-        println!("* {:?}", doc);
+        println!("* {:?}", result);
     }
     // end-age-agg
 
@@ -57,8 +57,7 @@ async fn main() -> mongodb::error::Result<()> {
 
     let mut results = my_coll.aggregate(last_active_pipeline).await?;
     while let Some(result) = results.try_next().await? {
-        let doc = mongodb::bson::from_document(result)?;
-        println!("* {:?}", doc);
+        println!("* {:?}", result);
     }
     // end-lastactive-agg
 
@@ -72,8 +71,7 @@ async fn main() -> mongodb::error::Result<()> {
 
     let mut results = my_coll.aggregate(popularity_pipeline).await?;
     while let Some(result) = results.try_next().await? {
-        let doc = mongodb::bson::from_document(result)?;
-        println!("* {:?}", doc);
+        println!("* {:?}", result);
     }
     // end-popular-agg