Abstract Internal Should not be instantiated directly.
Optional options: GenericFindAndRerankOptionsOptional mapping: ((doc) => T)Optional initialPage: FindAndRerankPage<RerankedResult<TRaw>>Optional Internal _currentReadonly Internal _internalOptional Readonly Internal _mappingProtected Internal _stateReadonly Internal _timeoutThis 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().Static Private Internal InternalReadonly commandReadonly commandAbstract dataconst coll = db.collection(...);
const cursor = coll.findAndRerank(...);
cursor.dataSource === coll; // true
CollectionFindAndRerankCursor overrides this method to return the dataSource typed exactly as Table or Collection respectively, instead of remaining a union of both.
Gets the current status of the cursor.
See CursorState for more information on the possible states, and how they may be transitioned between each other.
const cursor = collection.find({});
console.log(cursor.state); // 'idle'
await cursor.next();
console.log(cursor.state); // 'started'
cursor.close();
console.log(cursor.state); // 'closed'
CursorState
An async iterator that lazily iterates over all records in the cursor.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
breaks, iteration will stop earlyconst cursor = collection.find({ age: { $gt: 30 } });
// Iterate over all matching records
for await (const doc of cursor) {
console.log(doc);
if (doc.name === 'John') {
break; // Stop iteration early
}
}
// Cursor is now closed
console.log(cursor.state); // 'closed'
Protected _fetchInternal Protected _tmGets the 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 (consumed() + buffered()).
The number of raw records currently in the buffer.
const cursor = collection.find({});
console.log(cursor.buffered()); // 0
await cursor.next(); // Fetches a page of results
console.log(cursor.buffered()); // Number of records in buffer
AbstractCursor.consumed
Creates a new cursor with the exact same configuration as the current cursor.
The new cursor will be in the 'idle' state, regardless of the state of the current cursor, and will start its own iteration from the beginning, sending new queries to the server, even if the resultant data was already fetched by the original cursor.
A new cursor with the same configuration as the current cursor.
const cursor = collection.findAndRerank({ age: { $gt: 30 } })
.sort({ $hybrid: 'old man' });
// Clone the cursor before use
const clone1 = cursor.clone();
const clone2 = cursor.clone();
// Each cursor operates independently
const firstResult = await clone1.toArray();
const firstTwoRecords = await clone2.next();
// Original cursor is still usable
for await (const doc of cursor) {
console.log(doc);
}
Cloning a cursor is different from rewinding it. Cloning creates an independent new cursor with the same configuration as the original, while rewinding resets the current cursor to its initial state.
See FindAndRerankCursor.rewind for more information on rewinding.
FindAndRerankCursor.rewind
Closes the cursor. The cursor will be unusable after this method is called, or until AbstractCursor.rewind is called.
const cursor = collection.find({});
// Use the cursor
const doc = await cursor.next();
// Close the cursor when done
cursor.close();
// Attempting to use a closed cursor
await cursor.next(); // Throws CursorError
AbstractCursor.rewind - To reset a closed cursor to make it usable again
Consumes up to max records from the buffer, or all records if max is not provided.
⚠️Warning: This actually consumes the buffer; it doesn't just peek at it.
🚨Important: The records returned from this method are not affected by
cursor.map().
Optional max: numberThe optional max number of records to read from the buffer.
The records read from the buffer.
const cursor = collection.find({});
await cursor.next(); // Populates the buffer
// Consume up to 5 records from the buffer
const records = cursor.consumeBuffer(5);
console.log(records.length); // Number of records consumed (up to 5)
// Consume all remaining records
const remaining = cursor.consumeBuffer();
Gets the number of records that have been read by 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 (consumed() + buffered()).
The number of records that have been read from the cursor.
const cursor = collection.find({});
console.log(cursor.consumed()); // 0
await cursor.next();
console.log(cursor.consumed()); // 1
AbstractCursor.buffered
Fetches the next complete page of results from the server and returns it directly.
🚨Important:
findAndRerankoperations are not currently paginated, and as such, this construct mainly exists for consistency with FindCursor.fetchNextPage.Regardless, the page state mechanism is still full functional on the client side, in case it is available in the future.
See FindCursor.fetchNextPage for more information on fetching the next page.
A page object containing the results, the next page state, and optionally the sort vector.
Sets the filter for the cursor, overwriting any previous filter.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
filter.
A filter to select which records to return.
A new cursor with the new filter set.
await table.insertOne({ name: 'John', ... });
const cursor = table.findAndRerank({})
.sort({ $hybrid: 'big burly man' })
.filter({ name: 'John' });
// The cursor will only return records with the name 'John'
const { document: john } = await cursor.next();
john.name === 'John'; // true
Iterates over all records in the cursor, calling the provided consumer for each record.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
✏️Note: If you get an IDE error "Promise returned from forEach argument is ignored", you may simply ignore it. It is a known WebStorm bug.
false or Promise<false>, iteration will stop earlyThe consumer to call for each record. Return false to stop iteration.
A promise that resolves when iteration is complete.
const cursor = collection.find({ age: { $gt: 30 } });
// Process all records
await cursor.forEach((doc) => {
console.log(doc);
});
// Process records until a condition is met
await cursor.forEach(async (doc) => {
if (await isSpecial(doc)) {
return false;
}
});
Retrieves the vector used to perform the vector search, if applicable.
🚨Important: This will only return a non-null value if FindAndRerankCursor.includeSortVector is set.
The sort vector used to perform the vector search, or null if not applicable.
// Using $vector
const vector = new DataAPIVector([0.1, 0.2, 0.3]);
const cursor = collection.findAndRerank({})
.sort({ $hybrid: { $vector: vector, ... } })
.includeSortVector();
const sortVector = await cursor.getSortVector();
// Returns the same vector used in the sort
// Using $vectorize
const cursor = collection.findAndRerank({})
.sort({ $hybrid: { $vectorize: 'some text', ... } })
.includeSortVector();
const sortVector = await cursor.getSortVector();
// Returns the vector generated from the text
This method will:
null if includeSortVector was not set to truesort: { $hybrid: { $vector } } was usedsort: { $hybrid: { $vectorize } } was usedIf this method is called before the cursor has been executed, it will make an API request to fetch the sort vector and also populate the cursor's buffer.
If the cursor has already been executed, the sort vector will have already been cached, so no additional request will be made.
Tests if there is a next record in the cursor.
falseWhether or not there is a next record.
const cursor = collection.find({ name: 'John' });
// Check if there are any records
if (await cursor.hasNext()) {
const john = await cursor.next();
console.log(john);
}
// Use in a loop
while (await cursor.hasNext()) {
const record = await cursor.next();
console.log(record);
}
Sets the maximum number of records to consider from the underlying vector and lexical searches.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
limit.
Either a single number, or an object may be provided as a limit definition.
If a single number is specified, it applies to both the vector and lexical searches.
To set different limits for the vector and lexical searches, an object containing limits for each vector and lexical column must be provided.
{ $vector: number, $lexical: number }The hybrid limits for this cursor.
A new cursor with the new hybrid limits set.
await collection.insertMany([
{ name: 'John', age: 30, $vectorize: 'an elder man', $lexical: 'an elder man' },
{ name: 'Jane', age: 25, $vectorize: 'a young girl', $lexical: 'a young girl' },
]);
const cursor = collection.findAndRerank({})
.sort({ $hybrid: 'old man' })
.hybridLimits(1);
// The cursor will return only one record
const all = await cursor.toArray();
all.length === 1; // true
Determines whether the RerankedResult.scores is returned for each document.
If this is not set, then the scores will be an empty object for each document.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with new score settings.
Optional includeScores: booleanWhether the scores should be included in the result.
A new cursor with the new scores inclusion setting.
const cursor = table.findAndRerank({ name: 'John' })
.sort({ $hybrid: 'old man' })
.includeScores();
for await (const res of cursor) {
console.log(res.document);
console.log(res.scores);
}
Sets whether the sort vector should be fetched on the very first API call.
Note that this is a requirement
to use FindAndRerankCursor.getSortVector—it'll unconditionally return null if this is not set to true.
true.🚨Important: This method does NOT mutate the cursor; it returns a new cursor with the new sort vector settings.
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.findAndRerank({})
.sort({ $hybrid: 'old man' })
.includeSortVector();
// The cursor will return the sort vector used
// Here, it'll be the embedding for the vector created from the term 'old man'
const sortVector = await cursor.getSortVector();
sortVector; // DataAPIVector([...])
Sets the initial page state for the cursor, allowing you to resume fetching results from a specific point.
🚨Important:
findAndRerankoperations are not currently paginated, and as such, this construct mainly exists for consistency with FindCursor.initialPageState.Regardless, the page state mechanism is still full functional on the client side, in case it is available in the future.
See FindCursor.initialPageState for more information on, and warnings about, the initial page state.
Optional initialPageState: stringThe page state to resume from, or undefined to start from the beginning
A new cursor with the initial page state set
null initial page states are rejected to prevent the user from accidentally creating an infinite loop of fetching.
FindAndRerankCursor.fetchNextPage
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).
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
limit.
The limit for this cursor.
A new cursor with the new limit set.
await collection.insertMany([
{ name: 'John', age: 30, $vectorize: 'an elder man', $lexical: 'an elder man' },
{ name: 'Jane', age: 25, $vectorize: 'a young girl', $lexical: 'a young girl' },
]);
const cursor = collection.findAndRerank({})
.sort({ $hybrid: 'old man' })
.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).
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with the new mapping function applied.
⚠️Warning: You may NOT provide a projection after a mapping is already provided, to prevent potential type de-sync errors.
A new cursor with the new mapping set.
const cursor = table.findAndRerank({});
.sort({ $hybrid: 'old man' })
.map(res => res.document);
.map(row => row.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.
nullnull will be returnedThe next record, or null if there are no more records.
const cursor = collection.find({ name: 'John' });
// Get the first record
const john = await cursor.next();
// Get the next record (or null if no more records)
const nextRecord = await cursor.next();
// Exhaust the cursor
let doc;
while ((doc = await cursor.next()) !== null) {
console.log(doc);
}
Sets the projection for the cursor, overwriting any previous projection.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new projection.
🚨Important: To properly type this method, you should provide a type argument to specify the shape of the projected records.
⚠️Warning: You may NOT provide a projection after a mapping is already provided, to prevent potential type 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.findAndRerank({ name: 'John' }).sort(...);
// T is `RerankedResult<Partial<Schema>>` because the type is not specified
const rawProjected = cursor.project({ id: 0, name: 1 });
// T is `RerankedResult<{ name: string }>`
const projected = cursor.project<{ name: string }>({ id: 0, name: 1 });
// You can also chain instead of using intermediate variables
const fluentlyProjected = table
.findAndRerank({ name: 'John' })
.sort(...)
.project<{ name: string }>({ id: 0, name: 1 });
.map(res => res.document)
.map(row => row.name);
Specifies the document field to use for the reranking step. Often used with FindAndRerankCursor.rerankQuery.
Optional if you query through the $vectorize field instead of the $vector field; otherwise required.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
rerankOn.
Once the underlying vector and lexical searches complete, the reranker compares the rerankQuery text with each document's rerankOn field.
The reserved $lexical field is often used for this parameter, but you can specify any field that stores a string.
Any document lacking the field is excluded.
The document field to use for the reranking step.
A new cursor with the new rerankOn set.
const cursor = await coll.findAndRerank({})
.sort({ $hybrid: { $vector: vector([...]), $lexical: 'what is a dog?' } })
.rerankOn('$lexical')
.rerankQuery('I like dogs');
for await (const res of cursor) {
console.log(res.document);
}
Specifies the query text to use for the reranking step. Often used with FindAndRerankCursor.rerankOn.
Optional if you query through the $vectorize field instead of the $vector field; otherwise required.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
rerankQuery.
Once the underlying vector and lexical searches complete, the reranker compares the rerankQuery text with each document's rerankOn field.
The query text to use for the reranking step.
A new cursor with the new rerankQuery set.
const cursor = await coll.findAndRerank({})
.sort({ $hybrid: { $vector: vector([...]), $lexical: 'what is a dog?' } })
.rerankOn('$lexical')
.rerankQuery('I like dogs');
for await (const res of cursor) {
console.log(res.document);
}
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 the cursor.
const cursor = collection.find({}).sort({ name: 1 });
// Read some data
const first = await cursor.next();
// Rewind the cursor
cursor.rewind();
// Start again from the beginning
const firstAgain = await cursor.next();
// first and firstAgain are the same record
Rewinding a cursor is different from cloning it. Cloning creates an independent new cursor with the same state and configuration as the original, while rewinding resets the current cursor to its initial state.
See AbstractCursor.clone for more information on cloning.
AbstractCursor.clone
Sets the sort criteria for prioritizing records.
🚨Important: This option must be set, and must contain a
$hybridkey.
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with a new
sort.
$hybrid keyThe $hybrid key is a special key that specifies the query(s) to use for the underlying vector and lexical searches.
If your collection doesn't have vectorize enabled, you must pass separate query items for $vector and $lexical:
{ $hybrid: { $vector: vector([...]), $lexical: 'A house on a hill' } }If your collection has vectorize enabled, you can query through the $vectorize field instead of the $vector field. You can also use a single search string for both the $vectorize and $lexical queries.
{ $hybrid: { $vectorize: 'A tree in the woods', $lexical: 'A house on a hill' } }{ $hybrid: 'A tree in the woods' }The hybrid sort criteria to use for prioritizing records.
A new cursor with the new sort set.
await collection.insertMany([
{ name: 'John', age: 30, $vectorize: 'an elder man', $lexical: 'an elder man' },
{ name: 'Jane', age: 25, $vectorize: 'a young girl', $lexical: 'a young girl' },
]);
const cursor = collection.findAndRerank({})
.sort({ $hybrid: 'old man' });
// The cursor will return records sorted by the hybrid query
const { document: oldest } = await cursor.next();
oldest.nane === 'John'; // true
Returns an array of all matching records in the cursor.
⚠️Warning: The user should ensure that there is enough memory to store all records in the cursor.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
An array of all records in the cursor.
const cursor = collection.find({ department: 'Engineering' });
// Get all matching records as an array
const engineers = await cursor.toArray();
console.log(`Found ${engineers.length} engineers`);
// For a large result set, consider using lazy iteration instead
for await (const doc of cursor.rewind()) {
// Process one document at a time
}
Overview (preview)
A lazy iterator over the results of some generic
findAndRerankoperation on the Data API.Typing
In full, the cursor is typed as
FindAndRerankCursor<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 FindAndRerankCursor.map method.Options
Options may be set either through the
findAndRerank({}, 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
CollectionFindAndRerankCursor