Internal
Should not be instantiated directly.
Optional
options: FindOptionsPrivate
_bufferPrivate
_filterPrivate
Readonly
_httpPrivate
Readonly
_keyspacePrivate
Optional
_mappingPrivate
Optional
_nextPrivate
Readonly
_optionsPrivate
Optional
_sortPrivate
_stateWhether the cursor is closed, whether it be manually, or because the cursor is exhausted.
Whether or not the cursor is closed.
The keyspace of the collection that's being iterated over.
The keyspace of the collection that's being iterated over.
The keyspace of the collection that's being iterated over.
This is now a deprecated alias for the strictly equivalent FindCursor.keyspace, and will be removed in an upcoming major version.
https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5
An async iterator that lazily iterates over all documents 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);
}
Private
_assertPrivate
_getPrivate
_nextReturns a new, uninitialized cursor with the same filter and options set on this cursor. No state is shared between the two cursors; only the configuration.
Like mongo, mapping functions are not cloned.
A behavioral clone of this cursor.
const cursor = collection.find({ name: 'John' });
Closes the cursor. The cursor will be unusable after this method is called, or until FindCursor.rewind is called.
Sets the filter for the cursor, overwriting any previous filter. Note that this filter is weakly typed. Prefer to pass in a filter through the constructor instead, if strongly typed filters are desired.
NB. This method acts on the original documents, before any mapping.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
The cursor.
StrictFilter
Iterates over all documents in the cursor, calling the provided consumer for each document.
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 document.
A promise that resolves when iteration is complete.
for await (const doc of cursor) { ... }
syntax instead.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.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
Whether similarity scores should be included.
The cursor.
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
.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
Whether the sort vector should be fetched on the first API call
The cursor.
Sets the maximum number of documents to return.
If limit == 0
, there will be no limit on the number of documents returned.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
The limit for this cursor.
The cursor.
Map all documents using the provided mapping function. Previous mapping functions will be composed with the new mapping function (new ∘ old).
NB. Unlike Mongo, it is okay to map a cursor to null
.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
The cursor.
Fetches the next document from the cursor. Returns null
if there are no more documents to fetch.
If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return null
.
The next document, or null
if there are no more documents.
Sets the projection for the cursor, overwriting any previous projection.
NB. This method acts on the original documents, before any mapping.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
To properly type this method, you should provide a type argument for T
to specify the shape of the projected
documents, with mapping applied.
Specifies which fields should be included/excluded in the returned documents.
The cursor.
const cursor = collection.find({ name: 'John' });
// T is `any` 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 = collection
.find({ name: 'John' })
.project<{ name: string }>({ _id: 0, name: 1 });
// It's important to keep mapping in mind
const mapProjected = collection
.find({ name: 'John' })
.map(doc => doc.name);
.project<string>({ _id: 0, name: 1 });
StrictProjection
Pulls up to max
documents from the buffer, or all documents 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 documents to read from the buffer. If not provided, all documents will be read.
The documents read from the buffer.
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 documents. Note that this sort is weakly typed. Prefer to pass in a sort through the constructor instead, if strongly typed sorts are desired.
NB. This method acts on the original documents, before any mapping.
This method mutates the cursor, and the cursor MUST be uninitialized when calling this method.
The sort order to prioritize which documents are returned.
The cursor.
StrictSort
Returns an array of all matching documents in the cursor. The user should ensure that there is enough memory to store all documents 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 documents in the cursor.
Lazily iterates over the document results of a query.
Shouldn't be directly instantiated, but rather created via Collection.find.
Typed as
FindCursor<T, TRaw>
whereT
is the type of the mapped documents andTRaw
is the type of the raw documents before any mapping. If no mapping function is provided,T
andTRaw
will be the same type. Mapping is done using the FindCursor.map method.Example