Internal Should not be instantiated directly.
Readonly Internal _filterOptional Readonly Internal _mappingProtected Internal _nextReadonly Internal _optionsReadonly Internal _parentReadonly Internal _serdesProtected 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().const 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.
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 _nextInternal Protected _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 FindAndRerankCursor.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.findAndRerank({})
.sort({ $hybrid: 'big burly man' })
.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: { $hybrid: { $vector } } was used, getSortVector() will simply regurgitate that same $vector.
If sort: { $hybrid: { $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 the maximum number of records to consider from the underlying vector and lexical searches.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new limit set.
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.find({})
.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.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new setting.
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.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.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 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, $vectorize: 'an elder man', $lexical: 'an elder man' },
{ name: 'Jane', age: 25, $vectorize: 'a young girl', $lexical: 'a young girl' },
]);
const cursor = collection.find({})
.sort({ $hybrid: 'old man' })
.limit(1);
// The cursor will return only one record
const all = await cursor.toArray();
all.length === 1; // 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.
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.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new setting.
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.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new setting.
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 this cursor.
Sets the sort criteria for prioritizing records.
This option must be set, and must contain a $hybrid key.
Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new sort set.
$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.find({})
.sort({ $hybrid: 'old man' });
// The cursor will return records sorted by the hybrid query
const oldest = await cursor.next();
oldest.nane === 'John'; // 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 (preview)
A lazy iterator over the results of some generic
findAndRerankoperation on the Data API.Shouldn't be directly instantiated, but rather spawned via Collection.findAndRerank.
Typing
For most intents and purposes, you may treat the cursor as if it is typed simply as
Cursor<T>.If you're using a projection, it is heavily recommended to provide an explicit type representing the type of the document after projection.
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 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