Abstract Internal Should not be instantiated directly.
Readonly Internal _filterPrivate Readonly Internal _httpOptional Readonly Internal _mappingProtected Internal _nextReadonly Internal _optionsReadonly Internal _parentReadonly Internal _serdesPrivate Internal _sortProtected Internal _stateThis temporary error-ing property exists for migration convenience, and will be removed in a future version.
.bufferedCount() has been renamed to simply be .buffered().This temporary error-ing property exists for migration convenience, and will be removed in a future version.
.readBufferedDocuments() has been renamed to be .consumeBuffer().Abstract dataconst coll = db.collection(...);
const cursor = coll.find({});
cursor.dataSource === coll; // true
TableFindCursor & CollectionFindCursor override this method to return the dataSource typed exactly as Table or Collection respectively, instead of remaining a union of both.
The current status of the cursor.
An async iterator that lazily iterates over all records in the cursor.
Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.
If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return immediately.
It will close the cursor when iteration is complete, even if it was broken early.
for await (const doc of cursor) {
console.log(doc);
}
Protected _nextProtected _nextProtected _tmThe number of raw records in the buffer.
Unless the cursor was closed before the buffer was completely read, the total number of records retrieved from the server is equal to (FindCursor.consumed + FindCursor.buffered).
Creates, a new, uninitialized copy of this cursor with the exact same options and mapping.
See FindCursor.rewind for resetting the same instance of the cursor.
Closes the cursor. The cursor will be unusable after this method is called, or until FindCursor.rewind is called.
Consumes up to max records from the buffer, or all records if max is not provided.
Note that this actually consumes the buffer; it doesn't just peek at it.
Optional max: numberThe maximum number of records to read from the buffer. If not provided, all records will be read.
The records read from the buffer.
The number of records that have been read be the user from the cursor.
Unless the cursor was closed before the buffer was completely read, the total number of records retrieved from the server is equal to (FindCursor.consumed + FindCursor.buffered).
Sets the filter for the cursor, overwriting any previous filter.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new filter set.
A filter to select which records to return.
A new cursor with the new filter set.
await table.insertOne({ name: 'John', ... });
const cursor = table.find({})
.filter({ name: 'John' });
// The cursor will only return records with the name 'John'
const john = await cursor.next();
john.name === 'John'; // true
Iterates over all records in the cursor, calling the provided consumer for each record.
If the consumer returns false, iteration will stop.
Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.
If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return immediately.
It will close the cursor when iteration is complete, even if it was stopped early.
The consumer to call for each record.
A promise that resolves when iteration is complete.
If you get an IDE error "Promise returned from forEach argument is ignored", it is a known WebStorm bug.
Retrieves the vector used to perform the vector search, if applicable.
If includeSortVector is not true, this will unconditionally return null. No find request will be made.
If sort: { $vector } was used, getSortVector() will simply regurgitate that same $vector.
If sort: { $vectorize } was used, getSortVector() will return the $vector that was created from the text.
If vector search is not used, getSortVector() will simply return null. A find request will still be made.
If includeSortVector is true, and this function is called before any other cursor operation (such as
.next() or .toArray()), it'll make an API request to fetch the sort vector, filling the cursor's buffer
in the process.
If the cursor has already been executed before this function has been called, no additional API request will be made to fetch the sort vector, as it has already been cached.
But to reiterate, if includeSortVector is false, and this function is called, no API request is made, and
the cursor's buffer is not populated; it simply returns null.
The sort vector, or null if none was used (or if includeSortVector !== true).
Sets whether similarity scores should be included in the cursor's results.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new similarity setting.
Optional includeSimilarity: booleanWhether similarity scores should be included.
A new cursor with the new similarity setting.
const cursor = table.find({ name: 'John' })
.sort({ $vector: new DataAPIVector([...]) })
.includeSimilarity();
// The cursor will return the similarity scores for each record
const closest = await cursor.next();
closest.$similarity; // number
Sets whether the sort vector should be fetched on the very first API call. Note that this is a requirement
to use FindCursor.getSortVector—it'll unconditionally return null if this is not set to true.
true.Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new setting.
Optional includeSortVector: booleanWhether the sort vector should be fetched on the first API call
A new cursor with the new sort vector inclusion setting.
const cursor = table.find({ name: 'John' })
.sort({ $vectorize: 'name' })
.includeSortVector();
// The cursor will return the sort vector used
// Here, it'll be the embedding for the vector created from the name 'John'
const sortVector = await cursor.getSortVector();
sortVector; // DataAPIVector([...])
Sets the maximum number of records to return.
If limit == 0, there will be no limit on the number of records returned (beyond any that the Data API may itself enforce).
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new limit set.
The limit for this cursor.
A new cursor with the new limit set.
await collection.insertMany([
{ name: 'John', age: 30 },
{ name: 'Jane', age: 25 },
]);
const cursor = collection.find({})
.limit(1);
// The cursor will return only one record
const all = await cursor.toArray();
all.length === 1; // true
Map all records using the provided mapping function. Previous mapping functions will be composed with the new mapping function (new ∘ old).
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new projection set.
You may NOT set a projection after a mapping is already provided, to prevent potential de-sync errors.
A new cursor with the new mapping set.
const cursor = table.find({ name: 'John' });
.map(doc => doc.name);
.map(name => name.toLowerCase());
// T is `string` because the mapping function returns a string
const name = await cursor.next();
name === 'john'; // true
Fetches the next record from the cursor. Returns null if there are no more records to fetch.
If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return null.
The next record, or null if there are no more records.
Sets the projection for the cursor, overwriting any previous projection.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new projection set.
To properly type this method, you should provide a type argument to specify the shape of the projected records.
Note that you may NOT provide a projection after a mapping is already provided, to prevent potential de-sync errors.
Specifies which fields should be included/excluded in the returned records.
A new cursor with the new projection set.
const cursor = table.find({ name: 'John' });
// T is `Partial<Schema>` because the type is not specified
const rawProjected = cursor.project({ id: 0, name: 1 });
// T is { name: string }
const projected = cursor.project<{ name: string }>({ id: 0, name: 1 });
// You can also chain instead of using intermediate variables
const fluentlyProjected = table
.find({ name: 'John' })
.project<{ name: string }>({ id: 0, name: 1 });
Rewinds the cursor to its uninitialized state, clearing the buffer and any state.
Any configuration set on the cursor will remain, but iteration will start from the beginning, sending new queries to the server, even if the resultant data was already fetched by this cursor.
Sets the number of records to skip before returning. Must be used with FindCursor.sort.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new skip set.
The skip for the cursor query.
A new cursor with the new skip set.
await collection.insertMany([
{ name: 'John', age: 30 },
{ name: 'Jane', age: 25 },
]);
const cursor = collection.find({})
.sort({ age: -1 })
.skip(1);
// The cursor will skip the first record and return the second
const secondOldest = await cursor.next();
secondOldest.age === 25; // true
Sets the sort criteria for prioritizing records.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new sort set.
The sort order to prioritize which records are returned.
A new cursor with the new sort set.
await collection.insertMany([
{ name: 'John', age: 30 },
{ name: 'Jane', age: 25 },
]);
const cursor = collection.find({})
.sort({ age: -1 });
// The cursor will return records sorted by age in descending order
const oldest = await cursor.next();
oldest.age === 30; // true
Returns an array of all matching records in the cursor. The user should ensure that there is enough memory to store all records in the cursor.
Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.
If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return an empty array.
An array of all records in the cursor.
Overview
A lazy iterator over the results of some generic
findoperation on the Data API.Typing
In full, the cursor is typed as
FindCursor<T, TRaw>, whereTis the type of the mapped records, andTRawis the type of the raw records before any mapping.If no mapping function is provided,
TandTRawwill be the same type. Mapping is done using the FindCursor.map method.Options
Options may be set either through the
find({}, options)method, or through the various fluent builder methods, which, unlike Mongo, do not mutate the existing cursor, but rather return a new, uninitialized cursor with the new option(s) set.Example
See