diff --git a/source/code-snippets/usage-examples/find.js b/source/code-snippets/usage-examples/find.js index 0486e86d2..4a389c291 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 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) { diff --git a/source/code-snippets/usage-examples/find.ts b/source/code-snippets/usage-examples/find.ts index 123c1e2af..efab7839a 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 sortFields = { title: 1 }; + const projectFields = { _id: 0, title: 1, imdb: 1 }; + + 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 ee48d5d52..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); } @@ -149,3 +149,5 @@ the following results: For more projection examples, see the :manual:`MongoDB Manual page on Project Fields to Return from Query `. + +.. include:: /includes/crud/chain-cursor-methods.rst diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index dbdedcd14..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. @@ -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 ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 08dca2fe2..b4cc4538b 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 ``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); } 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