From f90d0afd4293ab43c7f62c110706971d570f62f0 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 11:40:15 -0400 Subject: [PATCH 01/16] make specify docs page --- .../query/specify-documents-to-return.txt | 304 +++++++++++++++++- 1 file changed, 303 insertions(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 508f266ea..036bd212f 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -25,4 +25,306 @@ operation by using the following methods: - ``limit``: Specifies the maximum number of documents to return from a query. - ``sort``: Specifies the sort order for the returned documents. -- ``skip``: Specifies the number of documents to skip before returning query results. \ No newline at end of file +- ``skip``: Specifies the number of documents to skip before returning query results. + +Sample Data for Examples +~~~~~~~~~~~~~~~~~~~~~~~~ + +To follow the examples in this guide, use the following code snippet to insert documents +that describe books into the ``myDB.books`` collection: + +.. code-block:: javascript + + const myDB = client.db("myDB"); + const myColl = myDB.collection("books"); + + await myColl.insertMany([ + { "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }, + { "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 }, + { "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 }, + { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, + { "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 }, + { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, + ]); + +.. include:: /includes/access-cursor-note.rst + +.. _node-fundamentals-limit: + +Limit +----- + +Use ``limit`` to cap the number of documents that can be returned from a read operation. +``limit`` functions as a cap on the maximum number of +documents that the operation can return, but the operation can return +a smaller number of documents if there are not enough documents present +to reach the limit. If ``limit`` is used with the +:doc:`skip ` method, the skip applies +first and the limit only applies to the documents left over after +the skip. + +The following example queries the collection to return the top three +longest books. It matches all documents because the query filter is +empty. Then, it applies a descending ``sort`` on the ``length`` field to +return longer books before shorter books and a ``limit`` to +return only the ``3`` first results: + +.. code-block:: javascript + :emphasize-lines: 4 + + // 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); + for await (const doc of cursor) { + console.dir; + } + +The code example above outputs the following three documents, sorted by +length: + +.. code-block:: json + :copyable: false + + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + { "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +.. note:: + + The order in which you call ``limit`` and ``sort`` does not matter + because the driver reorders the calls to apply the sort first and the + limit after it. The following two calls are equivalent: + + .. code-block:: javascript + + 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 +---- + +Use ``skip`` to omit documents from the beginning of the list of +returned documents for a read operation. You can combine ``skip`` with +:doc:`sort ` to omit the top +(for descending order) or bottom (for ascending order) results for a +given query. Since the :manual:`order of documents returned +` is not guaranteed in +the absence of a sort, using ``skip`` without using ``sort`` omits +arbitrary documents. + +If the value of ``skip`` exceeds the number of matched documents for +a query, then that query returns no documents. + +Example +------- + +In the following example, we query the collection with a filter that +matches all the documents and pass options that specifies ``sort`` and +``skip`` commands as query options. The sort option specifies that fruit +documents that have higher ``length`` values are returned before ones with lower +lengths. The skip option specifies that the first document is +omitted from the result: + +.. code-block:: javascript + + // define an empty query document + const query = {}; + const options = { + // sort in descending (-1) order by length + sort : { length: -1 }, + // omit the first document + skip : 1, + } + + const cursor = myColl.find(query, options); + for await (const doc of cursor) { + console.dir(doc); + } + +Since we specified that query skip the first document, the second and third highest +length documents are printed by the code snippet above: + +.. code-block:: json + :copyable: false + + { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, + { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 } + + +The ``sort`` and ``skip`` options can also be specified as methods chained to +the ``find`` method. The following two commands are equivalent: + +.. code-block:: javascript + + myColl.find(query, { sort: { rating: -1}, skip: 1}); + myColl.find(query).sort({rating: -1}).skip(1); + +Sort +---- + +Use ``sort`` to change the order in which read operations return +documents. ``Sort`` tells MongoDB to order returned documents by the +values of one or more fields in a certain direction. To sort returned +documents by a field in ascending (lowest first) order, use a value of +``1``. To sort in descending (greatest first) order instead, use ``-1``. +If you do not specify a sort, MongoDB does not guarantee the order of +query results. + +Example +------- + +Pass the following sort document to a read operation to ensure that the +operation returns books with longer lengths before books with shorter +lengths: + +.. code-block:: javascript + :emphasize-lines: 4 + + // 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); + for await (const doc of cursor) { + console.dir(doc); + } + +In this case, the number ``-1`` tells the read operation to sort the +books in descending order by length. ``find()`` returns the following +documents when this sort is used with an empty query: + +.. code-block:: json + :copyable: false + + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } + { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } + { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } + { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } + +Sometimes, the order of two or more documents is ambiguous using a +specified sort. In the above case, both "A Dance with Dragons" and +"Infinite Jest" have ``1104`` pages, so the order in which they are +returned is not guaranteed. To resolve ties in your sorted results in a +repeatable way, add more fields to the sort document: + +.. code-block:: javascript + :emphasize-lines: 4 + + // 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); + for await (const doc of cursor) { + console.dir(doc); + } + +With the addition of the ``author`` field to the sort document, the read operation sorts +matching documents first by ``length`` then, if there is a tie, by ``author``. Matched +document fields are compared in the same order as fields are specified in the sort +document. ``find()`` returns the following ordering of documents when this sort is used on +the documents matching the query, sorting ``"Martin"`` before ``"Wallace"`` for the two books with +the same length: + +.. code-block:: json + :copyable: false + + { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } + { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } + { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } + { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + +Combine Limit, Sort, and Skip +----------------------------- + +You can combine ``limit``, ``sort``, and ``skip`` in a single +operation. This allows you to set a maximum number of sorted documents to +return, skipping a specified number of documents before returning. + +The following example returns documents with the ``length`` value of +``"1104"``. The results are sorted in alphabetical order, skipping the first +document: + +.. code-block:: javascript + :emphasize-lines: 4 + + // 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, + } + const cursor = myColl.find(query).sort(sort); + 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 specifying them as +parameters in 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}); + + .. output:: + :language: json + :visible: false + + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +Additional Information +---------------------- + +For more information about specifying a query, see :ref:`node-query`. + +For more information about retrieving documents, see :ref:`node-fundamentals-retrieve-data`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API Documentation: + +- `find() <{+api+}/classes/Collection.html#find>`__ +- `limit() <{+api+}/classes/FindCursor.html#limit>`__ +- `sort() <{+api+}/classes/FindCursor.html#sort>`__ +- `skip() <{+api+}/classes/FindCursor.html#skip>`__ \ No newline at end of file From c34954adc56afdd42758db5cff653c13d09ef9ed Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 11:47:28 -0400 Subject: [PATCH 02/16] fix includes link --- source/includes/access-cursor-note.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/access-cursor-note.rst b/source/includes/access-cursor-note.rst index c3ad63f56..9b2a7b382 100644 --- a/source/includes/access-cursor-note.rst +++ b/source/includes/access-cursor-note.rst @@ -3,4 +3,4 @@ Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the - :doc:`Cursor Fundamentals page `. \ No newline at end of file + :doc:`Access Data From a Cursor page `. \ No newline at end of file From ddd0e3cdbc3011d3fb2ef67fb4dc5f973a89b019 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 11:48:08 -0400 Subject: [PATCH 03/16] fix link --- source/crud/query/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 036bd212f..9807f8786 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -59,7 +59,7 @@ Use ``limit`` to cap the number of documents that can be returned from a read op documents that the operation can return, but the operation can return a smaller number of documents if there are not enough documents present to reach the limit. If ``limit`` is used with the -:doc:`skip ` method, the skip applies +:ref:`skip ` method, the skip applies first and the limit only applies to the documents left over after the skip. From f1e0d08bb4bf5d821f048a7e8434d1a513062bfe Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 11:50:56 -0400 Subject: [PATCH 04/16] fix highlighting and links --- source/crud/query/specify-documents-to-return.txt | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 9807f8786..1cf04a35a 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -133,9 +133,6 @@ arbitrary documents. If the value of ``skip`` exceeds the number of matched documents for a query, then that query returns no documents. -Example -------- - In the following example, we query the collection with a filter that matches all the documents and pass options that specifies ``sort`` and ``skip`` commands as query options. The sort option specifies that fruit @@ -188,10 +185,7 @@ documents by a field in ascending (lowest first) order, use a value of If you do not specify a sort, MongoDB does not guarantee the order of query results. -Example -------- - -Pass the following sort document to a read operation to ensure that the +In the following example, we pass the sort document to a read operation to ensure that the operation returns books with longer lengths before books with shorter lengths: @@ -268,7 +262,7 @@ The following example returns documents with the ``length`` value of document: .. code-block:: javascript - :emphasize-lines: 4 + :emphasize-lines: 5 // define a query to look for length value of 1104 const query = {length: "1104"}; From bf2c7e9ff6f86ba67b6caff0f6dc51bc64c3d7c4 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 13:58:26 -0400 Subject: [PATCH 05/16] remove passive --- 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 1cf04a35a..493f0c51a 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -156,8 +156,8 @@ omitted from the result: console.dir(doc); } -Since we specified that query skip the first document, the second and third highest -length documents are printed by the code snippet above: +Since we specified that query skip the first document, the code snippet above prints +the second and third highest length documents: .. code-block:: json :copyable: false From 1444efb234346bb04ac589aca053ae1e47b93ad1 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 19 Mar 2025 17:07:44 -0400 Subject: [PATCH 06/16] nr feedback --- source/connect/connection-targets.txt | 4 +- .../query/specify-documents-to-return.txt | 193 +++++++++--------- 2 files changed, 100 insertions(+), 97 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index df72aba8a..61713d411 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -15,4 +15,6 @@ Choose a Connection Target :local: :backlinks: none :depth: 2 - :class: singlecol \ No newline at end of file + :class: singlecol + +.. _node-other-ways-to-connect: \ No newline at end of file diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 493f0c51a..aebb4aa92 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -23,14 +23,14 @@ Overview In this guide, you can learn how to specify which documents to return from a read operation by using the following methods: -- ``limit``: Specifies the maximum number of documents to return from a query. -- ``sort``: Specifies the sort order for the returned documents. -- ``skip``: Specifies the number of documents to skip before returning query results. +- ``limit()``: Specifies the maximum number of documents to return from a query. +- ``sort()``: Specifies the sort order for the returned documents. +- ``skip()``: Specifies the number of documents to skip before returning query results. Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ -To follow the examples in this guide, use the following code snippet to insert documents +To run the examples in this guide, use the following code snippet to insert documents that describe books into the ``myDB.books`` collection: .. code-block:: javascript @@ -54,20 +54,19 @@ that describe books into the ``myDB.books`` collection: Limit ----- -Use ``limit`` to cap the number of documents that can be returned from a read operation. -``limit`` functions as a cap on the maximum number of -documents that the operation can return, but the operation can return -a smaller number of documents if there are not enough documents present -to reach the limit. If ``limit`` is used with the -:ref:`skip ` method, the skip applies -first and the limit only applies to the documents left over after -the skip. +Use the ``limit()`` method to cap the number of documents that can be returned from a read +operation. This method specifies the maximum number of documents that the operation can +return, but the operation can return a smaller number of documents if there are not enough +documents present to reach the limit. If ``limit()`` is used with the :ref:`skip +` method, the skip applies first and the limit only applies to the +documents left over after the skip. The following example queries the collection to return the top three -longest books. It matches all documents because the query filter is -empty. Then, it applies a descending ``sort`` on the ``length`` field to -return longer books before shorter books and a ``limit`` to -return only the ``3`` first results: +longest books. + +- The query matches all documents because the query filter is empty. +- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books. +- The ``limit()`` method specifies returning only the first ``3`` results. .. code-block:: javascript :emphasize-lines: 4 @@ -94,16 +93,16 @@ length: .. note:: - The order in which you call ``limit`` and ``sort`` does not matter - because the driver reorders the calls to apply the sort first and the - limit after it. The following two calls are equivalent: + The order in which you call ``limit()`` and ``sort()`` does not matter because the + driver reorders the calls to apply the sort first. The following two calls are + equivalent: .. code-block:: javascript 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 +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: @@ -116,76 +115,20 @@ 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 ----- - -Use ``skip`` to omit documents from the beginning of the list of -returned documents for a read operation. You can combine ``skip`` with -:doc:`sort ` to omit the top -(for descending order) or bottom (for ascending order) results for a -given query. Since the :manual:`order of documents returned -` is not guaranteed in -the absence of a sort, using ``skip`` without using ``sort`` omits -arbitrary documents. - -If the value of ``skip`` exceeds the number of matched documents for -a query, then that query returns no documents. - -In the following example, we query the collection with a filter that -matches all the documents and pass options that specifies ``sort`` and -``skip`` commands as query options. The sort option specifies that fruit -documents that have higher ``length`` values are returned before ones with lower -lengths. The skip option specifies that the first document is -omitted from the result: - -.. code-block:: javascript - - // define an empty query document - const query = {}; - const options = { - // sort in descending (-1) order by length - sort : { length: -1 }, - // omit the first document - skip : 1, - } - - const cursor = myColl.find(query, options); - for await (const doc of cursor) { - console.dir(doc); - } - -Since we specified that query skip the first document, the code snippet above prints -the second and third highest length documents: - -.. code-block:: json - :copyable: false - - { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, - { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 } - - -The ``sort`` and ``skip`` options can also be specified as methods chained to -the ``find`` method. The following two commands are equivalent: - -.. code-block:: javascript - - myColl.find(query, { sort: { rating: -1}, skip: 1}); - myColl.find(query).sort({rating: -1}).skip(1); +.. _node-fundamentals-sort: Sort ---- -Use ``sort`` to change the order in which read operations return -documents. ``Sort`` tells MongoDB to order returned documents by the +Use the ``sort()`` method to change the order in which read operations return +documents. This method tells MongoDB to order returned documents by the values of one or more fields in a certain direction. To sort returned documents by a field in ascending (lowest first) order, use a value of ``1``. To sort in descending (greatest first) order instead, use ``-1``. If you do not specify a sort, MongoDB does not guarantee the order of query results. -In the following example, we pass the sort document to a read operation to ensure that the +The following example passes the sort document to a read operation to ensure that the operation returns books with longer lengths before books with shorter lengths: @@ -215,11 +158,11 @@ documents when this sort is used with an empty query: { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } -Sometimes, the order of two or more documents is ambiguous using a -specified sort. In the above case, both "A Dance with Dragons" and -"Infinite Jest" have ``1104`` pages, so the order in which they are -returned is not guaranteed. To resolve ties in your sorted results in a -repeatable way, add more fields to the sort document: +Sometimes, the order of two or more documents is ambiguous using a specified sort. In the +above case,the documents that have ``title`` values of ``"A Dance with Dragons"`` and +``"Infinite Jest"`` both have a ``length`` of ``1104``, so the order in which they are +returned is not guaranteed. To resolve ties in your sorted results in a repeatable way, +add more fields to the sort document: .. code-block:: javascript :emphasize-lines: 4 @@ -237,8 +180,7 @@ With the addition of the ``author`` field to the sort document, the read operati matching documents first by ``length`` then, if there is a tie, by ``author``. Matched document fields are compared in the same order as fields are specified in the sort document. ``find()`` returns the following ordering of documents when this sort is used on -the documents matching the query, sorting ``"Martin"`` before ``"Wallace"`` for the two books with -the same length: +the documents matching the query: .. code-block:: json :copyable: false @@ -250,16 +192,74 @@ the same length: { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } +.. _node-fundamentals-skip: + +Skip +---- + +Use the ``skip()`` method to omit documents from the beginning of the list of +returned documents for a read operation. You can combine ``skip()`` with +:ref:`sort ` to omit the top +(for descending order) or bottom (for ascending order) results for a +given query. Since the :manual:`order of documents returned +` is not guaranteed in +the absence of a sort, using ``skip()`` without using ``sort()`` omits +arbitrary documents. + +If the value of ``skip()`` exceeds the number of matched documents for +a query, then that query returns no documents. + +The following example queries the collection for the books with the second and third +highest lengths. + +- The query matches all documents because the query filter is empty. +- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books. +- The ``skip()`` method specifies that the first matching document is ommited from the result. + +.. code-block:: javascript + + // define an empty query document + const query = {}; + const sort = { length: -1 }; + const skip = 1; + const cursor = myColl.find(query).sort(sort).skip(1); + for await (const doc of cursor) { + console.dir(doc); + } + +Since the query skips the first matching document, the preceding code snippet prints +the second and third highest length documents: + +.. code-block:: json + :copyable: false + + { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, + { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 } + +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(1); + myColl.find(query, { sort: { length: -1 }, skip: 1}); + +For more information on the ``options`` settings for the ``find()`` +method, see the +`API documentation on find() <{+api+}/classes/Collection.html#find>`__. + + Combine Limit, Sort, and Skip ----------------------------- -You can combine ``limit``, ``sort``, and ``skip`` in a single +You can combine the ``limit()``, ``sort()``, and ``skip()`` options in a single operation. This allows you to set a maximum number of sorted documents to return, skipping a specified number of documents before returning. The following example returns documents with the ``length`` value of ``"1104"``. The results are sorted in alphabetical order, skipping the first -document: +document and specifies returning only the first result: .. code-block:: javascript :emphasize-lines: 5 @@ -271,8 +271,10 @@ document: sort : { title: 1 }, // omit the first document skip : 1, + // returns only the first result + limit: 1, } - const cursor = myColl.find(query).sort(sort); + const cursor = myColl.find(query, options); for await (const doc of cursor) { console.dir(doc); } @@ -288,16 +290,15 @@ document: 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 specifying them as -parameters in the ``find`` method. The following example specifies the -same query as the preceding example: +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}); + myColl.find(query).sort({ title: 1 }).skip(1).limit(1); .. output:: :language: json @@ -315,8 +316,8 @@ For more information about retrieving documents, see :ref:`node-fundamentals-ret API Documentation ~~~~~~~~~~~~~~~~~ -To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: +To learn more about any of the methods discussed in this +guide, see the following API documentation: - `find() <{+api+}/classes/Collection.html#find>`__ - `limit() <{+api+}/classes/FindCursor.html#limit>`__ From ba43f39cee1c000c239be7a88d1d20bd0b292694 Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 20 Mar 2025 10:39:33 -0400 Subject: [PATCH 07/16] final edits --- source/crud/query/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index aebb4aa92..2b0a5b546 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -57,7 +57,7 @@ Limit Use the ``limit()`` method to cap the number of documents that can be returned from a read operation. This method specifies the maximum number of documents that the operation can return, but the operation can return a smaller number of documents if there are not enough -documents present to reach the limit. If ``limit()`` is used with the :ref:`skip +documents present to reach the limit. If ``limit()`` is used with the :ref:`skip() ` method, the skip applies first and the limit only applies to the documents left over after the skip. From b490337859d0b21e31626c0e30e97170752b05cf Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 20 Mar 2025 10:40:30 -0400 Subject: [PATCH 08/16] fix typo --- 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 2b0a5b546..2bc086408 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -199,7 +199,7 @@ Skip Use the ``skip()`` method to omit documents from the beginning of the list of returned documents for a read operation. You can combine ``skip()`` with -:ref:`sort ` to omit the top +:ref:`sort() ` to omit the top (for descending order) or bottom (for ascending order) results for a given query. Since the :manual:`order of documents returned ` is not guaranteed in @@ -214,7 +214,7 @@ highest lengths. - The query matches all documents because the query filter is empty. - The descending ``sort()`` method on the ``length`` field returns longer books before shorter books. -- The ``skip()`` method specifies that the first matching document is ommited from the result. +- The ``skip()`` method specifies that the first matching document is omitted from the result. .. code-block:: javascript From 6699647647efeefee47692860aebc6d461c28130 Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 20 Mar 2025 15:15:16 -0400 Subject: [PATCH 09/16] nr feedback --- .../query/specify-documents-to-return.txt | 154 +++++++++--------- 1 file changed, 76 insertions(+), 78 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 2bc086408..eb7bb7532 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -23,8 +23,8 @@ Overview In this guide, you can learn how to specify which documents to return from a read operation by using the following methods: -- ``limit()``: Specifies the maximum number of documents to return from a query. - ``sort()``: Specifies the sort order for the returned documents. +- ``limit()``: Specifies the maximum number of documents to return from a query. - ``skip()``: Specifies the number of documents to skip before returning query results. Sample Data for Examples @@ -49,72 +49,6 @@ that describe books into the ``myDB.books`` collection: .. include:: /includes/access-cursor-note.rst -.. _node-fundamentals-limit: - -Limit ------ - -Use the ``limit()`` method to cap the number of documents that can be returned from a read -operation. This method specifies the maximum number of documents that the operation can -return, but the operation can return a smaller number of documents if there are not enough -documents present to reach the limit. If ``limit()`` is used with the :ref:`skip() -` method, the skip applies first and the limit only applies to the -documents left over after the skip. - -The following example queries the collection to return the top three -longest books. - -- The query matches all documents because the query filter is empty. -- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books. -- The ``limit()`` method specifies returning only the first ``3`` results. - -.. code-block:: javascript - :emphasize-lines: 4 - - // 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); - for await (const doc of cursor) { - console.dir; - } - -The code example above outputs the following three documents, sorted by -length: - -.. code-block:: json - :copyable: false - - { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } - { "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 } - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - -.. note:: - - The order in which you call ``limit()`` and ``sort()`` does not matter because the - driver reorders the calls to apply the sort first. The following two calls are - equivalent: - - .. code-block:: javascript - - 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-sort: Sort @@ -159,7 +93,7 @@ documents when this sort is used with an empty query: { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } Sometimes, the order of two or more documents is ambiguous using a specified sort. In the -above case,the documents that have ``title`` values of ``"A Dance with Dragons"`` and +preceding example, the documents that have ``title`` values of ``"A Dance with Dragons"`` and ``"Infinite Jest"`` both have a ``length`` of ``1104``, so the order in which they are returned is not guaranteed. To resolve ties in your sorted results in a repeatable way, add more fields to the sort document: @@ -192,13 +126,78 @@ the documents matching the query: { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } +.. _node-fundamentals-limit: + +Limit +----- + +Use the ``limit()`` method to cap the number of documents that can be returned from a read +operation. This method specifies the maximum number of documents that the operation can +return, but the operation can return a smaller number of documents if there are not enough +documents present to reach the limit. If ``limit()`` is used with the :ref:`skip() +` method, the skip applies first and the limit only applies to the +documents left over after the skip. + +This example performs the following actions: + +- Uses an empty query filter to match all documents in the collection +- Calls the ``sort()`` method to apply a descending sort on the ``length`` field to the results +- Calls the ``limit()`` method to return only the first ``3`` results + +.. code-block:: javascript + :emphasize-lines: 5 + + // 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); + for await (const doc of cursor) { + console.dir; + } + +The code example above outputs the following three documents, sorted by +length: + +.. code-block:: json + :copyable: false + + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + { "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +.. note:: + + The order in which you call ``limit()`` and ``sort()`` does not matter because the + driver reorders the calls to apply the sort first. The following two calls are + equivalent: + + .. code-block:: javascript + + 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 ---- -Use the ``skip()`` method to omit documents from the beginning of the list of -returned documents for a read operation. You can combine ``skip()`` with +Use the ``skip()`` method to omit documents from the beginning of the read operation +results. You can combine ``skip()`` with :ref:`sort() ` to omit the top (for descending order) or bottom (for ascending order) results for a given query. Since the :manual:`order of documents returned @@ -209,12 +208,12 @@ arbitrary documents. If the value of ``skip()`` exceeds the number of matched documents for a query, then that query returns no documents. -The following example queries the collection for the books with the second and third -highest lengths. +This example queries the collection for the books with the second and third +highest lengths by performing the following actions: -- The query matches all documents because the query filter is empty. -- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books. -- The ``skip()`` method specifies that the first matching document is omitted from the result. +- Uses an empty query filter to match all documents in the collection +- Calls the ``sort()`` method to apply a descending sort to the ``length`` field, which returns longer books before shorter books +- Calls the ``skip()`` method to omit the first matching document from the result .. code-block:: javascript @@ -253,16 +252,15 @@ method, see the Combine Limit, Sort, and Skip ----------------------------- -You can combine the ``limit()``, ``sort()``, and ``skip()`` options in a single +You can combine the ``limit``, ``sort``, and ``skip`` options in a single operation. This allows you to set a maximum number of sorted documents to return, skipping a specified number of documents before returning. The following example returns documents with the ``length`` value of ``"1104"``. The results are sorted in alphabetical order, skipping the first -document and specifies returning only the first result: +document and includes only the first result: .. code-block:: javascript - :emphasize-lines: 5 // define a query to look for length value of 1104 const query = {length: "1104"}; From 62f5561d979c67d03e2dd62d38eceeb47c7484d6 Mon Sep 17 00:00:00 2001 From: Angela Date: Mon, 24 Mar 2025 14:24:11 -0400 Subject: [PATCH 10/16] tech review --- .../query/specify-documents-to-return.txt | 34 ++++++++++++------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index eb7bb7532..bf16121c7 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -27,6 +27,15 @@ 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. + +.. note:: + + 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 does not apply. + Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -154,7 +163,7 @@ This example performs the following actions: const limit = 3; const cursor = myColl.find(query).sort(sort).limit(limit); for await (const doc of cursor) { - console.dir; + console.dir(doc); } The code example above outputs the following three documents, sorted by @@ -208,32 +217,32 @@ arbitrary documents. If the value of ``skip()`` exceeds the number of matched documents for a query, then that query returns no documents. -This example queries the collection for the books with the second and third -highest lengths by performing the following actions: +This example queries the collection for the books with the fifth and sixth highest lengths +by performing the following actions: - Uses an empty query filter to match all documents in the collection - Calls the ``sort()`` method to apply a descending sort to the ``length`` field, which returns longer books before shorter books -- Calls the ``skip()`` method to omit the first matching document from the result +- Calls the ``skip()`` method to omit the first four matching documents from the result .. code-block:: javascript // define an empty query document const query = {}; const sort = { length: -1 }; - const skip = 1; - const cursor = myColl.find(query).sort(sort).skip(1); + const skip = 4; + const cursor = myColl.find(query).sort(sort).skip(skip); for await (const doc of cursor) { console.dir(doc); } -Since the query skips the first matching document, the preceding code snippet prints -the second and third highest length documents: +Since the query skips the first four matching documents, the preceding code snippet prints +the fifth and sixth highest length documents: .. code-block:: json :copyable: false - { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, - { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 } + { "_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 @@ -241,13 +250,14 @@ calls are equivalent: .. code-block:: javascript - myColl.find(query).sort({ length: -1 }).skip(1); - myColl.find(query, { sort: { length: -1 }, skip: 1}); + 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 ----------------------------- From 98c26e6bb2e565ae56da084cd41891b137cd5237 Mon Sep 17 00:00:00 2001 From: Angela Date: Mon, 24 Mar 2025 14:28:40 -0400 Subject: [PATCH 11/16] fix wording --- source/crud/query/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index bf16121c7..77c8d92b2 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -34,7 +34,7 @@ You can use these methods either by chaining them to your read operation or by s 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 does not apply. + iterating the cursor, the method you specified does not apply to the operation. Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ From df4b55fbc0e4c3c3542ba649e97b33d05566e427 Mon Sep 17 00:00:00 2001 From: Angela Date: Mon, 24 Mar 2025 14:29:30 -0400 Subject: [PATCH 12/16] Fix spacing --- source/crud/query/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 77c8d92b2..d71c2611e 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -163,7 +163,7 @@ This example performs the following actions: const limit = 3; const cursor = myColl.find(query).sort(sort).limit(limit); for await (const doc of cursor) { - console.dir(doc); + console.dir(doc); } The code example above outputs the following three documents, sorted by From 4a269bdab0947e28e5291bd8acdaffcae55e8c83 Mon Sep 17 00:00:00 2001 From: Angela Date: Mon, 24 Mar 2025 14:37:59 -0400 Subject: [PATCH 13/16] spacing change --- source/crud/query/specify-documents-to-return.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index d71c2611e..b1f225c15 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -163,7 +163,7 @@ This example performs the following actions: const limit = 3; const cursor = myColl.find(query).sort(sort).limit(limit); for await (const doc of cursor) { - console.dir(doc); + console.dir(doc); } The code example above outputs the following three documents, sorted by From 421b09648b25c7d5bf5cc409e4c2e346cb05fd35 Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 31 Mar 2025 10:41:38 -0400 Subject: [PATCH 14/16] Update connection-targets.txt --- source/connect/connection-targets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 98d2e4f7d..20e3d09e2 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -18,7 +18,7 @@ Choose a Connection Target :class: singlecol .. _node-other-ways-to-connect: -======= + Overview -------- From 6cdffcfb22da8d5440f0f93f0f6d6f0bb84c6e3c Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 31 Mar 2025 10:42:51 -0400 Subject: [PATCH 15/16] Update access-cursor-note.rst --- source/includes/access-cursor-note.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/access-cursor-note.rst b/source/includes/access-cursor-note.rst index 9b2a7b382..44b058206 100644 --- a/source/includes/access-cursor-note.rst +++ b/source/includes/access-cursor-note.rst @@ -3,4 +3,4 @@ Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the - :doc:`Access Data From a Cursor page `. \ No newline at end of file + :ref:`Access Data From a Cursor page `. From 7d55403b96055da0fbfffa3935b1e17e9c9b286b Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 31 Mar 2025 10:52:55 -0400 Subject: [PATCH 16/16] Update access-cursor-note.rst --- source/includes/access-cursor-note.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/access-cursor-note.rst b/source/includes/access-cursor-note.rst index 44b058206..c72bac066 100644 --- a/source/includes/access-cursor-note.rst +++ b/source/includes/access-cursor-note.rst @@ -3,4 +3,4 @@ Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the - :ref:`Access Data From a Cursor page `. + :ref:`Access Data From a Cursor page `.