DOCSP-48708 Specify cursor limitations

source/code-snippets/usage-examples/find.js

@@ -14,16 +14,11 @@ async function run() {
 
     // Query for movies that have a runtime less than 15 minutes
     const query = { runtime: { $lt: 15 } };
-
-    const options = {
-      // Sort returned documents in ascending order by title (A->Z)
-      sort: { title: 1 },
-      // Include only the `title` and `imdb` fields in each returned document
-      projection: { _id: 0, title: 1, imdb: 1 },
-    };
+    const sortFields = { title: 1 };
+    const projectFields = { _id: 0, title: 1, imdb: 1 };
 
     // Execute query 
-    const cursor = movies.find(query, options);
+    const cursor = movies.find(query).sort(sortFields).project(projectFields);
 
     // Print a message if no documents were found
     if ((await movies.countDocuments(query)) === 0) {

source/code-snippets/usage-examples/find.ts

@@ -25,13 +25,10 @@ async function run() {
     const movies = database.collection<Movie>("movies");
 
     const query = { runtime: { $lt: 15 } };
-    const cursor = movies.find<Movie>(
-      query,
-      {
-        sort: { title: 1 },
-        projection: { _id: 0, title: 1, imdb: 1 },
-      }
-    );
+    const sortFields = { title: 1 };
+    const projectFields = { _id: 0, title: 1, imdb: 1 };
+
+    const cursor = movies.find<Movie>(query).sort(sortFields).project(projectFields);
 
     if ((await movies.countDocuments(query)) === 0) {
       console.warn("No documents found!");

source/crud/query/project.txt

@@ -64,8 +64,8 @@ field of each document:
    :emphasize-lines: 2
 
    // return only* the name field
-   const projection = { name: 1 };
-   const cursor = myColl.find().project(projection);
+   const projectFields = { name: 1 };
+   const cursor = myColl.find().project(projectFields);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -101,8 +101,8 @@ returned documents.
    :emphasize-lines: 2
 
    // return only the name field
-   const projection = { _id: 0, name: 1 };
-   const cursor = myColl.find().project(projection);
+   const projectFields = { _id: 0, name: 1 };
+   const cursor = myColl.find().project(projectFields);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -130,8 +130,8 @@ order in which they are returned.
 
 .. code-block:: javascript
 
-   const projection = { _id: 0, rating: 1, name: 1 };
-   const cursor = myColl.find().project(projection);
+   const projectFields = { _id: 0, rating: 1, name: 1 };
+   const cursor = myColl.find().project(projectFields);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -149,3 +149,5 @@ the following results:
 
 For more projection examples, see the
 :manual:`MongoDB Manual page on Project Fields to Return from Query </tutorial/project-fields-from-query-results/>`.
+
+.. include:: /includes/crud/chain-cursor-methods.rst 

source/crud/query/retrieve.txt

@@ -96,9 +96,9 @@ see the :ref:`node-fundamentals-query-document` guide.
 
    .. code-block:: javascript
 
-      const projection = { _id: 0, field1: 1 };
+      const projectFields = { _id: 0, field1: 1 };
 
-      const findResult = await myColl.findOne().project(projection);
+      const findResult = await myColl.findOne().project(projectFields);
 
    For more information about projecting document fields, see the
    :ref:`node-fundamentals-project` guide.
@@ -235,14 +235,7 @@ Running the preceding example results in the following output:
    { title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } }
    ...
 
-You can also specify ``sort`` and ``projection`` options by chaining the
-``sort()`` and ``projection`` methods to the ``find()`` method. The following
-two commands are equivalent:
-
-.. code-block:: javascript
-
-   movies.find({ runtime: { $lt: 15 } }, { sort: { title: 1 }, projection: { _id: 0, title: 1, imdb: 1 }});
-   movies.find({ runtime: { $lt: 15 } }).sort({ title: 1}).project({ _id: 0, title: 1, imdb: 1 });
+.. include:: /includes/crud/chain-cursor-methods.rst 
 
 Additional Information
 ~~~~~~~~~~~~~~~~~~~~~~

source/crud/query/specify-documents-to-return.txt

@@ -47,12 +47,7 @@ that describe books into the ``myDB.books`` collection:
      { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 },
    ]);
 
-.. note::
-
-   You must chain ``FindCursor`` methods such as ``sort()``, ``limit()``, or 
-   ``skip()`` to a read operation before iterating the cursor. If you specify 
-   a ``FindCursor`` method after iterating the cursor, the setting does not 
-   apply to the operation.
+.. include:: /includes/crud/chain-cursor-methods.rst 
 
 .. include:: /includes/access-cursor-note.rst
 
@@ -79,8 +74,8 @@ lengths:
    // define an empty query document
    const query = {};
    // sort in descending (-1) order by length
-   const sort = { length: -1 };
-   const cursor = myColl.find(query).sort(sort);
+   const sortFields = { length: -1 };
+   const cursor = myColl.find(query).sort(sortFields);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -111,8 +106,8 @@ add more fields to the sort document:
    // define an empty query document
    const query = {};
    // sort in ascending (1) order by length
-   const sort = { length: 1, author: 1 };
-   const cursor = myColl.find(query).sort(sort);
+   const sortFields = { length: 1, author: 1 };
+   const cursor = myColl.find(query).sort(sortFields);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -157,9 +152,9 @@ This example performs the following actions:
    // define an empty query document
    const query = {};
    // sort in descending (-1) order by length
-   const sort = { length: -1 };
-   const limit = 3;
-   const cursor = myColl.find(query).sort(sort).limit(limit);
+   const sortFields = { length: -1 };
+   const limitNum = 3;
+   const cursor = myColl.find(query).sort(sortFields).limit(limitNum);
    for await (const doc of cursor) {
      console.dir(doc);
    }
@@ -213,9 +208,9 @@ by performing the following actions:
 
    // define an empty query document
    const query = {};
-   const sort = { length: -1 };
-   const skip = 4;
-   const cursor = myColl.find(query).sort(sort).skip(skip);
+   const sortFields = { length: -1 };
+   const skipNum = 4;
+   const cursor = myColl.find(query).sort(sortFields).skip(skipNum);
    for await (const doc of cursor) {
      console.dir(doc);
    }

source/includes/crud/chain-cursor-methods.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   You must chain a cursor method such as ``sort()``, ``limit()``, 
+   ``skip()``, or ``project()`` to a read operation before iterating the cursor. 
+   If you specify a cursor method after iterating the cursor, the setting does 
+   not apply to the read operation.