Cursor

Cursor provides unidirectional (optionally cached/bidirectional) row-by-row access to a query result, instead of buffering every row into QueryResult.rows at once. It's returned in QueryResult.cursor when a query is executed with cursor: true. See Cursors & Streaming for the full usage guide.

Cursor extends an AsyncEventEmitter and emits move, fetch, eof, reset, close and error.

Constructor

new Cursor(connection: SqbConnection, fields: FieldInfoMap, adapterCursor: Adapter.Cursor, request: QueryRequest)

You don't construct a Cursor yourself — instances are returned via QueryResult.cursor when a query is run with cursor: true.

Properties

Property	Type	Description
connection	SqbConnection	The connection this cursor was created on.
fields	FieldInfoMap	Metadata describing the result's columns.
row	any	The current row.
rowNum	number	The current row number (0 before the first row).
isBof	boolean	true before the first row has been fetched.
isEof	boolean	true once you've stepped past the last row of an exhausted cursor.
isClosed	boolean	true once the cursor has been closed.
fetchedRows	number	Total rows fetched from the database so far.

Methods

cached()

cached(): void

Enables an internal cache so the cursor can move backward and be re-read. Must be called before any row has been fetched — throws otherwise.

close()

close(): Promise<void>

Closes the underlying adapter cursor and emits close.

fetchAll()

fetchAll(): Promise<number>

Requires caching to be enabled. Fetches every remaining row into the cache and returns the number of rows fetched; after this you can safely close() the cursor and keep reading from the in-memory cache.

moveTo()

moveTo(rowNum: number): Promise<ObjectRow>

Moves to an absolute row number and returns that row. Moving to an earlier row requires caching.

cursor.cached();
await cursor.seek(10);
const row = await cursor.moveTo(3);

next()

next(): Promise<ObjectRow>

Moves forward by one row and returns it, or resolves to undefined once the cursor is exhausted (closing it automatically).

let row;
while ((row = await cursor.next())) {
  console.log(row);
}

prev()

prev(): Promise<ObjectRow>

Moves back by one row and returns it. Requires caching to be enabled.

reset()

reset(): void

Rewinds the cursor to before the first row and emits reset. Requires caching to be enabled.

seek()

seek(step: number): Promise<ObjectRow>

Moves the cursor forward (or backward, with caching enabled) by step rows and returns the resulting row.

toStream()

toStream(options?: CursorStreamOptions): CursorStream

Wraps the cursor in a CursorStream for use as a Node.js Readable.