@itwin/core-backend 5.12.0-dev.9 → 5.13.0-dev.2

package/lib/esm/IModelDb.js

@@ -16,6 +16,7 @@ import { BriefcaseManager } from "./BriefcaseManager";
 import { ChannelControl } from "./ChannelControl";
 import { createChannelControl } from "./internal/ChannelAdmin";
 import { CheckpointManager, V2CheckpointManager } from "./CheckpointManager";
+import { getRuntimeClass, reshapeInstanceRow } from "./internal/ECSqlInstanceReshaper";
 import { ClassRegistry, EntityJsClassMap, MetaDataRegistry } from "./ClassRegistry";
 import { CloudSqlite } from "./CloudSqlite";
 import { CodeService } from "./CodeService";
@@ -46,11 +47,11 @@ import { IModelNative } from "./internal/NativePlatform";
 import { createNoOpLockControl } from "./internal/NoLocks";
 import { createIModelDbFonts } from "./internal/IModelDbFontsImpl";
 import { _activeTxn, _cache, _close, _hubAccess, _implicitTxn, _instanceKeyCache, _nativeDb, _releaseAllLocks, _resetIModelDb } from "./internal/Symbols";
-import { ECVersion, SchemaContext, SchemaJsonLocater, SchemaView } from "@itwin/ecschema-metadata";
+import { ECVersion, SchemaContext, SchemaJsonLocater, SchemaManifest, SchemaViewManager } from "@itwin/ecschema-metadata";
 import { SchemaMap } from "./Schema";
 import { ElementLRUCache, InstanceKeyLRUCache } from "./internal/ElementLRUCache";
 import { IModelIncrementalSchemaLocater } from "./IModelIncrementalSchemaLocater";
-import { ECSqlRowExecutor } from "./ECSqlRowExecutor";
+import { ECSqlRowExecutor, releaseECSqlStatement } from "./ECSqlRowExecutor";
 import { integrityCheckTypeMap, performQuickIntegrityCheck, performSpecificIntegrityCheck } from "./internal/IntegrityCheck";
 import { ECSqlSyncReader } from "./ECSqlSyncReader";
 // spell:ignore fontid fontmap
