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  
bindBoolean(parameter: BindParameter, val: boolean): void Bind a boolean 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  
bindNull(parameter: BindParameter): void Bind null to a 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.  
getColumnBytes(colIndex: number): number Get a size in bytes of a blob or text column  
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  
getValueBlobMaybe(colIndex: number): undefined | Uint8Array Get the value as a blob, or undefined if it is null.  
getValueBoolean(colIndex: number): boolean Get the value as a boolean.  
getValueDate(colIndex: number): Date Get the value of a julianday column as a JavaScript Date. Beta  
getValueDouble(colIndex: number): number Get a value as a double  
getValueDoubleMaybe(colIndex: number): undefined | number Get the value as an double, or undefined if it is null.  
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  
getValueIntegerMaybe(colIndex: number): undefined | number Get the value as an integer, or undefined if it is null.  
getValueString(colIndex: number): string Get a value as a string  
getValueStringMaybe(colIndex: number): undefined | string Get the value as a string, or undefined if it is null.  
isValueNull(colIndex: number): boolean Determine whether the value of the specified column is null  
maybeBindBlob(parameter: BindParameter, val?: Uint8Array): void Bind a blob parameter if it is defined.  
maybeBindBoolean(parameter: BindParameter, val?: boolean): void Bind a boolean parameter if it is defined.  
maybeBindDouble(parameter: BindParameter, val?: number): void Bind a double parameter if it is defined.  
maybeBindInteger(parameter: BindParameter, val?: number): void Bind an integer parameter if it is defined.  
maybeBindString(parameter: BindParameter, val?: string): void Bind a string parameter if it is defined.  
next(): IteratorResult<any, any> Calls step when called as an iterator.  
nextRow(): boolean Call step on this statement and determine whether a new row is available.  
prepare(db: AnyDb, logErrors: boolean = true): 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 SqliteStatement    

Defined in

Last Updated: 20 June, 2023