From 3872ed41c821eeae1f8f75e1350dcfc2fdd6111e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 16:17:01 -0400 Subject: [PATCH 1/6] DOCSP-48708 Specify cursor limitations --- source/crud/query/project.txt | 6 ++++++ source/crud/query/specify-documents-to-return.txt | 6 +++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index ee48d5d52..547f6cfb5 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -149,3 +149,9 @@ the following results: For more projection examples, see the :manual:`MongoDB Manual page on Project Fields to Return from Query `. + +.. note:: + + You must chain ``FindCursor`` methods such as ``project()`` to a read operation + before iterating the cursor. If you specify a projection after + iterating the cursor, the projection does not apply to the operation. diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 08dca2fe2..92d3f9881 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -49,10 +49,10 @@ that describe books into the ``myDB.books`` collection: .. note:: - You must chain ``FindCursor`` methods such as ``sort()``, ``limit()``, or + You must chain a cursor method 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. + a cursor method after iterating the cursor, the setting does not + apply to the read operation. .. include:: /includes/access-cursor-note.rst From 1261365034aab8b3a540daf7eac024ab40f8b8a1 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 16:56:21 -0400 Subject: [PATCH 2/6] add chaining method to find --- source/code-snippets/usage-examples/find.js | 11 +++-------- source/crud/query/retrieve.txt | 12 +++++------- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/source/code-snippets/usage-examples/find.js b/source/code-snippets/usage-examples/find.js index 0486e86d2..551120206 100644 --- a/source/code-snippets/usage-examples/find.js +++ b/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 sort = { title: 1 }; + const projection = { _id: 0, title: 1, imdb: 1 }; // Execute query - const cursor = movies.find(query, options); + const cursor = movies.find(query).sort(sort).project(projection); // Print a message if no documents were found if ((await movies.countDocuments(query)) === 0) { diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index dbdedcd14..f423046bb 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -235,14 +235,12 @@ 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: +.. note:: -.. 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 }); + You must chain cursor methods such as ``sort()`` 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. Additional Information ~~~~~~~~~~~~~~~~~~~~~~ From eeb95c15e599c2ceffcca7c3b8d9eff0bdeb0f4c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 16:57:26 -0400 Subject: [PATCH 3/6] edit --- source/crud/query/project.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 547f6cfb5..7078a07c5 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -152,6 +152,6 @@ For more projection examples, see the .. note:: - You must chain ``FindCursor`` methods such as ``project()`` to a read operation + You must chain a cursor method such as ``project()`` to a read operation before iterating the cursor. If you specify a projection after iterating the cursor, the projection does not apply to the operation. From 83a9f445cfbcf9ee055187d58a606027f19cad95 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 17:05:17 -0400 Subject: [PATCH 4/6] edit find ts example --- source/code-snippets/usage-examples/find.ts | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/source/code-snippets/usage-examples/find.ts b/source/code-snippets/usage-examples/find.ts index 123c1e2af..72d8195e9 100644 --- a/source/code-snippets/usage-examples/find.ts +++ b/source/code-snippets/usage-examples/find.ts @@ -25,13 +25,10 @@ async function run() { const movies = database.collection("movies"); const query = { runtime: { $lt: 15 } }; - const cursor = movies.find( - query, - { - sort: { title: 1 }, - projection: { _id: 0, title: 1, imdb: 1 }, - } - ); + const sort = { title: 1 }; + const projection = { _id: 0, title: 1, imdb: 1 }; + + const cursor = movies.find(query).sort(sort).project(projection); if ((await movies.countDocuments(query)) === 0) { console.warn("No documents found!"); From e26cd4cfacf1c8c4a7fa4e058f92f84919fffd89 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Apr 2025 10:49:00 -0400 Subject: [PATCH 5/6] SA review --- source/code-snippets/usage-examples/find.js | 6 +++--- source/code-snippets/usage-examples/find.ts | 6 +++--- source/crud/query/project.txt | 6 +----- source/crud/query/retrieve.txt | 7 +------ source/crud/query/specify-documents-to-return.txt | 7 +------ source/includes/crud/chain-cursor-methods.rst | 6 ++++++ 6 files changed, 15 insertions(+), 23 deletions(-) create mode 100644 source/includes/crud/chain-cursor-methods.rst diff --git a/source/code-snippets/usage-examples/find.js b/source/code-snippets/usage-examples/find.js index 551120206..4a389c291 100644 --- a/source/code-snippets/usage-examples/find.js +++ b/source/code-snippets/usage-examples/find.js @@ -14,11 +14,11 @@ async function run() { // Query for movies that have a runtime less than 15 minutes const query = { runtime: { $lt: 15 } }; - const sort = { title: 1 }; - const 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).sort(sort).project(projection); + const cursor = movies.find(query).sort(sortFields).project(projectFields); // Print a message if no documents were found if ((await movies.countDocuments(query)) === 0) { diff --git a/source/code-snippets/usage-examples/find.ts b/source/code-snippets/usage-examples/find.ts index 72d8195e9..efab7839a 100644 --- a/source/code-snippets/usage-examples/find.ts +++ b/source/code-snippets/usage-examples/find.ts @@ -25,10 +25,10 @@ async function run() { const movies = database.collection("movies"); const query = { runtime: { $lt: 15 } }; - const sort = { title: 1 }; - const projection = { _id: 0, title: 1, imdb: 1 }; + const sortFields = { title: 1 }; + const projectFields = { _id: 0, title: 1, imdb: 1 }; - const cursor = movies.find(query).sort(sort).project(projection); + const cursor = movies.find(query).sort(sortFields).project(projectFields); if ((await movies.countDocuments(query)) === 0) { console.warn("No documents found!"); diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 7078a07c5..26d4abe2e 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -150,8 +150,4 @@ the following results: For more projection examples, see the :manual:`MongoDB Manual page on Project Fields to Return from Query `. -.. note:: - - You must chain a cursor method such as ``project()`` to a read operation - before iterating the cursor. If you specify a projection after - iterating the cursor, the projection does not apply to the operation. +.. include:: /includes/crud/chain-cursor-methods.rst diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index f423046bb..45b39512d 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -235,12 +235,7 @@ Running the preceding example results in the following output: { title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } } ... -.. note:: - - You must chain cursor methods such as ``sort()`` 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. +.. include:: /includes/crud/chain-cursor-methods.rst Additional Information ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 92d3f9881..095e1b738 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/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 a cursor method such as ``sort()``, ``limit()``, or - ``skip()`` 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. +.. include:: /includes/crud/chain-cursor-methods.rst .. include:: /includes/access-cursor-note.rst diff --git a/source/includes/crud/chain-cursor-methods.rst b/source/includes/crud/chain-cursor-methods.rst new file mode 100644 index 000000000..716d03511 --- /dev/null +++ b/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. \ No newline at end of file From ab47f480e07afd10a992eb6e012ae53251c54164 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Apr 2025 10:57:32 -0400 Subject: [PATCH 6/6] change cursor chain const names to be more specific --- source/crud/query/project.txt | 12 +++++------ source/crud/query/retrieve.txt | 4 ++-- .../query/specify-documents-to-return.txt | 20 +++++++++---------- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 26d4abe2e..1a7771d55 100644 --- a/source/crud/query/project.txt +++ b/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); } diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 45b39512d..d5f8a22eb 100644 --- a/source/crud/query/retrieve.txt +++ b/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. diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 095e1b738..b4cc4538b 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -74,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); } @@ -106,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); } @@ -152,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); } @@ -208,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); }