Skip to content

DOCSP-48708 Specify cursor limitations #1094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 23, 2025
Merged

DOCSP-48708 Specify cursor limitations #1094

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3872ed4
DOCSP-48708 Specify cursor limitations
lindseymoore Apr 22, 2025
1261365
add chaining method to find
lindseymoore Apr 22, 2025
eeb95c1
edit
lindseymoore Apr 22, 2025
83a9f44
edit find ts example
lindseymoore Apr 22, 2025
e26cd4c
SA review
lindseymoore Apr 23, 2025
ab47f48
change cursor chain const names to be more specific
lindseymoore Apr 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 3 additions & 8 deletions source/code-snippets/usage-examples/find.js
View file
Open in desktop
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For technical reviewer: Can cursor chaining be used for findOne? Tried to chain for the findOne example on the page, but I got a TypeError: movies.findOne(...).sort is not a function error. It seems like findOne doesn't return a cursor but want to check anyways if it's an option to chain. Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct that findOne cannot be chained as it is immediately exhausting the cursor and returning a Promise<Document> not a cursor.

Original file line number Diff line number Diff line change
Expand Up @@ -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 };
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[s] I wonder of naming this sortOptions or sortOpts would be clearer?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good suggestion, I think naming it sortFields can make this more clear.

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) {
Expand Down
11 changes: 4 additions & 7 deletions source/code-snippets/usage-examples/find.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 sort = { title: 1 };
const projection = { _id: 0, title: 1, imdb: 1 };

const cursor = movies.find<Movie>(query).sort(sort).project(projection);

if ((await movies.countDocuments(query)) === 0) {
console.warn("No documents found!");
Expand Down
6 changes: 6 additions & 0 deletions source/crud/query/project.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,9 @@ 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/>`.

.. note::
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[s] What do you think of making this an include instead?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made an include called chain-cursor-methods.rst


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.
12 changes: 5 additions & 7 deletions source/crud/query/retrieve.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~
Expand Down
6 changes: 3 additions & 3 deletions source/crud/query/specify-documents-to-return.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading