@itwin/core-backend
Version:
iTwin.js backend components
104 lines • 4.33 kB
TypeScript
/** @packageDocumentation
* @module ECSQL
*/
import { ECSqlReaderBase, QueryBinder, QueryOptions, QueryPropertyMetaData, QueryRowProxy } from "@itwin/core-common";
import { ECSqlRowExecutor } from "./ECSqlRowExecutor";
/** @beta */
export type SynchronousQueryOptions = Omit<QueryOptions, "suppressLogErrors" | "includeMetaData" | "limit" | "priority" | "restartToken" | "delay" | "usePrimaryConn" | "quota">;
/**
* Execute ECSQL statements synchronously and read the results one row at a time.
*
* This is the synchronous counterpart of [[ECSqlReader]] from `@itwin/core-common`.
* It uses [[ECSqlRowExecutor]] directly — each call to [[step]] fetches exactly one row
* with no internal caching, paging, or offset tracking.
*
* The query results are returned one row at a time. The format of the row is dictated by the
* `rowFormat` specified in the `options` parameter of the constructed ECSqlSyncReader object.
* Defaults to [[QueryRowFormat.UseECSqlPropertyIndexes]] when no `rowFormat` is defined.
*
* There are three primary ways to interact with and read the results:
* - Iterate using ECSqlSyncReader as a synchronous iterator.
* - Step manually using [[ECSqlSyncReader.step]].
* - Capture all results at once using [[ECSqlSyncReader.toArray]].
*
* @note When iterating over the results, the current row is a [[QueryRowProxy]] object.
* To get the row as a basic JavaScript object, call [[QueryRowProxy.toRow]] on it.
* @beta
*/
export declare class ECSqlSyncReader extends ECSqlReaderBase implements IterableIterator<QueryRowProxy> {
private _executor;
readonly query: string;
private _currentRow;
private _options;
/** Cached native row-adaptor options — built once and reused for every row. */
private _cachedRowOptions;
/**
* @internal
*/
constructor(_executor: ECSqlRowExecutor, query: string, param?: QueryBinder, options?: SynchronousQueryOptions);
/**
* @internal
*/
protected getRowInternal(): any[];
/**
* Reads a single row from the executor. Returns the row data or `undefined` when the
* result set is exhausted.
*
* Uses the fast-path `stepNextRow` method on the executor, which calls `stmt.step()`
* and `stmt.toRow()` directly — no intermediate request/response objects are allocated per row.
* @internal
*/
private readRow;
/**
* Steps the cursor with retry logic for transient busy/interrupt conditions.
* Returns the row data array, or `undefined` when the result set is exhausted.
* @internal
*/
private stepWithRetry;
/**
* Get the metadata for each column in the query result.
*
* If metadata has not been retrieved yet, fetches it directly from the prepared
* statement. If a step has not yet occurred, executes a single step to ensure
* the statement cursor is positioned, preserving the row for the next [[step]] call.
*
* @returns An array of [[QueryPropertyMetaData]].
* @beta
*/
getMetaData(): QueryPropertyMetaData[];
/**
* Step to the next row of the query result.
*
* Each call executes exactly one step on the underlying statement — there is no
* internal row caching or offset tracking.
*
* @returns `true` if a row can be read from `current`.<br/>
* `false` if there are no more rows; i.e., all rows have been stepped through already.
* @beta
*/
step(): boolean;
/**
* Get all remaining rows from the query result.
*
* @returns An array of all remaining rows from the query result.
* @beta
*/
toArray(): any[];
/**
* Accessor for using ECSqlSyncReader as a synchronous iterator.
*
* @returns A synchronous iterator over the rows returned by the executed ECSQL query.
* @beta
*/
[Symbol.iterator](): IterableIterator<QueryRowProxy>;
/**
* Calls step when called as an iterator.
*
* Returns the row alongside a `done` boolean to indicate if there are any more rows for an iterator to step to.
*
* @returns An object with the keys: `value` which contains the row and `done` which contains a boolean.
* @beta
*/
next(): IteratorResult<QueryRowProxy, any>;
}
//# sourceMappingURL=ECSqlSyncReader.d.ts.map