@itwin/core-backend 5.13.0-dev.1 → 5.13.0-dev.11

package/lib/esm/IModelDb.js

@@ -9,7 +9,7 @@ import * as fs from "fs";
 import { join } from "path";
 import * as touch from "touch";
 import { assert, BeEvent, BentleyStatus, ChangeSetStatus, DbChangeStage, DbConflictCause, DbConflictResolution, DbResult, Guid, Id64, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode } from "@itwin/core-bentley";
-import { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryBinder, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
+import { Base64EncodedString, BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryBinder, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
 import { Range2d, Range3d } from "@itwin/core-geometry";
 import { BackendLoggerCategory } from "./BackendLoggerCategory";
 import { BriefcaseManager } from "./BriefcaseManager";
@@ -185,12 +185,16 @@ export class IModelDb extends IModel {
     [_implicitTxn];
     /** @internal */
     [_activeTxn];
-    /** Returns the active [[EditTxn]] if one is current, otherwise the implicit transaction.
-     * Use this inside element and relationship callbacks that may be invoked either during an explicit transaction or
-     * during indirect change processing.
-     * @note This method is a temporary workaround until [[OnElementArg]] (and related callback arg types) are updated
-     * to carry the transaction directly in a future PR.
-     * @internal
+    /** Returns the transaction to use for additional edits from an element, model, or aspect callback.
+     * In callbacks whose arguments provide an [[IModelDb]] but no transaction, obtain this transaction through
+     * `arg.iModel.getIndirectTxn()` and pass it to APIs that accept an [[EditTxn]].
+     *
+     * If an explicit transaction is active, this returns that transaction. Otherwise, it returns the implicit transaction
+     * used by legacy write paths. Callbacks that receive an `indirectEditTxn` argument should use that transaction directly.
+     *
+     * @note The operation that invoked the callback owns the transaction. Callback implementations must not invoke transaction
+     * lifecycle methods such as [[EditTxn.start]], [[EditTxn.end]], [[EditTxn.saveChanges]], [[EditTxn.abandonChanges]], or [[EditTxn.onClose]].
+     * @beta
      */
     getIndirectTxn() {
         return this[_activeTxn] ?? this[_implicitTxn];
@@ -356,6 +360,7 @@ export class IModelDb extends IModel {
             this.optimize();
         IModelDb._openDbs.delete(this._fileKey);
         this._workspace?.close();
+        this.views[_close]();
         this.locks[_close]();
         this._locks = undefined;
         this._codeService?.close();
@@ -2169,7 +2174,7 @@ function processSchemaWriteStatus(status) {
          * @param props The data for the new model.
          * @returns The newly inserted model's Id.
          * @throws [[IModelError]] if insertion fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertModel(props) {
             return this._iModel[_implicitTxn].insertModel(props);
@@ -2177,7 +2182,7 @@ function processSchemaWriteStatus(status) {
         /** Update an existing model.
          * @param props the properties of the model to change
          * @throws [[IModelError]] if update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateModel(props) {
             this._iModel[_implicitTxn].updateModel(props);
@@ -2189,7 +2194,7 @@ function processSchemaWriteStatus(status) {
          * Cached [Tile]($frontend)s are only invalidated after the geometry guid of the model changes.
          * @note This will throw IModelError with [IModelStatus.VersionTooOld]($core-bentley) if a version of the BisCore schema older than 1.0.11 is present in the iModel.
          * @throws [[IModelError]] if the update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateGeometryGuid instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateGeometryGuid instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          * @see [[TxnManager.onModelGeometryChanged]] for the event emitted in response to such a change.
          */
         updateGeometryGuid(modelId) {
@@ -2198,7 +2203,7 @@ function processSchemaWriteStatus(status) {
         /** Delete one or more existing models.
          * @param ids The Ids of the models to be deleted
          * @throws [[IModelError]] if deletion fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteModel(ids) {
             this._iModel[_implicitTxn].deleteModel(ids);
@@ -2422,7 +2427,7 @@ function processSchemaWriteStatus(status) {
          * However when `elProps.federationGuid` is not present or undefined, a new Guid will be generated and stored on the resultant element. But
          * the value of `elProps.federationGuid` is *not* updated. Generally, it is best to re-read the element after inserting (e.g. via [[getElementProps]])
          * if you intend to continue working with it. That will ensure its values reflect the persistent state.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertElement(elProps, options) {
             return this._iModel[_implicitTxn].insertElement(elProps, options);
@@ -2437,7 +2442,7 @@ function processSchemaWriteStatus(status) {
          * @note The values of `classFullName` and `model` *may not be changed* by this method. Further, it will permute the `elProps` object by adding or
          * overwriting their values to the correct values.
          * @throws [[ITwinError]] if update fails.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateElement(elProps) {
             this._iModel[_implicitTxn].updateElement(elProps);
@@ -2446,7 +2451,7 @@ function processSchemaWriteStatus(status) {
          * @param ids The set of Ids of the element(s) to be deleted
          * @throws [[ITwinError]]
          * @see deleteDefinitionElements
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteElement instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteElement(ids) {
             this._iModel[_implicitTxn].deleteElement(ids);
@@ -2471,7 +2476,7 @@ function processSchemaWriteStatus(status) {
          * DefinitionElements rather than calling this method separately for each one. Ids that are not valid DefinitionElements will be ignored.
          * @returns An IdSet of the DefinitionElements that are used and were therefore not deleted.
          * @see deleteElement
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteDefinitionElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteDefinitionElements instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteDefinitionElements(definitionElementIds) {
             return this._iModel[_implicitTxn].deleteDefinitionElements(definitionElementIds);
@@ -2574,21 +2579,27 @@ function processSchemaWriteStatus(status) {
             return this._queryAspect(aspectInstanceId, aspectClassFullName);
         }
         static classMap = new Map();
+        getAspectPropsFromInstanceQuery(rawInstance) {
+            const parsedRow = typeof rawInstance === "string" ? JSON.parse(rawInstance, Base64EncodedString.reviver) : rawInstance;
+            if (!JsonUtils.isObject(parsedRow))
+                throw new IModelError(IModelStatus.BadRequest, "Expected an ElementAspect instance query to return an object");
+            const row = {};
+            for (const [key, value] of Object.entries(parsedRow)) {
+                const ecPropertyName = key.length === 0 ? key : key[0].toUpperCase() + key.substring(1);
+                row[ECJsNames.toJsName(ecPropertyName)] = value;
+            }
+            const className = row.className;
+            if (typeof className !== "string")
+                throw new IModelError(IModelStatus.BadRequest, "Expected an ElementAspect instance query to return a className");
+            row.classFullName = className.replace(".", ":"); // add in property required by EntityProps
+            delete row.className; // clear property from SELECT $ that we don't want in the final instance
+            return row;
+        }
         runInstanceQuery(sql, elementId, excludedClassFullNames) {
             return this._iModel.withQueryReader(sql, (reader) => {
                 const aspects = [];
                 for (const queryRow of reader) {
-                    const row = {};
-                    const rawInstance = queryRow[0];
-                    const parsedRow = typeof rawInstance === "string" ? JSON.parse(rawInstance) : rawInstance;
-                    // eslint-disable-next-line guard-for-in
-                    for (const key in parsedRow) {
-                        const jsName = ECJsNames.toJsName(key[0].toUpperCase() + key.substring(1));
-                        Object.defineProperty(row, jsName, { enumerable: true, configurable: true, writable: true, value: parsedRow[key] });
-                    }
-                    const aspectProps = row;
-                    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
+                    const aspectProps = this.getAspectPropsFromInstanceQuery(queryRow[0]);
                     if ((undefined === excludedClassFullNames) || !excludedClassFullNames.has(aspectProps.classFullName))
                         aspects.push(this._iModel.constructEntity(aspectProps));
                 }
@@ -2603,9 +2614,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}`);
@@ -2624,7 +2635,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) {
@@ -2643,22 +2654,72 @@ 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}`);
             return aspects;
         }
+        /** Stream the [[ElementAspect]] instances owned by a set of elements.
+         *
+         * Use this method instead of calling [[getAspects]] repeatedly when reading aspects for multiple elements or when the result may be large. The query reads all requested owners together and yields each aspect without buffering the complete result set. For a single element with a small result, [[getAspects]] provides a simpler synchronous API.
+         *
+         * The order is unspecified unless [[QueryAspectOptions.groupByOwner]] is true.
+         * @param options Defines the element Ids, class filters, result ordering, and query connection.
+         * @returns An async iterator over the matching aspects.
+         * @beta
+         */
+        async *queryAspects(options) {
+            const elementIds = Id64.toIdSet(options.elementIds);
+            if (elementIds.size === 0)
+                return;
+            const params = new QueryBinder().bindIdSet("elementIds", elementIds);
+            const classFilter = options.aspectClassFullName === undefined ? "" : `AND aspect.ECClassId IN (
+        SELECT SourceECInstanceId FROM meta.ClassHasAllBaseClasses
+        WHERE TargetECInstanceId=ec_classid(:aspectClassFullName)
+      )`;
+            if (options.aspectClassFullName !== undefined)
+                params.bindString("aspectClassFullName", options.aspectClassFullName.replace(".", ":"));
+            const excludedClassIds = [];
+            let excludedClassIndex = 0;
+            for (const classFullName of options.excludedAspectClassFullNames ?? []) {
+                const parameterName = `excludedAspectClass${excludedClassIndex++}`;
+                excludedClassIds.push(`ec_classid(:${parameterName})`);
+                params.bindString(parameterName, classFullName.replace(".", ":"));
+            }
+            const excludedClassFilter = excludedClassIds.length === 0 ? "" : `AND aspect.ECClassId NOT IN (
+        SELECT ECInstanceId FROM meta.ECClassDef WHERE ECInstanceId IN (${excludedClassIds.join(",")})
+      )`;
+            const orderBy = options.groupByOwner
+                ? "ORDER BY OwnerId, AspectKind, ECClassId, ECInstanceId"
+                : "";
+            const sql = `WITH OwnerIds AS (SELECT id FROM IdSet(:elementIds))
+        SELECT $ FROM (
+          SELECT aspect.ECInstanceId, aspect.ECClassId, aspect.Element.Id AS OwnerId, 0 AS AspectKind
+          FROM OwnerIds owners
+          CROSS JOIN Bis.ElementMultiAspect aspect ON aspect.Element.Id=owners.id
+          WHERE TRUE ${classFilter} ${excludedClassFilter}
+          UNION ALL
+          SELECT aspect.ECInstanceId, aspect.ECClassId, aspect.Element.Id AS OwnerId, 1 AS AspectKind
+          FROM OwnerIds owners
+          CROSS JOIN Bis.ElementUniqueAspect aspect ON aspect.Element.Id=owners.id
+          WHERE TRUE ${classFilter} ${excludedClassFilter}
+        ) ${orderBy}
+        OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`;
+            const reader = this._iModel.createQueryReader(sql, params, { usePrimaryConn: options.usePrimaryConn });
+            for await (const queryRow of reader)
+                yield this._iModel.constructEntity(this.getAspectPropsFromInstanceQuery(queryRow[0]));
+        }
         /** Insert a new ElementAspect into the iModel.
          * @param aspectProps The properties of the new ElementAspect.
          * @throws [[IModelError]] if unable to insert the ElementAspect.
          * @returns the id of the newly inserted aspect.
          * @note Aspect Ids may collide with element Ids, so don't put both in a container like Set or Map
          *       use [EntityReference]($common) for that instead.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.insertAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.insertAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         insertAspect(aspectProps) {
             return this._iModel[_implicitTxn].insertAspect(aspectProps);
@@ -2666,7 +2727,7 @@ function processSchemaWriteStatus(status) {
         /** Update an exist ElementAspect within the iModel.
          * @param aspectProps The properties to use to update the ElementAspect.
          * @throws [[IModelError]] if unable to update the ElementAspect.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.updateAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.updateAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         updateAspect(aspectProps) {
             this._iModel[_implicitTxn].updateAspect(aspectProps);
@@ -2674,7 +2735,7 @@ function processSchemaWriteStatus(status) {
         /** Delete one or more ElementAspects from this iModel.
          * @param aspectInstanceIds The set of instance Ids of the ElementAspect(s) to be deleted
          * @throws [[IModelError]] if unable to delete the ElementAspect.
-         * @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.deleteAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.deleteAspect instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         deleteAspect(aspectInstanceIds) {
             this._iModel[_implicitTxn].deleteAspect(aspectInstanceIds);
@@ -2683,7 +2744,7 @@ function processSchemaWriteStatus(status) {
          * @param props The properties specifying the element to reparent and its new parent.
          * @throws [[ITwinError]] if the operation fails.
          * @beta
-         * @deprecated in 5.11.0 - will not be removed until after 2026-08-04. Use EditTxn.changeElementParent instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.11.0 - might be removed in next major version. Use EditTxn.changeElementParent instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         changeElementParent(props) {
             this._iModel[_implicitTxn].changeElementParent(props);
@@ -2692,7 +2753,7 @@ function processSchemaWriteStatus(status) {
          * @param props The properties specifying the element to move and its new model.
          * @throws [[ITwinError]] if the operation fails.
          * @beta
-         * @deprecated in 5.11.0 - will not be removed until after 2026-08-04. Use EditTxn.changeElementModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @deprecated in 5.11.0 - might be removed in next major version. Use EditTxn.changeElementModel instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         changeElementModel(props) {
             this._iModel[_implicitTxn].changeElementModel(props);
@@ -2711,15 +2772,27 @@ function processSchemaWriteStatus(status) {
         static viewStoreProperty = { namespace: "itwinjs", name: "DefaultViewStore" };
         _viewStore;
         get hasViewStore() { return undefined !== this._viewStore; }
-        /** @beta */
+        /** The [[ViewStore.CloudAccess]] for this iModel.
+         * @note The iModel owns its ViewStore (whether assigned via this setter or created by [[accessViewStore]]): it is closed when the iModel is closed.
+         * @beta
+         */
         get viewStore() {
             if (undefined === this._viewStore)
                 throw new IModelError(IModelStatus.BadRequest, "No ViewStore available");
             return this._viewStore;
         }
         set viewStore(viewStore) {
+            if (this._viewStore !== undefined && this._viewStore !== viewStore)
+                this._viewStore.close();
             this._viewStore = viewStore;
         }
+        /** Close the ViewStore for this iModel, if one is open. Called when the iModel is closed.
+         * @internal
+         */
+        [_close]() {
+            this._viewStore?.close();
+            this._viewStore = undefined;
+        }
         /** @beta */
         async accessViewStore(args) {
             let props = args.props;
@@ -2739,7 +2812,7 @@ function processSchemaWriteStatus(status) {
             return this._viewStore;
         }
         /**
-         * @beta @deprecated in 5.9.0 - will not be removed until after 2026-08-04. Use EditTxn.saveDefaultViewStore instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
+         * @beta @deprecated in 5.9.0 - might be removed in next major version. Use EditTxn.saveDefaultViewStore instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
          */
         saveDefaultViewStore(arg) {
             this._iModel[_implicitTxn].saveDefaultViewStore(arg);