From 2487965cfb69aba5d0f28645ab742ce2e8c1338e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 10 Apr 2025 17:37:30 -0400 Subject: [PATCH 1/7] DOCSP-48707 Standardize cursor chaining methods --- source/crud/query/count.txt | 4 +++- source/crud/query/retrieve.txt | 10 ++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 9885211c3..4cb967b98 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -41,7 +41,9 @@ documentation for each method for more information. .. code-block:: javascript - collection.countDocuments({}, { hint: "_id_" }); + con + + collection.countDocuments({}).hint("_id"); Example ------- diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 585d920b6..36513980b 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -91,18 +91,16 @@ see the :ref:`node-fundamentals-query-document` guide. to the ``findOne()`` method, the operation returns a single document from a collection. - You can specify options in a find operation even when you pass an + You can cursor methods to a find operation even when you pass an empty query. For example, the following code shows how you can - specify a projection as an option while executing a find operation + specify a projection while executing a find operation that receives an empty query parameter: .. code-block:: javascript - const options = { - projection: { _id: 0, field1: 1 }, - }; + const projection = { _id: 0, field1: 1 }; - const findResult = await myColl.findOne({}, options); + const findResult = await myColl.findOne().project(projection); For more information about projecting document fields, see the :ref:`node-fundamentals-project` guide. From bf43890b485a45719c3b1f8aa6993390c416bf21 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 11 Apr 2025 17:11:49 -0400 Subject: [PATCH 2/7] tech review --- source/crud/query/retrieve.txt | 2 +- .../query/specify-documents-to-return.txt | 103 +++++++----------- 2 files changed, 38 insertions(+), 67 deletions(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 36513980b..981d55c0b 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -91,7 +91,7 @@ see the :ref:`node-fundamentals-query-document` guide. to the ``findOne()`` method, the operation returns a single document from a collection. - You can cursor methods to a find operation even when you pass an + You can chain cursor methods to a find operation even when you pass an empty query. For example, the following code shows how you can specify a projection while executing a find operation that receives an empty query parameter: diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index b1f225c15..5dff4f7a8 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -27,14 +27,26 @@ operation by using the following methods: - ``limit()``: Specifies the maximum number of documents to return from a query. - ``skip()``: Specifies the number of documents to skip before returning query results. -You can use these methods either by chaining them to your read operation or by specifying them in an -``options`` object in your call to your read operation. +Cursor Chaining API vs. Options API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: +You can specify which documents to return by chaining the above methods to your read +operation or by specifying them in an ``options`` object in your call to your +read operation. The following example shows how to use both the chaining API and the +options API to achieve the same result: - If you chain ``sort()``, ``limit()``, or ``skip()`` to a read operation, you must - specify all methods before iterating the cursor. If you specify a method after - iterating the cursor, the method you specified does not apply to the operation. +.. code-block:: javascript + + // Uses the cursor chaining API + myColl.find(query).sort({ length: -1 }).limit(3); + + // Uses the + myColl.find(query, { sort: { length: -1 }, limit: 3 }); + +We recommend that you use the cursor chaining API for [what is the reason]. The following on this +page use the cursor chaining API. For more information on passing an ``options`` +object to the ``find()`` method, see the +`find() <{+api+}/classes/Collection.html#find>`__ API documentation. Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -56,6 +68,12 @@ that describe books into the ``myDB.books`` collection: { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, ]); +.. note:: + + When you chain ``sort()``, ``limit()``, or ``skip()`` to a read operation, you must + specify all methods before iterating the cursor. If you specify a method after + iterating the cursor, the method you specified does not apply to the operation. + .. include:: /includes/access-cursor-note.rst .. _node-fundamentals-sort: @@ -187,19 +205,6 @@ length: myColl.find(query).sort({ length: -1 }).limit(3); myColl.find(query).limit(3).sort({ length: -1 }); -You can also apply ``sort()`` and ``limit()`` by specifying them in an -``options`` object in your call to the ``find()`` method. The following two -calls are equivalent: - -.. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).limit(3); - myColl.find(query, { sort: { length: -1 }, limit: 3 }); - -For more information on the ``options`` settings for the ``find()`` -method, see the -`API documentation on find() <{+api+}/classes/Collection.html#find>`__. - .. _node-fundamentals-skip: Skip @@ -244,21 +249,6 @@ the fifth and sixth highest length documents: { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } -You can also apply ``skip()`` and ``sort()`` by specifying them in an -``options`` object in your call to the ``find()`` method. The following two -calls are equivalent: - -.. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).skip(4); - myColl.find(query, { sort: { length: -1 }, skip: 4}); - -For more information on the ``options`` settings for the ``find()`` -method, see the -`API documentation on find() <{+api+}/classes/Collection.html#find>`__. - -.. _node-fundamentals-combine-lim-sort-skip: - Combine Limit, Sort, and Skip ----------------------------- @@ -270,43 +260,18 @@ The following example returns documents with the ``length`` value of ``"1104"``. The results are sorted in alphabetical order, skipping the first document and includes only the first result: -.. code-block:: javascript - - // define a query to look for length value of 1104 - const query = {length: "1104"}; - const options = { - // sort in alphabetical (1) order by title - sort : { title: 1 }, - // omit the first document - skip : 1, - // returns only the first result - limit: 1, - } - const cursor = myColl.find(query, options); - for await (const doc of cursor) { - console.dir(doc); - } - -.. code-block:: json - :copyable: false - - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - -.. note:: - - The order in which you call these methods doesn't change the documents - that are returned. The driver automatically reorders the calls to perform the - sort and skip operations first, and the limit operation afterward. - -You can also limit, sort, and skip results by chaining each method to the ``find`` method. -The following example specifies the same query as the preceding example: - .. io-code-block:: .. input:: :language: javascript - myColl.find(query).sort({ title: 1 }).skip(1).limit(1); + const query = {length: "1104"}; + + const cursor = myColl.find(query).sort({ title: 1 }).skip(1).limit(1); + + for await (const doc of cursor) { + console.dir(doc); + } .. output:: :language: json @@ -314,6 +279,12 @@ The following example specifies the same query as the preceding example: { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } +.. note:: + + The order in which you call these methods doesn't change the documents + that are returned. The driver automatically reorders the calls to perform the + sort and skip operations first, and the limit operation afterward. + Additional Information ---------------------- From 7295aaf3b90ad5622ecacb55d1a85563b3a7ac94 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 11 Apr 2025 17:15:31 -0400 Subject: [PATCH 3/7] edits --- source/crud/query/count.txt | 2 -- source/crud/query/specify-documents-to-return.txt | 8 ++++---- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 4cb967b98..b1b849e6c 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -41,8 +41,6 @@ documentation for each method for more information. .. code-block:: javascript - con - collection.countDocuments({}).hint("_id"); Example diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 5dff4f7a8..69b51fd2d 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -40,12 +40,12 @@ options API to achieve the same result: // Uses the cursor chaining API myColl.find(query).sort({ length: -1 }).limit(3); - // Uses the + // Uses the object API myColl.find(query, { sort: { length: -1 }, limit: 3 }); -We recommend that you use the cursor chaining API for [what is the reason]. The following on this -page use the cursor chaining API. For more information on passing an ``options`` -object to the ``find()`` method, see the +We recommend that you use the cursor chaining API for [what is the reason]. The +following examples on this page use the cursor chaining API. For more information +on passing an ``options`` object to the ``find()`` method, see the `find() <{+api+}/classes/Collection.html#find>`__ API documentation. Sample Data for Examples From c61b01e086df0f463427a08998e6492df1bca7e5 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 11 Apr 2025 17:18:10 -0400 Subject: [PATCH 4/7] vale check --- source/crud/query/specify-documents-to-return.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 69b51fd2d..75dc9f223 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -27,8 +27,8 @@ operation by using the following methods: - ``limit()``: Specifies the maximum number of documents to return from a query. - ``skip()``: Specifies the number of documents to skip before returning query results. -Cursor Chaining API vs. Options API -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cursor Chaining API versus the Options API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can specify which documents to return by chaining the above methods to your read operation or by specifying them in an ``options`` object in your call to your From 9317dbead8e9745eb45385715efcc3dd557df8fa Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Apr 2025 14:54:17 -0400 Subject: [PATCH 5/7] remove mention of options object --- .../query/specify-documents-to-return.txt | 21 ------------------- 1 file changed, 21 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 75dc9f223..3bd7ee546 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -27,27 +27,6 @@ operation by using the following methods: - ``limit()``: Specifies the maximum number of documents to return from a query. - ``skip()``: Specifies the number of documents to skip before returning query results. -Cursor Chaining API versus the Options API -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can specify which documents to return by chaining the above methods to your read -operation or by specifying them in an ``options`` object in your call to your -read operation. The following example shows how to use both the chaining API and the -options API to achieve the same result: - -.. code-block:: javascript - - // Uses the cursor chaining API - myColl.find(query).sort({ length: -1 }).limit(3); - - // Uses the object API - myColl.find(query, { sort: { length: -1 }, limit: 3 }); - -We recommend that you use the cursor chaining API for [what is the reason]. The -following examples on this page use the cursor chaining API. For more information -on passing an ``options`` object to the ``find()`` method, see the -`find() <{+api+}/classes/Collection.html#find>`__ API documentation. - Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ From 1c0552542eb63fdaaa3f14bdc5e3e114b5151faf Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 18 Apr 2025 13:30:47 -0400 Subject: [PATCH 6/7] order comment --- source/crud/query/specify-documents-to-return.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 3bd7ee546..cbeb7efee 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -261,8 +261,7 @@ document and includes only the first result: .. note:: The order in which you call these methods doesn't change the documents - that are returned. The driver automatically reorders the calls to perform the - sort and skip operations first, and the limit operation afterward. + that are returned. Additional Information ---------------------- From 16ea3f9aaa495a1f8ba4de2660f06c4c3f3bcffb Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 15:25:05 -0400 Subject: [PATCH 7/7] RR review --- source/crud/query/retrieve.txt | 2 +- source/crud/query/specify-documents-to-return.txt | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 981d55c0b..aa68575db 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -93,7 +93,7 @@ see the :ref:`node-fundamentals-query-document` guide. You can chain cursor methods to a find operation even when you pass an empty query. For example, the following code shows how you can - specify a projection while executing a find operation + specify a projection while performing a find operation that receives an empty query parameter: .. code-block:: javascript diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index cbeb7efee..08dca2fe2 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -49,9 +49,10 @@ that describe books into the ``myDB.books`` collection: .. note:: - When you chain ``sort()``, ``limit()``, or ``skip()`` to a read operation, you must - specify all methods before iterating the cursor. If you specify a method after - iterating the cursor, the method you specified does not apply to the operation. + 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/access-cursor-note.rst