Asynchronous ECSQL Queries with createQueryReader

Use createQueryReader for asynchronous ECSQL queries on an IModelDb, ECDb, or frontend IModelConnection. In these examples, iModel can be any of those objects.

createQueryReader returns an ECSqlReader immediately. Query execution starts when you consume the reader with asynchronous iteration, step(), or toArray(). The reader fetches and buffers batches of rows.

For synchronous backend execution, use withQueryReader. It supplies a callback-scoped reader that steps one row at a time. See Choosing a query reader for differences in execution, connection selection, buffering, options, and lifetime.

• Executing ECSQL in the frontend covers network-round-trip considerations.
• Backend migration guidance covers replacing withPreparedStatement.

See also:

• About ECSQL
• Frequently used ECSQL queries

The createQueryReader Function

All of the iModel classes above provide a createQueryReader method for executing ECSQL statements on an iModel and reading the results of the query. The execution and results are handled by the returned ECSqlReader.

For reference, here are all three createQueryReader methods.

• IModelDb.createQueryReader
• ECDb.createQueryReader
• IModelConnection.createQueryReader

Here is the TypeScript method signature for createQueryReader:

• The ecsql string is the query to execute, for example:

  SELECT ECInstanceId, ECClassId FROM BisCore.Element

• The params argument of type QueryBinder contains any bindings for the ECSQL statement.

• The config argument of type QueryOptions is for additional options for how the query will be executed. Some examples are:

  • rowFormat for determining how query results will look. For an explanation of the available formats, see ECSQL Row Formats.
  • limit for specifying how many rows can be returned at most.
  • restartToken for canceling a previous query with the same token and starting a new one.
  • usePrimaryConn for queries that need to see unsaved changes on the owning backend connection. By default, concurrent queries use separate worker connections. This option does not remove result buffering.

Iterating Over Query Results

Use the ECSqlReader created by the createQueryReader function to iterate over query results. There are three primary ways to do so:

1. Stream them using ECSqlReader as an asynchronous iterator.

Results are QueryRowProxy objects. See Handling a Row of Query Results for how to handle the results.

2. Iterate over them manually using ECSqlReader.step.

Results are QueryRowProxy objects. See Handling a Row of Query Results for how to handle the results.

3. Collect all remaining results using ECSqlReader.toArray.

Each result is an array by default, or an object when a named row format is selected. Collecting all rows uses memory proportional to the result size; prefer iteration for large results.

Handling a Row of Query Results

Iteration and step() expose a QueryRowProxy for the current row. Access values by column index or by name. The proxy follows the reader's current row; materialize a row before retaining it across reader advances.

The rowFormat option controls materialized row shape and some value conversions. See ECSQL Row Formats.

Accessing Row Values By Index

When iterating with a for loop:

When iterating with step:

Column indexes follow SELECT-column order in every row format. The queries below place ECInstanceId and ECClassId at indexes 0,1 and 1,0 respectively. The value representation can still depend on the format; for example, JS formatting converts unaliased class IDs to class names.

SELECT ECInstanceId, ECClassId FROM bis.Element SELECT ECClassId, ECInstanceId FROM bis.Element

Accessing Row Values By Name

When iterating with a for loop:

When iterating with step:

Using Types with the Row Results

See property value types for result types. Properties can be absent when their value is null, as with Parent in this example:

Working with Rows as JavaScript Literals

Call row.toRow() to materialize the current row as a plain object. It uses ECSQL names unless the deprecated UseJsPropertyNames format was selected, including when the reader uses the default index format. Store these objects rather than the reusable row proxy.

row.toArray() returns only the current row's raw values. reader.toArray() collects all remaining rows, using the selected row format. See ECSQL Row Formats for the distinctions.

When iterating with a for loop:

When iterating with step:

Select an object format when collecting all rows with reader.toArray():

Specifying Row Formats

Set config.rowFormat to a QueryRowFormat value. These examples show the three formats; ECSQL Row Formats defines naming, class-ID conversion, and null handling.

QueryRowFormat.UseECSqlPropertyIndexes

This is the default format. reader.toArray() produces arrays of values in SELECT-column order.

Here is an example using .toArray:

Example Output:

Notice that the individual rows are returned as arrays.

QueryRowFormat.UseECSqlPropertyNames

reader.toArray() produces objects keyed by ECSQL column names or aliases.

Here is an example using .toArray:

Example Output:

Deprecated QueryRowFormat.UseJsPropertyNames

This legacy format converts unaliased class-ID values to class names and maps property keys to names such as id, className, and navigation relClassName. It is deprecated; use it only while preserving an existing result contract. New queries should use UseECSqlPropertyNames, explicit aliases, and ec_classname() projections. See ECSQL Row Formats.

Here is an example using .toArray:

Example Output:

ECInstanceId becomes id, and ECClassId becomes className with a qualified class-name value.

Parameter Bindings

See ECSQL Parameter Types to learn which types to use for the parameters when binding.

Positional parameters

Named parameters

Navigation properties

Filter navigation properties by their members. For example, bind the related instance ID to a predicate on Parent.Id. Whole navigation-value bindings are not supported by the query readers.

Struct properties

Parameterize individual struct members. Whole-struct bindings are not supported by the query readers. This example uses the sample schema in Struct properties in ECSQL.

ID sets

Use QueryBinder.bindIdSet to bind a set of Id64 values for InVirtualSet:

Array properties

The query readers do not support arbitrary ECSQL array-property parameters. ID-set bindings are a separate facility. See parameter support and legacy statement bindings.