ECSqlStatement Class
Executes ECSQL statements.
A statement must be prepared before it can be executed, and it must be released when no longer needed. See IModelDb.withPreparedStatement or ECDb.withPreparedStatement for a convenient and reliable way to prepare, execute, and then release a statement.
A statement may contain parameters that must be filled in before use by the bind methods.
Once prepared (and parameters are bound, if any), the statement is executed by calling ECSqlStatement.step.
In case of an ECSQL SELECT statement, the current row can be retrieved with ECSqlStatement.getRow as
a whole, or with ECSqlStatement.getValue when individual values are needed.
Alternatively, query results of an ECSQL SELECT statement can be stepped through by using
standard iteration syntax, such as for of
.
Preparing a statement can be time-consuming. The best way to reduce the effect of this overhead is to cache and reuse prepared statements. A cached prepared statement may be used in different places in an app, as long as the statement is general enough. The key to making this strategy work is to phrase a statement in a general way and use placeholders to represent parameters that will vary on each use.
See also
- Executing ECSQL provides more background on ECSQL and an introduction on how to execute ECSQL with the iTwin.js API.
- Code Examples illustrate the use of the iTwin.js API for executing and working with ECSQL
Implements
- IterableIterator<any>
- IDisposable
Methods
Name | Description | |
---|---|---|
constructor(): ECSqlStatement | ||
[iterator](): IterableIterator<any> | The iterator that will step through the results of this statement. | |
bindArray(parameter: string | number, val: any[]): void | Binds an array value to the specified ECSQL parameter. | |
bindBlob(parameter: string | number, blob: string | Uint8Array | ArrayBuffer | SharedArrayBuffer): void | Binds a BLOB value to the specified ECSQL parameter. | |
bindBoolean(parameter: string | number, val: boolean): void | Binds a boolean value to the specified ECSQL parameter. | |
bindDateTime(parameter: string | number, isoDateTimeString: string): void | Binds a DateTime value to the specified ECSQL parameter. | |
bindDouble(parameter: string | number, val: number): void | Binds a double value to the specified ECSQL parameter. | |
bindGuid(parameter: string | number, val: string): void | Binds an GUID value to the specified ECSQL parameter. | |
bindId(parameter: string | number, val: string): void | Binds an Id value to the specified ECSQL parameter. | |
bindIdSet(parameter: string | number, val: string[]): void | ||
bindInteger(parameter: string | number, val: string | number): void | Binds an integer value to the specified ECSQL parameter. | |
bindNavigation(parameter: string | number, val: NavigationBindingValue): void | Binds a navigation property value to the specified ECSQL parameter. | |
bindNull(parameter: string | number): void | Binds null to the specified ECSQL parameter. | |
bindPoint2d(parameter: string | number, val: Readonly<WritableXAndY>): void | Binds an Point2d value to the specified ECSQL parameter. | |
bindPoint3d(parameter: string | number, val: Readonly<WritableXYAndZ>): void | Binds an Point3d value to the specified ECSQL parameter. | |
bindRange3d(parameter: string | number, val: Readonly<WritableLowAndHighXYZ>): void | Binds a Range3d as a blob to the specified ECSQL parameter | |
bindString(parameter: string | number, val: string): void | Binds an string to the specified ECSQL parameter. | |
bindStruct(parameter: string | number, val: object): void | Binds a struct property value to the specified ECSQL parameter. | |
bindValue(parameter: string | number, val: any): void | Binds the specified value to the specified ECSQL parameter. | |
bindValues(values: object | any[]): void | Bind values to all parameters in the statement. | |
clearBindings(): void | Clear any bindings that were previously set on this statement. | |
dispose(): void | Call this function when finished with this statement. | |
getBinder(parameter: string | number): ECSqlBinder | Gets a binder to bind a value for an ECSQL parameter | |
getColumnCount(): number | Get the query result's column count (only for ECSQL SELECT statements). | |
getRow(): any | Get the current row. | |
getValue(columnIx: number): ECSqlValue | Get the value for the column at the given index in the query result. | |
next(): IteratorResult<any, any> | Calls step when called as an iterator. | |
reset(): void | Reset this statement so that the next call to step will return the first row, if any. | |
step(): DbResult | Step this statement to the next row. | |
stepForInsert(): ECSqlInsertResult | Step this INSERT statement and returns status and the ECInstanceId of the newly |
Properties
Name | Type | Description | |
---|---|---|---|
isPrepared Accessor ReadOnly | boolean | Check if this statement has been prepared successfully or not | |
sql Accessor ReadOnly | string |
Defined in
- backend/src/ECSqlStatement.ts Line 54
Last Updated: 20 June, 2023