@itwin/core-backend 5.12.0-dev.8 → 5.12.0

package/lib/cjs/IModelDb.js

@@ -19,6 +19,7 @@ const BriefcaseManager_1 = require("./BriefcaseManager");
 const ChannelControl_1 = require("./ChannelControl");
 const ChannelAdmin_1 = require("./internal/ChannelAdmin");
 const CheckpointManager_1 = require("./CheckpointManager");
+const ECSqlInstanceReshaper_1 = require("./internal/ECSqlInstanceReshaper");
 const ClassRegistry_1 = require("./ClassRegistry");
 const CloudSqlite_1 = require("./CloudSqlite");
 const CodeService_1 = require("./CodeService");
@@ -165,7 +166,9 @@ class IModelDb extends core_common_1.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 = (0, IModelDbFontsImpl_1.createIModelDbFonts)(this);
@@ -613,16 +616,22 @@ class IModelDb extends core_common_1.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[Symbols_1._nativeDb].isOpen())
             throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR_NOTOPEN, "db not open");
-        const executor = new ECSqlRowExecutor_1.ECSqlRowExecutor(this);
-        const reader = new ECSqlSyncReader_1.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_1.ECSqlStatement();
+        const executor = new ECSqlRowExecutor_1.ECSqlRowExecutor(this, stmt, loggerCategory);
+        const release = () => {
+            executor[Symbol.dispose]();
+            (0, ECSqlRowExecutor_1.releaseECSqlStatement)(stmt, this._statementCache, loggerCategory, executor.canCacheStatement);
+        };
         try {
+            const reader = new ECSqlSyncReader_1.ECSqlSyncReader(executor, ecsql, params, config);
             const val = callback(reader);
             if (val instanceof Promise) {
                 val.then(release, release);
@@ -722,8 +731,7 @@ class IModelDb extends core_common_1.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: core_common_1.QueryRowFormat.UseJsPropertyNames })) {
+            for await (const row of this.createQueryReader(query, undefined, { rowFormat: core_common_1.QueryRowFormat.UseECSqlPropertyNames })) {
                 result.push(row.toRow());
             }
         }
@@ -743,8 +751,7 @@ class IModelDb extends core_common_1.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: core_common_1.QueryRowFormat.UseJsPropertyNames })) {
+            for await (const row of this.createQueryReader(query, undefined, { rowFormat: core_common_1.QueryRowFormat.UseECSqlPropertyNames })) {
                 result.push(row.toRow());
             }
         }
@@ -787,7 +794,7 @@ class IModelDb extends core_common_1.IModel {
                     }
                 }
             }
-        }, core_common_1.QueryBinder.from(params.bindings));
+        }, core_common_1.QueryBinder.fromSkippingNullish(params.bindings));
         return ids;
     }
     clearCaches(params) {
@@ -798,11 +805,7 @@ class IModelDb extends core_common_1.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[Symbols_1._nativeDb].clearECDbCache();
         }
         this.elements[Symbols_1._cache].clear();
@@ -1298,53 +1301,74 @@ class IModelDb extends core_common_1.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 ecschema_metadata_1.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: core_bentley_1.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: core_bentley_1.Id64.getLocalId(row[0]), targetECInstanceId: core_bentley_1.Id64.getLocalId(row[1]) });
+                return ecschema_metadata_1.SchemaManifest.fromRows(schemaRows, referenceRows);
+            },
+            fetchSchemaToken: async () => {
+                const reader = this.createQueryReader("PRAGMA checksum(schema_token)");
+                const result = await reader.next();
+                if (result.done)
+                    throw new core_common_1.IModelError(core_bentley_1.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 core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned no rows");
+            throw new core_common_1.IModelError(core_bentley_1.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 core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned null data column");
-        return ecschema_metadata_1.SchemaView.fromBinary(data, token ?? "");
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, `${pragma} returned null data column`);
+        return { data, schemaToken: token ?? "" };
     }
     /** Get the linkTableRelationships for this IModel */
     get relationships() {
@@ -2520,16 +2544,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 = (0, ECSqlInstanceReshaper_1.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 = (0, ECSqlInstanceReshaper_1.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 core_common_1.QueryBinder().bindId("aspectInstanceId", aspectInstanceId), { rowFormat: core_common_1.QueryRowFormat.UseJsPropertyNames });
+            }, new core_common_1.QueryBinder().bindId("aspectInstanceId", aspectInstanceId), { rowFormat: core_common_1.QueryRowFormat.UseECSqlPropertyNames });
             if (undefined === aspect) {
                 throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, `ElementAspect not found ${aspectInstanceId}, ${aspectClassName}`);
             }