Pragmas

PRAGMA help

Print out list of pragma supported by ECSQL.

PRAGMA checksum

Calculate and print out SHA3 256 hash for a subset of the ec_ tables or the sqlite schema

• ecdb_schema - Includes only the ec definition tables but not the mapping tables

  ec_Schema, ec_SchemaReference, ec_Class, ec_ClassHasBaseClasses, ec_Enumeration, ec_KindOfQuantity, ec_UnitSystem, ec_Phenomenon, ec_Unit, ec_Format, ec_FormatCompositeUnit, ec_PropertyCategory, ec_Property, ec_RelationshipConstraint, ec_RelationshipConstraintClass, ec_CustomAttribute

• ecdb_map - Includes only the ec mapping tables but not the ec definition tables

  ec_PropertyPath, ec_ClassMap, ec_Table, ec_Column, ec_Index, ec_IndexColumn, ec_PropertyMap

• sqlite_schema - Includes information in the sqlite_master table
• schema_token - A cheap schema-identity hash (every schema's name and version only, one tiny row per schema), intended as a cache-invalidation key for SchemaView.

PRAGMA ecdb_ver

Print out ECDb current profile version supported by software and file profile version.

PRAGMA ecsql_ver

Print out the current ECSQL version supported by the software. This will allow applications to check feature availability when working with ECSql.

PRAGMA sqlite_sql

Print out the underlying sqlite/native sql as a string. This will help debugging ECSql statements.

PRAGMA experimental_features_enabled

Enable experimental feature in ECSQL on current connection.

to switch off

to check if flag is currently set.

PRAGMA validate_ecsql_writes

Enable validation of values in ECSQL insert statement on current connection.

to switch off

to check if flag is currently set.

PRAGMA explain_query

Prints out a high level description of the strategy or plan SQLite uses to implement a specific SQL query generated by the input ECSql query. For use in interactive debugging purposes, the output of this command may change in the future.

PRAGMA integrity_check (experimental)

Checks ECDb schema and data consistency without modifying the database. It is available on read-only connections. IModelDb.integrityCheck wraps the pragma for backend TypeScript callers.

Summary results

Without a check name, the pragma runs all checks listed above except check_missing_child_rows. It stops each check at its first problem and returns one summary row per check. This is the quick mode used by IModelDb.integrityCheck() by default.

Detailed results

Pass a check name to return its problem rows. An empty result means the selected check found no problems. Query execution errors can prevent a check from completing and are distinct from returned problem rows.

Each detailed result includes a one-based sno. Other fields depend on the selected check. IModelDb.integrityCheck accepts selections through IntegrityCheckOptions.specificChecks; enable all eleven options and set quickCheck: false to get full detailed coverage without also running the summary checks.

Navigation ID results

A navigation property stores the referenced instance's ECInstanceId in its .Id member. For example, Element.Model.Id identifies the model containing that element.

check_nav_ids resolves the navigation property's relationship constraint class, then looks for a referenced row with that ID. The query includes derived classes and uses the first constraint class for the navigation direction. Null navigation IDs are ignored.

A result means the referenced-class query found no row with that ID. The class definition was resolved before the query ran. The result does not distinguish an absent instance from an instance outside that class hierarchy, and contains no further per-row error message.

For Element.Model, the check is equivalent to:

Missing child-row results

An element can occupy rows in several physical tables. This check starts with existing bis_Element rows and looks for required child-table rows with the same element ID. It checks physical storage rows, not parent/child element relationships.

Results contain class (BisCore:Element), id (element ID), class_id (the element's ECClassId), and MissingRowInTables. The last field is a comma-separated list of all child tables checked for that class; at least one lacks a row, but the list does not identify which ones are missing. The TypeScript API names these last two fields classId and missingRowInTables.

Diverged property-map results

This check compares the storage mappings of an inherited property in a derived class and each base class. It reports different columns within a shared physical table hierarchy. It excludes ECDbSystem properties and mappings under different physical table roots, and does not compare instance values.

Results identify the derived class (derivedClassId, derivedClassName), base class (baseClassId, baseClassName), property access path (propertyName), and the two table.column mappings (baseColumn, divergedColumn).

PRAGMA parse_tree (experimental)

Generates a json representation parsed tree of the input ECSql.

PRAGMA schema_view

Returns a curated subset of EC schema metadata from the connection as a single compact binary blob. This is used internally by SchemaView to hydrate a lightweight, read-only schema cache in a single round-trip instead of loading each schema individually. The subset is described in SchemaView - What is included / excluded.

The pragma accepts an optional integer argument to select the binary format version. When omitted, the latest supported version is returned (currently v1).

Explicitly request format version 1:

The result is a single row with the following columns:

The pragma is read-only. Attempting to set a value returns an error.

Passing an unsupported format version returns an error:

The pragma works against any ECDb profile from 4.0.0.1 onward; older files do not need to be upgraded first. On profile 4.0.0.1 only, KindOfQuantity persistence and presentation strings are returned in legacy FUS format rather than EC3.2; all other data is unaffected. See SchemaViewBinaryFormat - ECDb Profile Compatibility for details.

PRAGMA schema_view_fragment

Returns the same binary format as schema_view, but for a chosen subset of the connection's schemas instead of all of them. This backs incremental loading of a SchemaView: a consumer can hydrate only the schemas it needs - for example BisCore and its references - rather than every schema in the iModel. A fragment is a content subset of the identical format, not a different format, so the blob it returns is parsed exactly like a schema_view blob. See SchemaViewBinaryFormat - Fragments.

The single string argument is a comma-separated list of schema names, optionally prefixed with a v<N>; format-version token. Names are matched case-insensitively:

The pragma does not expand references itself - the caller controls exactly which schemas the blob contains, computed from the schema reference graph (meta.ECSchemaDef + meta.SchemaHasSchemaReferences). What set to pass depends on how the blob is consumed:

• Parsed standalone (used on its own to build a SchemaView): pass a dependency-closed set - every schema referenced by a requested schema is also in the list. A referenced schema left out leaves its cross-references unresolved; they parse as "not present", the same as an excluded schema.
• Merged into an existing view (incremental loading): references already merged from an earlier fragment may be omitted. Cross-references resolve against the accumulated view, so only the still-missing schemas need to be in the list. The incremental loader relies on this to avoid re-fetching schemas it already has.

The result row has the same columns as schema_view: format, formatVersion, data, schemaToken.

The pragma is read-only. It fails (returning no blob, not a partial one) on an empty list, a malformed or non-existent schema name, or a malformed or unsupported v<N>; prefix. Duplicate names are de-duplicated, not rejected.

Why the format version is embedded in the argument string

The fragment pragma needs two independent inputs - the blob format version and the set of schema names - but the ECSQL pragma infrastructure today only supports exactly one scalar argument (pragma_value is a single token). Putting the version inside that one string, as an optional self-tagged v<N>; prefix, is deliberate. The alternatives are worse or require refactoring the pragma infrastructure.

The embedded v<N>; prefix is self-describing (v1 reads as "version 1"), cannot collide with the name list (schema names are ECNames, which never contain ; or ,), and is read first so a future format that changes the list encoding can dispatch on the version before parsing the rest - the role a leading version byte plays in any binary wire format. It also keeps this pragma consistent with schema_view, where the format version is likewise the single optional leading argument; the common case schema_view_fragment('BisCore,Generic') stays clean and means "latest version." The choice is reversible: if pragmas ever gain real multi-argument support, the prefix can be promoted to a proper second argument while the string form is accepted during a deprecation window.

Using schema_token for cache invalidation

PRAGMA checksum(schema_token) returns a cheap hash that identifies the current set of schemas - their names and versions only. It is intended as a cache-invalidation key for a SchemaView: hold onto the schemaToken column returned by schema_view / schema_view_fragment, and later compare it against PRAGMA checksum(schema_token) to decide whether the cached view is stale.

Like the other checksum keys, the result is a single row whose sha3_256 column holds the SHA3-256 hash - here, of every schema's name and version digits.

ECSql Syntax