@@ -162,7 +163,9 @@ export class IModelDb extends IModel {
     _jsClassMap;
     _schemaMap;
     _schemaContext;
-    _schemasPromise;
+    // Created lazily on the first getSchemaView call. Owns the SchemaView's lifetime and does all its
+    // data access through the SchemaViewDataProvider implemented below.
+    _schemaViewManager;
     /** @deprecated in 5.0.0 - might be removed in next major version. Use [[fonts]]. */
     _fontMap; // eslint-disable-line @typescript-eslint/no-deprecated
     _fonts = createIModelDbFonts(this);
@@ -610,16 +613,22 @@ export class IModelDb extends IModel {
      * @param config Allow to specify certain flags which control how query is executed.
      * @returns the value returned by `callback`.
      * @throws IModelError if db is not open.
-     * Should be used when we want true step by step behaviour from the reader without any intermediate caching involved.
+     * Use this method for true step-by-step row consumption without intermediate result or page caching.
+     * The prepared ECSQL statement may be reused from the statement cache between completed calls.
      * @beta
      * */
     withQueryReader(ecsql, callback, params, config) {
         if (!this[_nativeDb].isOpen())
             throw new IModelError(DbResult.BE_SQLITE_ERROR_NOTOPEN, "db not open");
-        const executor = new ECSqlRowExecutor(this);
-        const reader = new ECSqlSyncReader(executor, ecsql, params, config);
-        const release = () => executor[Symbol.dispose]();
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const stmt = this._statementCache.findAndRemove(ecsql) ?? new ECSqlStatement();
+        const executor = new ECSqlRowExecutor(this, stmt, loggerCategory);
+        const release = () => {
+            executor[Symbol.dispose]();
+            releaseECSqlStatement(stmt, this._statementCache, loggerCategory, executor.canCacheStatement);
+        };
         try {
+            const reader = new ECSqlSyncReader(executor, ecsql, params, config);
             const val = callback(reader);
             if (val instanceof Promise) {
                 val.then(release, release);
@@ -719,8 +728,7 @@ export class IModelDb extends IModel {
         const where = [...parentCategories].join(",");
         const query = `SELECT ECInstanceId as id, Parent.Id as parentId, Properties as appearance FROM BisCore.SubCategory WHERE Parent.Id IN (${where})`;
         try {
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            for await (const row of this.createQueryReader(query, undefined, { rowFormat: QueryRowFormat.UseJsPropertyNames })) {
+            for await (const row of this.createQueryReader(query, undefined, { rowFormat: QueryRowFormat.UseECSqlPropertyNames })) {
                 result.push(row.toRow());
             }
         }
@@ -740,8 +748,7 @@ export class IModelDb extends IModel {
         const where = [...categoryIds].join(",");
         const query = `SELECT ECInstanceId as id, Parent.Id as parentId, Properties as appearance FROM BisCore.SubCategory WHERE Parent.Id IN (${where})`;
         try {
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            for await (const row of this.createQueryReader(query, undefined, { rowFormat: QueryRowFormat.UseJsPropertyNames })) {
+            for await (const row of this.createQueryReader(query, undefined, { rowFormat: QueryRowFormat.UseECSqlPropertyNames })) {
                 result.push(row.toRow());
             }
         }
@@ -784,7 +791,7 @@ export class IModelDb extends IModel {
                     }
                 }
             }
-        }, QueryBinder.from(params.bindings));
+        }, QueryBinder.fromSkippingNullish(params.bindings));
         return ids;
     }
     clearCaches(params) {
@@ -795,11 +802,7 @@ export class IModelDb extends IModel {
             this._jsClassMap = undefined;
             this._schemaMap = undefined;
             this._schemaContext = undefined;
-            if (this._schemasPromise) {
-                const old = this._schemasPromise;
-                this._schemasPromise = undefined;
-                old.then((view) => view.markOutdated()).catch(() => { });
-            }
+            this._schemaViewManager?.reset();
             this[_nativeDb].clearECDbCache();
         }
         this.elements[_cache].clear();
@@ -1295,53 +1298,74 @@ export class IModelDb extends IModel {
         return this._schemaContext;
     }
     /** Get the schema view for this iModel. The view is built lazily on
-     * first call by fetching compact binary schema data via `PRAGMA schema_view` through
-     * the ConcurrentQuery thread pool. Subsequent calls return the cached view. Multiple
-     * concurrent callers share a single in-flight build.
+     * first call by fetching compact binary schema data through
+     * the ConcurrentQuery thread pool.
      *
      * The returned `SchemaView` is a lightweight, read-only, synchronous API for
      * navigating schema metadata - classes, properties, relationships, enumerations, etc.
      * It is the recommended default for runtime read-only metadata access and is significantly
      * faster and lower-memory than [[schemaContext]]. Use [[schemaContext]] for schema authoring,
      * custom-attribute deserialization, or anywhere you need the full ecschema-metadata object graph.
+     *
+     * Every call shares one accumulating view instance and concurrent calls are serialized, so a
+     * caller never observes a partially loaded view. The instance is discarded by [[clearCaches]],
+     * for example after a schema import; the next call builds a new one. See
+     * [GetSchemaViewArgs]($ecschema-metadata) for the arguments.
      * @beta
      */
-    async getSchemaView() {
-        if (this._schemasPromise) {
-            const ctx = await this._schemasPromise;
-            if (!ctx.isOutdated)
-                return ctx;
-        }
-        // Capture the in-flight promise locally so the rejection handler only clears
-        // `_schemasPromise` if it still points at this build. A concurrent invalidation +
-        // re-fetch could otherwise replace the field before our hydrate fails, and a naive
-        // `_schemasPromise = undefined` would clobber that newer reference.
-        const inflight = this._hydrateSchemas();
-        this._schemasPromise = inflight;
-        inflight.catch(() => {
-            if (this._schemasPromise === inflight)
-                this._schemasPromise = undefined;
-        });
-        return inflight;
-    }
-    async _hydrateSchemas() {
-        // PRAGMA returns exactly one row with format, formatVersion, data (binary), schemaToken.
-        // Important: only call reader.next() once - do NOT use `for await` on PRAGMA results.
-        // ConcurrentQuery wraps regular ECSQL in LIMIT/OFFSET for pagination but skips this for
-        // PRAGMAs. If the serialized result exceeds the memory threshold, the response is marked
-        // "Partial", and a `for await` loop would re-issue the same PRAGMA forever since PRAGMAs
-        // don't support OFFSET-based pagination.
-        // This implementation uses the non-pinned version of the pragma other than frontend - because backend
-        // is always strictly coupled with the native code.
-        const reader = this.createQueryReader("PRAGMA schema_view");
+    async getSchemaView(args) {
+        this._schemaViewManager ??= new SchemaViewManager(this._createSchemaViewDataProvider());
+        return this._schemaViewManager.getSchemaView(args);
+    }
+    /** The [SchemaViewDataProvider]($ecschema-metadata) backing this iModel's [[getSchemaView]]: the
+     * transport-specific half of schema-view loading. The backend always uses the latest blob version
+     * since it is strictly coupled with native code.
+     */
+    _createSchemaViewDataProvider() {
+        return {
+            fetchFullBlob: async () => this._fetchSchemaBlob("PRAGMA schema_view"),
+            // Names are ECNames, so a comma can never occur in one. Native re-validates each token as an
+            // ECName and fails the pragma on an unknown name.
+            fetchFragmentBlob: async (schemaNames) => this._fetchSchemaBlob(`PRAGMA schema_view_fragment('${schemaNames.join(",")}')`),
+            fetchManifest: async () => {
+                const schemaRows = [];
+                const schemaSql = "SELECT ECInstanceId, Name, VersionMajor, VersionWrite, VersionMinor FROM meta.ECSchemaDef";
+                for await (const row of this.createQueryReader(schemaSql)) {
+                    // ECInstanceId arrives as a hex Id64String. `ec_` metadata rowids carry no briefcase
+                    // prefix, so the local id is the full value.
+                    schemaRows.push({ ecInstanceId: Id64.getLocalId(row[0]), name: row[1], versionMajor: row[2], versionWrite: row[3], versionMinor: row[4] });
+                }
+                const referenceRows = [];
+                const referenceSql = "SELECT SourceECInstanceId, TargetECInstanceId FROM meta.SchemaHasSchemaReferences";
+                for await (const row of this.createQueryReader(referenceSql))
+                    referenceRows.push({ sourceECInstanceId: Id64.getLocalId(row[0]), targetECInstanceId: Id64.getLocalId(row[1]) });
+                return SchemaManifest.fromRows(schemaRows, referenceRows);
+            },
+            fetchSchemaToken: async () => {
+                const reader = this.createQueryReader("PRAGMA checksum(schema_token)");
+                const result = await reader.next();
+                if (result.done)
+                    throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA checksum(schema_token) returned no rows");
+                return result.value.sha3_256;
+            },
+        };
+    }
+    /** Fetch one schema-view blob (full or fragment). Both `PRAGMA schema_view` and
+     * `PRAGMA schema_view_fragment` return a single row with the same columns. */
+    async _fetchSchemaBlob(pragma) {
+        // Only call reader.next() once - do NOT use `for await` on PRAGMA results. ConcurrentQuery wraps
+        // regular ECSQL in LIMIT/OFFSET for pagination but skips this for PRAGMAs; if the serialized result
+        // exceeds the memory threshold the response is marked "Partial", and a `for await` loop would
+        // re-issue the same PRAGMA forever since PRAGMAs don't support OFFSET-based pagination.
+        const reader = this.createQueryReader(pragma);
         const result = await reader.next();
         if (result.done)
-            throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned no rows");
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, `${pragma} returned no rows`);
         const data = result.value.data;
         const token = result.value.schemaToken;
         if (data === undefined || data === null)
-            throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned null data column");
-        return SchemaView.fromBinary(data, token ?? "");
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, `${pragma} returned null data column`);
+        return { data, schemaToken: token ?? "" };
     }
     /** Get the linkTableRelationships for this IModel */
     get relationships() {
@@ -2516,16 +2540,21 @@ function processSchemaWriteStatus(status) {
          * @throws [[IModelError]]
          */
         _queryAspect(aspectInstanceId, aspectClassName) {
-            const sql = `SELECT *, ec_classname(ECClassId, 's:c') classFullName FROM ${aspectClassName} WHERE ECInstanceId=:aspectInstanceId`;
+            // `SELECT *` targets a caller/runtime-determined ElementAspect subclass, so its shape can't be decomposed
+            // ahead of time. Query using the non-deprecated UseECSqlPropertyNames format and reshape the row into the
+            // legacy UseJsPropertyNames shape using ECSchema metadata (see ECSqlInstanceReshaper for why a naive,
+            // non-schema-aware rename isn't safe here).
+            const ecClass = getRuntimeClass(this._iModel, aspectClassName);
+            const sql = `SELECT * FROM ${aspectClassName} WHERE ECInstanceId=:aspectInstanceId`;
             const aspect = this._iModel.withQueryReader(sql, (reader) => {
                 if (reader.step()) {
-                    const aspectProps = { ...reader.current.toRow() }; // start with everything that SELECT * returned; classFullName is supplied by the ec_classname alias
-                    aspectProps.className = undefined; // clear the raw ECClassId-derived property from SELECT * that we don't want in the final instance
+                    const aspectProps = reshapeInstanceRow(reader.current.toRow(), ecClass, this._iModel);
+                    aspectProps.classFullName = aspectProps.className.replace(".", ":"); // add in property required by EntityProps
+                    aspectProps.className = undefined; // clear property from SELECT * that we don't want in the final instance
                     return aspectProps;
                 }
                 return undefined;
-                // eslint-disable-next-line @typescript-eslint/no-deprecated
-            }, new QueryBinder().bindId("aspectInstanceId", aspectInstanceId), { rowFormat: QueryRowFormat.UseJsPropertyNames });
+            }, new QueryBinder().bindId("aspectInstanceId", aspectInstanceId), { rowFormat: QueryRowFormat.UseECSqlPropertyNames });
             if (undefined === aspect) {
                 throw new IModelError(IModelStatus.NotFound, `ElementAspect not found ${aspectInstanceId}, ${aspectClassName}`);
             }
@@ -2574,9 +2603,9 @@ function processSchemaWriteStatus(status) {
          */
         getAspects(elementId, aspectClassFullName, excludedClassFullNames) {
             if (aspectClassFullName === undefined) {
-                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
-          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
-            UNION ALL
+                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
+          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
+            UNION ALL
           SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
                 if (allAspects.length === 0)
                     Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);
@@ -2595,7 +2624,7 @@ function processSchemaWriteStatus(status) {
             let classIdList = IModelDb.Elements.classMap.get(aspectClassFullName);
             if (classIdList === undefined) {
                 const classIds = [];
-                const sql = `select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name=:className
+                const sql = `select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name=:className
         and Schema.Id = (select ECInstanceId from meta.ECSchemaDef where Name=:schemaName)) and SourceECInstanceId != TargetECInstanceId`;
                 this._iModel.withQueryReader(sql, (reader) => {
                     for (const row of reader) {
@@ -2614,10 +2643,10 @@ function processSchemaWriteStatus(status) {
                 return [];
             }
             // Execute an instance query to retrieve all aspects from all the derived classes
-            const aspects = this.runInstanceQuery(`SELECT $ FROM (
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
-          UNION ALL
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+            const aspects = this.runInstanceQuery(`SELECT $ FROM (
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+          UNION ALL
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
         ) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
             if (aspects.length === 0)
                 Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);