@itwin/core-common
Version:
iTwin.js components common to frontend and backend
231 lines • 8.22 kB
TypeScript
import { DbQueryRequest, DbQueryResponse, DbRequestExecutor, QueryBinder, QueryOptions, QueryPropertyMetaData } from "./ConcurrentQuery";
/** @public */
export declare class PropertyMetaDataMap implements Iterable<QueryPropertyMetaData> {
readonly properties: QueryPropertyMetaData[];
private _byPropName;
private _byJsonName;
private _byNoCase;
constructor(properties: QueryPropertyMetaData[]);
get length(): number;
[Symbol.iterator](): Iterator<QueryPropertyMetaData, any, undefined>;
findByName(name: string): QueryPropertyMetaData | undefined;
findByJsonName(name: string): QueryPropertyMetaData | undefined;
findByNoCase(name: string): QueryPropertyMetaData | undefined;
}
/**
* The format for rows returned by [[ECSqlReader]].
* @public
*/
export type QueryValueType = any;
/**
* Methods and ways of accessing values from rows returned by [[ECSqlReader]].
* @public
*/
export interface QueryRowProxy {
/**
* Get the current row as a JavaScript `object`.
*
* @returns The current row as a JavaScript `object`.
*/
toRow(): any;
/**
* Get all remaining rows from the query result.
* If called on the current row ([[ECSqlReader.current]]), only that row is returned.
*
* @returns All remaining rows from the query result.
*/
toArray(): QueryValueType[];
/**
* Get the metadata for each column in the query result.
*
* @returns The metadata for each column in the query result.
*/
getMetaData(): QueryPropertyMetaData[];
/**
* Access a property using its name.
*
* @returns The value from the row whose key (ECSQL column name) is `propertyName`.
*
* @example
* The following lines will all return the same result:
* ```ts
* reader.current.ECInstanceId;
* reader.current.ecinstanceid;
* reader.current.["ECInstanceId"];
* ```
*/
[propertyName: string]: QueryValueType;
/**
* Access a property using its index.
* The index is relative to the order of the columns returned by the query that produced the row.
*
* @returns The value from the column at `propertyIndex`.
*
* @example reader.current[0]
*/
[propertyIndex: number]: QueryValueType;
}
/**
* Performance-related statistics for [[ECSqlReader]].
* @public
*/
export interface QueryStats {
/** Time spent running the query; not including time spent queued. Time is in microseconds */
backendCpuTime: number;
/** Total time it took the backend to run the query. Time is in milliseconds. */
backendTotalTime: number;
/** Estimated memory used for the query. */
backendMemUsed: number;
/** Total number of rows returned by the backend. */
backendRowsReturned: number;
/** The total round trip time from the client's perspective. Time is in milliseconds. */
totalTime: number;
/** The number of retries attempted to execute the query. */
retryCount: number;
/** Total time in millisecond to prepare ECSQL or grabing it from cache and binding parameters */
prepareTime: number;
}
/**
* Execute ECSQL statements and read the results.
*
* The query results are returned one row at a time. The format of the row is dictated by the
* [[QueryOptions.rowFormat]] specified in the `options` parameter of the constructed ECSqlReader object. Defaults to
* [[QueryRowFormat.UseECSqlPropertyIndexes]] when no `rowFormat` is defined.
*
* There are three primary ways to interact with and read the results:
* - Stream them using ECSqlReader as an asynchronous iterator.
* - Iterator over them manually using [[ECSqlReader.step]].
* - Capture all of the results at once in an array using [[QueryRowProxy.toArray]].
*
* @see
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [ECSQL Row Formats]($docs/learning/ECSQLRowFormat) for more details on how rows are formatted.
* - [ECSQL Code Examples]($docs/learning/ECSQLCodeExamples#iterating-over-query-results) for examples of each
* of the above ways of interacting with ECSqlReader.
*
* @note When iterating over the results, the current row will be a [[QueryRowProxy]] object. To get the row as a basic
* JavaScript object, call [[QueryRowProxy.toRow]] on it.
* @public
*/
export declare class ECSqlReader implements AsyncIterableIterator<QueryRowProxy> {
private _executor;
readonly query: string;
private static readonly _maxRetryCount;
private _localRows;
private _localOffset;
private _globalOffset;
private _globalCount;
private _done;
private _globalDone;
private _props;
private _param;
private _lockArgs;
private _stats;
private _options;
private _rowProxy;
/**
* @internal
*/
constructor(_executor: DbRequestExecutor<DbQueryRequest, DbQueryResponse>, query: string, param?: QueryBinder, options?: QueryOptions);
private static replaceBase64WithUint8Array;
setParams(param: QueryBinder): void;
reset(options?: QueryOptions): void;
/**
* Get the current row from the query result. The current row is the one most recently stepped-to
* (by step() or during iteration).
*
* Each value from the row can be accessed by index or by name.
*
* The format of the row is dictated by the [[QueryOptions.rowFormat]] specified in the `options` parameter of the
* constructed ECSqlReader object.
*
* @see
* - [[QueryRowFormat]]
* - [ECSQL Row Formats]($docs/learning/ECSQLRowFormat)
*
* @note The current row is be a [[QueryRowProxy]] object. To get the row as a basic JavaScript object, call
* [[QueryRowProxy.toRow]] on it.
*
* @example
* ```ts
* const reader = iModel.createQueryReader("SELECT ECInstanceId FROM bis.Element");
* while (await reader.step()) {
* // Both lines below print the same value
* console.log(reader.current[0]);
* console.log(reader.current.ecinstanceid);
* }
* ```
*
* @return The current row as a [[QueryRowProxy]].
*/
get current(): QueryRowProxy;
/**
* Clear all bindings.
*/
resetBindings(): void;
/**
* Returns if there are more rows available.
*
* @returns `true` if all rows have been stepped through already.<br/>
* `false` if there are any yet unaccessed rows.
*/
get done(): boolean;
/**
* @internal
*/
getRowInternal(): any[];
/**
* Get performance-related statistics for the current query.
*/
get stats(): QueryStats;
/**
*
*/
private readRows;
/**
* @internal
*/
protected runWithRetry(request: DbQueryRequest): Promise<DbQueryResponse>;
/**
* @internal
*/
formatCurrentRow(onlyReturnObject?: boolean): any[] | object;
/**
* Get the metadata for each column in the query result.
*
* @returns An array of [[QueryPropertyMetaData]].
*/
getMetaData(): Promise<QueryPropertyMetaData[]>;
/**
*
*/
private fetchRows;
/**
* Step to the next row of the query result.
*
* @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.
*/
step(): Promise<boolean>;
/**
* Get all remaining rows from the query result.
*
* @returns An array of all remaining rows from the query result.
*/
toArray(): Promise<any[]>;
/**
* Accessor for using ECSqlReader as an asynchronous iterator.
*
* @returns An asynchronous iterator over the rows returned by the executed ECSQL query.
*/
[Symbol.asyncIterator](): AsyncIterableIterator<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.
*/
next(): Promise<IteratorResult<QueryRowProxy, any>>;
}
//# sourceMappingURL=ECSqlReader.d.ts.map