Skip to content

feat(NODE-6472): findOne and find no longer keep open cursors #4580

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.

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

Open
wants to merge 12 commits into
base: main
Choose a base branch
from

Conversation

durran
Copy link
Member

@durran durran commented Jul 9, 2025

Description

Changes findOne to set options that will not require a cursor or a killCursors command. Updates find to not leave cursors open on the server when batch size and limit are equal.

What is changing?

  • The find one operation now deprecates options for it specifically which are irrelevant.
  • The find operation now sets batchSize to batchSize + 1 when the limit is equal to it.
  • Syncs CRUD spec tests.
Is there new documentation needed for these changes?

API docs on the findOne options.

What is the motivation for this change?

NODE-6472

Release Highlight

collection.findOne() and collection.find() will no longer potentially leave open cursors on the server

The findOne command will now always set the limit option to 1 and singleBatch to true. The limit, noCursorResponse and batchSize options have also been deprecated, and the command will guarantee no more cursors can be orphaned and no killCursors command will be potentially executed.

find will now set limit to batchSize + 1 when both options were equal, to avoid leaving cursors open.

Double check the following

  • Ran npm run check:lint script
  • Self-review completed using the steps outlined here
  • PR title follows the correct format: type(NODE-xxxx)[!]: description
    • Example: feat(NODE-1234)!: rewriting everything in coffeescript
  • Changes are covered by tests
  • New TODOs have a related JIRA ticket

@durran durran force-pushed the NODE-6472 branch 4 times, most recently from 11b1cf5 to 9fe1c2d Compare July 11, 2025 16:24
@durran durran changed the title feat(NODE-6472): run findOne without cursor feat(NODE-6472): findOne and find no longer keep open cursors Jul 22, 2025
const res = await cursor.next();
await cursor.close();
return res;
const opts = { ...options };
Copy link
Member Author

Choose a reason for hiding this comment

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

I made the decision here to do the options changes - creating a new find one operation was much more code and was suspiciously failing 6 tests in load balancer mode. This creating the cursor object works just fine and passes all tests, no killCursors is sent and the cursor on the server side always comes back with id 0.

@durran durran marked this pull request as ready for review July 22, 2025 22:25
@durran durran requested a review from a team as a code owner July 22, 2025 22:25
@baileympearson baileympearson self-assigned this Jul 23, 2025
@baileympearson baileympearson added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Jul 23, 2025
@@ -81,6 +81,16 @@ export interface FindOptions<TSchema extends Document = Document>
timeoutMode?: CursorTimeoutMode;
}

/** @public */
export interface FindOneOptions extends FindOptions {
/** @deprecated Will be removed in the next major version. User provided value will be ignored. */
Copy link
Contributor

Choose a reason for hiding this comment

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

Do we have a ticket to remove these fields from FindOneOptions in v7?

Copy link
Contributor

Choose a reason for hiding this comment

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

We'd need to add this to the bucket deprecations ticket in V7 or file a new ticket in V7 if the change goes through. (Let's add AC to the ticket to remember to do this). But why are we introducing exposing a brand new interface with deprecated options at all? If we remove these options from the interface, we are going to be back at FindOneOptions being the same as FindOptions - is the intent to replace the definition of this interface in V7 with a copy of FindOptions minus these three?

Copy link
Contributor

Choose a reason for hiding this comment

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

I expect that once they're removed, we will have:

/** @public */
export type FindOneOptions = Omit<FindOptions, ....>;

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, I think if we're doing more than just removing deprecations, we should do it in a separate ticket from the bucket work (to streamline the bucketed option removal).

Copy link
Member Author

Choose a reason for hiding this comment

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

So a separate ticket to NODE-5545? I had added these removals there but can create a another ticket.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't have a very strong preference as far as using the bucket ticket or filing a separate one if the team feels like it's not necessary, but we do want to capture that this won't be strictly deleting the deprecation lines, because I can see us moving quickly down that list in the bucket and inadvertently ending up back at FindOneOptions = FindOptions

@@ -195,7 +205,13 @@ function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOp

findCommand.singleBatch = true;
} else {
findCommand.batchSize = options.batchSize;
if (options.batchSize === options.limit) {
Copy link
Contributor

Choose a reason for hiding this comment

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

the if statement above, which set singleBatch: true was only used for findOne I think. Is that dead code we can remove now?

Copy link
Member Author

Choose a reason for hiding this comment

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

Good call. I've removed it.

Copy link
Contributor

Choose a reason for hiding this comment

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

I also noticed two if-statements above:

  if (typeof options.limit === 'number') {
    if (options.limit < 0) {
      findCommand.limit = -options.limit;
      findCommand.singleBatch = true;
    } else {
      findCommand.limit = options.limit;
    }
  }

We can remove the first nested if-statement there, right? That seems to have been used for find one with the old findOne implementation:

    const cursor = this.find(filter, options).limit(-1).batchSize(1);

delete opts.batchSize;
}
const cursor = this.find(filter, opts).limit(1);
return await cursor.next();
Copy link
Contributor

Choose a reason for hiding this comment

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

Copy link
Contributor

Choose a reason for hiding this comment

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

Also - one of the AC in the ticket:

Ensure no killCursors command is sent to the server.

Do we test this anywhere? (should we test this?)

Copy link
Member Author

Choose a reason for hiding this comment

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

The new unified tests added have expectedEvents that would fail if a killCursors command was issued, so I considered this acceptable from a testing point. As for the previous point, there is a performance aspect to the ticket, so I felt there was no need to go through the close logic when in theory it would not be needed.

Copy link
Contributor

Choose a reason for hiding this comment

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

Close is effectively a no-op when the cursor is already exhausted but if it ever weren't exhausted, we'd be leaking cursors. I think it's worth adding a call to close just in case.

If we're really concerned about throughput, we could even not await close:

cursor.close().then(squashError, squashError);
return result;

@durran durran requested a review from baileympearson July 24, 2025 10:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Primary Review In Review with primary reviewer, not yet ready for team's eyes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants