Class CollectionFindCursor<T, TRaw>

Overview

A lazy iterator over the results of a find operation on a Collection.

Shouldn't be directly instantiated, but rather spawned via Collection.find.

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>, where

  • T is the type of the mapped records, and
  • TRaw is the type of the raw records before any mapping.

If no mapping function is provided, T and TRaw will 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

interface Person {
  firstName: string,
  lastName: string,
  age: number,
}

const collection = db.collection<Person>('people');
const cursor1: Cursor<Person> = collection.find({ firstName: 'John' });

// Lazily iterate all documents matching the filter
for await (const doc of cursor1) {
  console.log(doc);
}

// Rewind the cursor to be able to iterate again
cursor1.rewind();

// Get all documents matching the filter as an array
const docs = await cursor1.toArray();

// Immutably set options & map as needed (changing options returns a new, uninitialized cursor)
const cursor2: Cursor<string> = cursor
  .project<Omit<Person, 'age'>>({ age: 0 })
  .map(doc => doc.firstName + ' ' + doc.lastName);

// Get next document from cursor
const doc = await cursor2.next();

See

  • AbstractCursor
  • FindCursor

Type Parameters

Hierarchy (view full)

Constructors

constructor

Properties

_filter _mapping? _nextPageState _options _parent _serdes _state bufferedCount includeSimilarity map project readBufferedDocuments

Accessors

dataSource state

Methods

[$CustomInspect] [asyncIterator] _next _nextPage _tm buffered clone close consumeBuffer consumed filter forEach getSortVector hasNext includeSortVector limit next rewind skip sort toArray

Constructors

constructor

Properties

Readonly Internal _filter

_filter: SerializedFilter

Optional Readonly Internal _mapping

_mapping?: ((doc) => T)

Type declaration

    • (doc): T

    • Parameters

      • doc: any

      Returns T

Protected Internal _nextPageState

_nextPageState: QueryState<string> = ...

Readonly Internal _options

_options: GenericFindOptions

Readonly Internal _parent

_parent: Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>

Readonly Internal _serdes

_serdes: SerDes<any, any>

Protected Internal _state

_state: CursorState = 'idle'

bufferedCount

bufferedCount: "ERROR: `.bufferedCount()` has been renamed to be simply `.buffered()`"

This temporary error-ing property exists for migration convenience, and will be removed in a future version.

Deprecated

  • .bufferedCount() has been renamed to simply be .buffered().

includeSimilarity

includeSimilarity: ((includeSimilarity?) => CollectionFindCursor<WithSim<TRaw>, WithSim<TRaw>>)

Type declaration

map

map: (<R>(map) => CollectionFindCursor<R, TRaw>)

Type declaration

project

project: (<RRaw>(projection) => CollectionFindCursor<RRaw, RRaw>)

Type declaration

readBufferedDocuments

readBufferedDocuments: "ERROR: `.readBufferedDocuments()` has been renamed to be `.consumeBuffer()`"

This temporary error-ing property exists for migration convenience, and will be removed in a future version.

Deprecated

  • .readBufferedDocuments() has been renamed to be .consumeBuffer().

Accessors

dataSource

state

Methods

[$CustomInspect]

[asyncIterator]

  • [asyncIterator](): AsyncGenerator<T, void, void>

  • 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.

    Returns AsyncGenerator<T, void, void>

    Example

    for await (const doc of cursor) {
      console.log(doc);
    }

Protected _next

Protected _nextPage

Protected _tm

buffered

clone

close

consumeBuffer

  • consumeBuffer(max?): TRaw[]

  • 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.

    Parameters

    • Optional max: number

      The maximum number of records to read from the buffer. If not provided, all records will be read.

    Returns TRaw[]

    The records read from the buffer.

consumed

filter

  • filter(filter): this
  • Overview

    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.

    Parameters

    Returns this

    A new cursor with the new filter set.

    Example

    await collection.insertOne({ name: 'John', ... });

    const cursor = collection.find({})
      .filter({ name: 'John' });

    // The cursor will only return records with the name 'John'
    const john = await cursor.next();
    john.name === 'John'; // true

forEach

  • forEach(consumer): Promise<void>

  • 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.

    Parameters

    • consumer: ((doc) => boolean | Promise<boolean>) | ((doc) => void | Promise<void>)

      The consumer to call for each record.

    Returns Promise<void>

    A promise that resolves when iteration is complete.

    Remarks

    If you get an IDE error "Promise returned from forEach argument is ignored", it is a known WebStorm bug.

getSortVector

  • getSortVector(): Promise<null | DataAPIVector>
  • Overview

    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.

    Returns Promise<null | DataAPIVector>

    The sort vector, or null if none was used (or if includeSortVector !== true).

hasNext

  • hasNext(): Promise<boolean>

  • Tests if there is a next record in the cursor.

    If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return false.

    Returns Promise<boolean>

    Whether or not there is a next record.

includeSortVector

  • includeSortVector(includeSortVector?): this
  • Overview

    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 is only applicable when using vector search, and will be ignored if the cursor is not using vector search.
    • See FindCursor.getSortVector to see exactly what is returned when this is set to true.

    Note: this method does NOT mutate the cursor; it simply returns a new, uninitialized cursor with the given new setting.

    Parameters

    • Optional includeSortVector: boolean

      Whether the sort vector should be fetched on the first API call

    Returns this

    A new cursor with the new sort vector inclusion setting.

    Example

    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([...])

limit

  • limit(limit): this
  • Overview

    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.

    Parameters

    • limit: number

      The limit for this cursor.

    Returns this

    A new cursor with the new limit set.

    Example

    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

next

  • next(): Promise<null | T>

  • 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.

    Returns Promise<null | T>

    The next record, or null if there are no more records.

rewind

  • rewind(): void

  • 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.

    Returns void

skip

  • skip(skip): this
  • Overview

    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.

    Parameters

    • skip: number

      The skip for the cursor query.

    Returns this

    A new cursor with the new skip set.

    Example

    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

sort

  • sort(sort): this
  • Overview

    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.

    Parameters

    • sort: Sort

      The sort order to prioritize which records are returned.

    Returns this

    A new cursor with the new sort set.

    Example

    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

toArray

  • toArray(): Promise<T[]>

  • 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.

    Returns Promise<T[]>

    An array of all records in the cursor.

Settings

Member Visibility

Theme

On This Page

constructor_filter_mapping_nextPageState_options_parent_serdes_statebufferedCountincludeSimilaritymapprojectreadBufferedDocumentsdataSourcestate[$CustomInspect][asyncIterator]_next_nextPage_tmbufferedclonecloseconsumeBufferconsumedfilterforEachgetSortVectorhasNextincludeSortVectorlimitnextrewindskipsorttoArray