SqliteStatement Class

Executes SQLite SQL statements.

A statement must be prepared before it can be executed, and it must be released when no longer needed. See IModelDb.withPreparedSqliteStatement or ECDb.withPreparedSqliteStatement 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 calling SqliteStatement.bindValue or SqliteStatement.bindValues.

Once prepared (and parameters are bound, if any), the statement is executed by calling SqliteStatement.step. In case of an SQL SELECT statement, the current row can be retrieved with SqliteStatement.getRow as a whole, or with SqliteStatement.getValue when individual values are needed. Alternatively, query results of an SQL 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.

Implements

Methods

Name Description
constructor(_sql: string): SqliteStatement    
[iterator](): IterableIterator<any> The iterator that will step through the results of this statement.  
bindBlob(parameter: BindParameter, blob: Uint8Array): void Bind a blob parameter  
bindDouble(parameter: BindParameter, val: number): void Bind a double parameter  
bindGuid(parameter: BindParameter, guid: string): void Bind a Guid parameter  
bindId(parameter: BindParameter, id: string): void Bind an Id64String parameter as a 64-bit integer  
bindInteger(parameter: BindParameter, val: number): void Bind an integer parameter  
bindString(parameter: BindParameter, val: string): void Bind a string parameter  
bindValue(parameter: BindParameter, value: any): void Binds a value to the specified SQL 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.  
getColumnCount(): number Get the query result's column count (only for SQL SELECT statements).  
getRow(): any Get the current row.  
getValue(columnIx: number): SqliteValue Get the value for the column at the given index in the query result.  
getValueBlob(colIndex: number): Uint8Array Get a value as a blob  
getValueDouble(colIndex: number): number Get a value as a double  
getValueGuid(colIndex: number): string Get a value as a Guid  
getValueId(colIndex: number): string Get a value as an Id  
getValueInteger(colIndex: number): number Get a value as a integer  
getValueString(colIndex: number): string Get a value as a string  
next(): IteratorResult<any, any> Calls step when called as an iterator.  
prepare(db: DgnDb | ECDb | SQLiteDb): void Prepare this statement prior to first use.  
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.  

Properties

Name Type Description
isPrepared Accessor ReadOnly boolean Check if this statement has been prepared successfully or not  
isReadonly Accessor ReadOnly boolean Indicates whether the prepared statement makes no *direct changes to the content of the file  
sql Accessor ReadOnly string    
stmt Accessor ReadOnly undefined | SqliteStatement    

Defined in

Last Updated: 11 June, 2024