API Reference › core-backend › ECSQL › ECSqlStatement

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

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

Last Updated: 16 April, 2024