@itwin/imodel-transformer 2.0.0-dev.7 → 2.0.0-dev.70

package/lib/cjs/IModelExporter.js

@@ -13,8 +13,13 @@ const core_bentley_1 = require("@itwin/core-bentley");
 const core_common_1 = require("@itwin/core-common");
 const ecschema_metadata_1 = require("@itwin/ecschema-metadata");
 const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
-const nodeAssert = require("assert");
-const ExportElementAspectsWithElementsStrategy_1 = require("./ExportElementAspectsWithElementsStrategy");
+const node_assert_1 = require("node:assert");
+const ElementAspectExportProcessor_1 = require("./ElementAspectExportProcessor");
+const ElementAspectExportCoordinator_1 = require("./ElementAspectExportCoordinator");
+const IModelTransformerError_1 = require("./IModelTransformerError");
+const ChangesetScanner_1 = require("./ChangesetScanner");
+const SourceClassKinds_1 = require("./SourceClassKinds");
+const ChangedElementForest_1 = require("./ChangedElementForest");
 const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter;
 /** Handles the events generated by IModelExporter.
  * @note Change information is available when `IModelExportHandler` methods are invoked via [IModelExporter.exportChanges]($transformer), but not available when invoked via [IModelExporter.exportAll]($transformer).
@@ -26,7 +31,7 @@ class IModelExportHandler {
     /** If `true` is returned, then the CodeSpec will be exported.
      * @note This method can optionally be overridden to exclude an individual CodeSpec from the export. The base implementation always returns `true`.
      */
-    shouldExportCodeSpec(_codeSpec) {
+    async shouldExportCodeSpec(_codeSpec) {
         return true;
     }
     /** Called when a CodeSpec should be exported.
@@ -34,31 +39,33 @@ class IModelExportHandler {
      * @param isUpdate If defined, then `true` indicates an UPDATE operation while `false` indicates an INSERT operation. If not defined, then INSERT vs. UPDATE is not known.
      * @note This should be overridden to actually do the export.
      */
-    onExportCodeSpec(_codeSpec, _isUpdate) { }
+    async onExportCodeSpec(_codeSpec, _isUpdate) { }
     /** Called when a font should be exported.
      * @param font The font to export
      * @param isUpdate If defined, then `true` indicates an UPDATE operation while `false` indicates an INSERT operation. If not defined, then INSERT vs. UPDATE is not known.
      * @note This should be overridden to actually do the export.
      */
-    onExportFont(_font, _isUpdate) { }
+    async onExportFont(_font, _isUpdate) { }
     /** Called when a model should be exported.
      * @param model The model to export
      * @param isUpdate If defined, then `true` indicates an UPDATE operation while `false` indicates an INSERT operation. If not defined, then INSERT vs. UPDATE is not known.
      * @note This should be overridden to actually do the export.
      */
-    onExportModel(_model, _isUpdate) { }
+    async onExportModel(_model, _isUpdate) { }
     /** Called when a model should be deleted. */
     async onDeleteModel(_modelId) { }
     /** If `true` is returned, then the element will be exported.
      * @note This method can optionally be overridden to exclude an individual Element (and its children and ElementAspects) from the export. The base implementation always returns `true`.
+     * @note During [IModelExporter.exportChanges]($transformer), this method is also called once for each unchanged ancestor of a changed element, so that a rejected ancestor excludes its changed descendants.
      */
-    shouldExportElement(_element) {
+    async shouldExportElement(_element) {
         return true;
     }
     /** Called when element is skipped instead of exported.
      * @note When an element is skipped, exporter will not export any of its child elements. Because of this, [[onSkipElement]] will not be invoked for any children of a "skipped" element.
+     * @note During [IModelExporter.exportChanges]($transformer), an unchanged ancestor is filtered only when a changed descendant is reached. An element excluded by ID below it may therefore receive [[onSkipElement]] before the ancestor is rejected.
      */
-    onSkipElement(_elementId) { }
+    async onSkipElement(_elementId) { }
     /** Called when an element should be exported.
      * @param element The element to export
      * @param isUpdate If defined, then `true` indicates an UPDATE operation while `false` indicates an INSERT operation. If not defined, then INSERT vs. UPDATE is not known.
@@ -72,12 +79,12 @@ class IModelExportHandler {
      * @internal
      */
     async preExportElement(_element) { }
-    /** Called when an element should be deleted. */
-    onDeleteElement(_elementId) { }
+    /** Called once with the source IDs of all elements deleted by the exported changes. */
+    async onDeleteElements(_elementIds) { }
     /** If `true` is returned, then the ElementAspect will be exported.
      * @note This method can optionally be overridden to exclude an individual ElementAspect from the export. The base implementation always returns `true`.
      */
-    shouldExportElementAspect(_aspect) {
+    async shouldExportElementAspect(_aspect) {
         return true;
     }
     /** Called when an ElementUniqueAspect should be exported.
@@ -93,21 +100,23 @@ class IModelExportHandler {
     /** If `true` is returned, then the relationship will be exported.
      * @note This method can optionally be overridden to exclude an individual CodeSpec from the export. The base implementation always returns `true`.
      */
-    shouldExportRelationship(_relationship) {
+    async shouldExportRelationship(_relationship) {
         return true;
     }
     /** Called when a Relationship should be exported.
      * @param relationship The Relationship to export
      * @param isUpdate If defined, then `true` indicates an UPDATE operation while `false` indicates an INSERT operation. If not defined, then INSERT vs. UPDATE is not known.
+     * @param sourceFedGuid The FederationGuid of the relationship's source endpoint, if available.
+     * @param targetFedGuid The FederationGuid of the relationship's target endpoint, if available.
      * @note This should be overridden to actually do the export.
      */
-    async onExportRelationship(_relationship, _isUpdate) { }
+    async onExportRelationship(_relationship, _isUpdate, _sourceFedGuid, _targetFedGuid) { }
     /** Called when a relationship should be deleted. */
-    onDeleteRelationship(_relInstanceId) { }
+    async onDeleteRelationship(_relInstanceId) { }
     /** If `true` is returned, then the schema will be exported.
      * @note This method can optionally be overridden to exclude an individual schema from the export. The base implementation always returns `true`.
      */
-    shouldExportSchema(_schemaKey) {
+    async shouldExportSchema(_schemaKey) {
         return true;
     }
     /** Called when a schema should be exported.
@@ -126,10 +135,14 @@ class IModelExportHandler {
 exports.IModelExportHandler = IModelExportHandler;
 /** Base class for exporting data from an iModel.
  * @note Most uses cases will not require a custom subclass of `IModelExporter`. Instead, it is more typical to subclass/customize [IModelExportHandler]($transformer).
+ * ElementAspects are exported separately from element callbacks in bounded,
+ * owner-scoped groups. Aspect callbacks are not guaranteed to be adjacent to
+ * callbacks for their owners.
  * @see [iModel Transformation and Data Exchange]($docs/learning/transformer/index.md), [[registerHandler]], [IModelTransformer]($transformer), [IModelImporter]($transformer)
  * @beta
  */
 class IModelExporter {
+    static _elementAspectOwnerBatchSize = 1000;
     /** The read-only source iModel. */
     sourceDb;
     /** A flag that indicates whether element GeometryStreams are loaded or not.
@@ -163,6 +176,12 @@ class IModelExporter {
     _progressCounter = 0;
     /** Optionally cached entity change information */
     _sourceDbChanges;
+    /** State shared by nested calls in one change-processing element traversal. */
+    _changedElementTraversal;
+    /** Unchanged elements on the current change-processing path. Each is filtered only when a changed descendant is reached. */
+    _unchangedAncestors = [];
+    /** Bounds the additional hierarchy retained by the sparse changed-element path. */
+    _changedElementForestElementLimit = 100_000;
     /**
      * Retrieve the cached entity change information.
      * @note This will only be initialized after [IModelExporter.exportChanges] is invoked or [IModelExporter.initialize] is called.
@@ -175,7 +194,13 @@ class IModelExporter {
     /** The handler called by this IModelExporter. */
     get handler() {
         if (undefined === this._handler) {
-            throw new Error("IModelExportHandler not registered");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ExportHandlerNotRegistered,
+                },
+                message: "IModelExportHandler not registered",
+            });
         }
         return this._handler;
     }
@@ -189,20 +214,37 @@ class IModelExporter {
     _excludedElementClasses = new Set();
     /** The set of classes of Relationships that will be excluded (polymorphically) from transformation to the target iModel. */
     _excludedRelationshipClasses = new Set();
-    /** Strategy for how ElementAspects are exported */
-    _exportElementAspectsStrategy;
+    /** Exports ElementAspects for accepted owner groups. */
+    _elementAspectExportProcessor;
+    /** Coordinates accepted-owner scopes and bounded group processing. */
+    _elementAspectExportCoordinator;
+    /** Coordinates accepted ElementAspect owners and bounded group processing.
+     * @internal
+     */
+    get elementAspectExportCoordinator() {
+        return this._elementAspectExportCoordinator;
+    }
+    /** Whether change traversal skips root-owned entities. */
+    _skipPropagateChangesToRootElements = false;
+    _rootElementIds = new Set([
+        core_common_1.IModel.rootSubjectId,
+        core_common_1.IModel.repositoryModelId,
+        core_common_1.IModel.dictionaryId,
+        "0xe", // The reality-data-sources modelId, skipped with root propagation.
+    ]);
     /** Construct a new IModelExporter
      * @param sourceDb The source IModelDb
      * @see registerHandler
      */
-    constructor(sourceDb, elementAspectsStrategy = ExportElementAspectsWithElementsStrategy_1.ExportElementAspectsWithElementsStrategy) {
+    constructor(sourceDb) {
         this.sourceDb = sourceDb;
-        this._exportElementAspectsStrategy = new elementAspectsStrategy(this.sourceDb, {
+        this._elementAspectExportProcessor = new ElementAspectExportProcessor_1.ElementAspectExportProcessor(this.sourceDb, {
             onExportElementMultiAspects: async (aspects) => this.handler.onExportElementMultiAspects(aspects),
             onExportElementUniqueAspect: async (aspect, isUpdate) => this.handler.onExportElementUniqueAspect(aspect, isUpdate),
-            shouldExportElementAspect: (aspect) => this.handler.shouldExportElementAspect(aspect),
+            shouldExportElementAspect: async (aspect) => this.handler.shouldExportElementAspect(aspect),
             trackProgress: async () => this.trackProgress(),
         });
+        this._elementAspectExportCoordinator = new ElementAspectExportCoordinator_1.ElementAspectExportCoordinator(IModelExporter._elementAspectOwnerBatchSize, () => this._elementAspectExportProcessor.excludedElementAspectClassFullNames, async (elementIds) => this._elementAspectExportProcessor.exportAllElementAspects(elementIds), () => this._elementAspectExportProcessor.resetCaches());
     }
     /**
      * Initialize prerequisites of exporting. This is implicitly done by any `export*` calls that need initialization
@@ -220,7 +262,7 @@ class IModelExporter {
         });
         if (this._sourceDbChanges === undefined)
             return;
-        this._exportElementAspectsStrategy.setAspectChanges(this._sourceDbChanges.aspect);
+        this._elementAspectExportProcessor.setAspectChanges(this._sourceDbChanges.aspect);
     }
     /** Register the handler that will be called by IModelExporter. */
     registerHandler(handler) {
@@ -230,7 +272,9 @@ class IModelExporter {
     excludeCodeSpec(codeSpecName) {
         this._excludedCodeSpecNames.add(codeSpecName);
     }
-    /** Add a rule to exclude a specific Element. */
+    /** Add a rule to exclude a specific Element.
+     * @note Configure exclusions before starting an export operation. Changing exclusions while an export is in progress is unsupported.
+     */
     excludeElement(elementId) {
         this._excludedElementIds.add(elementId);
     }
@@ -244,7 +288,7 @@ class IModelExporter {
     }
     /** Add a rule to exclude all ElementAspects of a specified class. */
     excludeElementAspectClass(classFullName) {
-        this._exportElementAspectsStrategy.excludeElementAspectClass(classFullName);
+        this._elementAspectExportProcessor.excludeElementAspectClass(classFullName);
     }
     /** Add a rule to exclude all Relationships of a specified class. */
     excludeRelationshipClass(classFullName) {
@@ -257,11 +301,12 @@ class IModelExporter {
         await this.initialize({});
         await this.exportCodeSpecs();
         await this.exportFonts();
-        await this.exportModel(core_common_1.IModel.repositoryModelId);
+        await this._elementAspectExportCoordinator.run(async () => this.exportModel(core_common_1.IModel.repositoryModelId));
         await this.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
     }
     /** Export changes from the source iModel.
      * Inserts, updates, and deletes are determined by inspecting the changeset(s).
+     * @throws [[ITwinError]] with scope `@itwin/imodel-transformer` and key `no-changesets` if the source iModel has no changesets and no custom changes. Call [[exportAll]] to export all content.
      * @note To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired
      *       range and open the source iModel as of the end (inclusive) of the desired range.
      * @note the changedInstanceIds are just for this call to exportChanges, so you must continue to pass it in
@@ -269,29 +314,68 @@ class IModelExporter {
      */
     async exportChanges(args) {
         if (!this.sourceDb.isBriefcaseDb())
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Must be a briefcase to export changes");
-        if ("" === this.sourceDb.changeset.id &&
-            !this.sourceDbChanges?.hasChanges) {
-            await this.exportAll(); // no changesets or custom changes, so revert to exportAll
-            return;
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ExportChangesRequiresBriefcase,
+                },
+                message: "Must be a briefcase to export changes",
+            });
+        let initOpts = args ?? {};
+        const hasExplicitChangeSource = "csFileProps" in initOpts ||
+            "changedInstanceIds" in initOpts ||
+            "changesetRanges" in initOpts ||
+            "startChangeset" in initOpts;
+        const currentChangesetId = this.sourceDb.changeset.id;
+        if (!hasExplicitChangeSource && currentChangesetId !== "") {
+            initOpts = {
+                ...initOpts,
+                startChangeset: { id: currentChangesetId },
+            };
         }
-        const startChangeset = args && "startChangeset" in args ? args.startChangeset : undefined;
-        const initOpts = {
-            startChangeset: { id: startChangeset?.id },
-        };
         await this.initialize(initOpts);
+        if (currentChangesetId === "" && !this.sourceDbChanges?.hasChanges) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.NoChangesets,
+                },
+                message: "Cannot export changes because the source iModel has no changesets or custom changes. Call exportAll() to export all content.",
+            });
+        }
+        this._skipPropagateChangesToRootElements =
+            initOpts.skipPropagateChangesToRootElements ?? false;
         // _sourceDbChanges are initialized in this.initialize
-        nodeAssert(this._sourceDbChanges !== undefined, "sourceDbChanges must be initialized.");
+        (0, node_assert_1.strict)(this._sourceDbChanges !== undefined, "sourceDbChanges must be initialized.");
         await this.exportCodeSpecs();
         await this.exportFonts();
-        if (initOpts.skipPropagateChangesToRootElements) {
-            await this.exportModelContents(core_common_1.IModel.repositoryModelId);
-            await this.exportSubModels(core_common_1.IModel.repositoryModelId);
+        (0, node_assert_1.strict)(this.beginChangedElementTraversalScope(), "exportChanges must own its changed-element traversal scope");
+        try {
+            await this._elementAspectExportCoordinator.run(async () => {
+                if (initOpts.skipPropagateChangesToRootElements) {
+                    // The root Subject is in the RepositoryModel. Traverse its children
+                    // separately, then export other top-level repository elements while
+                    // excluding the root so no element is visited twice.
+                    await this.exportChildElements(core_common_1.IModel.rootSubjectId);
+                    await this.exportModelContents(core_common_1.IModel.repositoryModelId, core_backend_1.Element.classFullName, true);
+                    await this.exportSubModels(core_common_1.IModel.repositoryModelId);
+                }
+                else {
+                    await this.exportModel(core_common_1.IModel.repositoryModelId);
+                }
+            });
+            const aspectOnlyOwnerElementIds = new Set(this._sourceDbChanges.aspectOwnerElementIds);
+            for (const elementId of this._sourceDbChanges.element.insertIds) {
+                aspectOnlyOwnerElementIds.delete(elementId);
+            }
+            for (const elementId of this._sourceDbChanges.element.updateIds) {
+                aspectOnlyOwnerElementIds.delete(elementId);
+            }
+            await this.exportAspectsForOwners(await this.filterOwnerElementIdsForAspectExport(aspectOnlyOwnerElementIds));
         }
-        else {
-            await this.exportModel(core_common_1.IModel.repositoryModelId);
+        finally {
+            this.endChangedElementTraversalScope();
         }
-        await this.exportAllAspects();
         await this.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
         // handle deletes
         if (this.visitElements) {
@@ -299,42 +383,31 @@ class IModelExporter {
             for (const modelId of this._sourceDbChanges.model.deleteIds) {
                 await this.handler.onDeleteModel(modelId);
             }
-            for (const elementId of this._sourceDbChanges.element.deleteIds) {
-                // We don't know how the handler wants to handle deletions, and we don't have enough information
-                // to know if deleted entities were related, so when processing changes, ignore errors from deletion.
-                // Technically, to keep the ignored error scope small, we ignore only the error of looking up a missing element,
-                // that approach works at least for the IModelTransformer.
-                // In the future, the handler may be responsible for doing the work of finding out which elements were cascade deleted,
-                // and returning them for the exporter to use to avoid double-deleting with error ignoring
-                try {
-                    this.handler.onDeleteElement(elementId);
-                }
-                catch (err) {
-                    const isMissingErr = err instanceof core_common_1.IModelError &&
-                        err.errorNumber === core_bentley_1.IModelStatus.NotFound;
-                    if (!isMissingErr)
-                        throw err;
-                }
+            if (this._sourceDbChanges.element.deleteIds.size > 0) {
+                await this.handler.onDeleteElements(new Set(this._sourceDbChanges.element.deleteIds));
             }
         }
         if (this.visitRelationships) {
             for (const relInstanceId of this._sourceDbChanges.relationship
                 .deleteIds) {
-                this.handler.onDeleteRelationship(relInstanceId);
+                await this.handler.onDeleteRelationship(relInstanceId);
             }
         }
         // Enable consecutive exportChanges runs without the need to re-instantiate the exporter.
         // You can counteract the obvious impact of losing this expensive data by always calling
         // exportChanges with the [[ExportChangesOptions.changedInstanceIds]] option set to
         // whatever you want
-        if (this._resetChangeDataOnExport)
+        if (this._resetChangeDataOnExport) {
             this._sourceDbChanges = undefined;
+            this._elementAspectExportProcessor.setAspectChanges(undefined);
+        }
     }
     _resetChangeDataOnExport = true;
-    /** Export schemas from the source iModel.
-     * @note This must be called separately from [[exportAll]] or [[exportChanges]].
+    /** Enumerate schemas from the source iModel in database order.
+     * @note Override this method to customize schema discovery for both direct exports and transformer schema processing.
+     * @beta
      */
-    async exportSchemas() {
+    async *enumerateSchemas() {
         const sql = `
       SELECT s.Name, s.VersionMajor, s.VersionWrite, s.VersionMinor
       FROM ECDbMeta.ECSchemaDef s
@@ -345,23 +418,35 @@ class IModelExporter {
       `}
       ORDER BY ECInstanceId
     `;
-        const schemaNamesToExport = [];
-        for await (const row of this.sourceDb.createQueryReader(sql)) {
-            const schemaName = row[0];
-            const versionMajor = row[1];
-            const versionWrite = row[2];
-            const versionMinor = row[3];
-            const schemaKey = new ecschema_metadata_1.SchemaKey(schemaName, new ecschema_metadata_1.ECVersion(versionMajor, versionWrite, versionMinor));
-            if (this.handler.shouldExportSchema(schemaKey)) {
-                schemaNamesToExport.push(schemaName);
+        for await (const row of this.sourceDb.createQueryReader(sql, undefined, {
+            usePrimaryConn: true,
+        })) {
+            const schemaKey = new ecschema_metadata_1.SchemaKey(row[0], new ecschema_metadata_1.ECVersion(row[1], row[2], row[3]));
+            const schema = await this.sourceDb.schemaContext.getSchema(schemaKey);
+            if (!schema) {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.SchemaLoadFailed,
+                    },
+                    message: `Failed to load schema: ${schemaKey.name}`,
+                });
             }
+            yield schema;
         }
-        if (schemaNamesToExport.length === 0)
-            return;
-        const schemaLoader = new ecschema_metadata_1.SchemaLoader((name) => this.sourceDb.getSchemaProps(name));
-        await Promise.all(schemaNamesToExport.map(async (schemaName) => {
-            const schema = schemaLoader.getSchema(schemaName);
-            core_bentley_1.Logger.logTrace(loggerCategory, `exportSchema(${schemaName})`);
+    }
+    /** Export schemas from the source iModel.
+     * @note This must be called separately from [[exportAll]] or [[exportChanges]].
+     */
+    async exportSchemas() {
+        const schemasToExport = [];
+        for await (const schema of this.enumerateSchemas()) {
+            if (await this.handler.shouldExportSchema(schema.schemaKey)) {
+                schemasToExport.push(schema);
+            }
+        }
+        await Promise.all(schemasToExport.map(async (schema) => {
+            core_bentley_1.Logger.logTrace(loggerCategory, `exportSchema(${schema.name})`);
             return this.handler.onExportSchema(schema);
         }));
     }
@@ -375,8 +460,10 @@ class IModelExporter {
     async exportCodeSpecs() {
         core_bentley_1.Logger.logTrace(loggerCategory, "exportCodeSpecs()");
         const sql = "SELECT Name FROM BisCore:CodeSpec ORDER BY ECInstanceId";
-        for await (const row of this.sourceDb.createQueryReader(sql)) {
-            await this.exportCodeSpecByName(row.name);
+        for await (const row of this.sourceDb.createQueryReader(sql, undefined, {
+            usePrimaryConn: true,
+        })) {
+            await this.exportCodeSpecByName(row[0]);
         }
     }
     /** Export a single CodeSpec from the source iModel.
@@ -403,9 +490,9 @@ class IModelExporter {
             return;
         }
         // CodeSpec has passed standard exclusion rules, now give handler a chance to accept/reject export
-        if (this.handler.shouldExportCodeSpec(codeSpec)) {
+        if (await this.handler.shouldExportCodeSpec(codeSpec)) {
             core_bentley_1.Logger.logTrace(loggerCategory, `exportCodeSpec(${codeSpecName})${this.getChangeOpSuffix(isUpdate)}`);
-            this.handler.onExportCodeSpec(codeSpec, isUpdate);
+            await this.handler.onExportCodeSpec(codeSpec, isUpdate);
             return this.trackProgress();
         }
     }
@@ -443,7 +530,7 @@ class IModelExporter {
      */
     async exportFontByFontProps(fontProps) {
         core_bentley_1.Logger.logTrace(loggerCategory, `exportFontByFamily(${fontProps.name}, ${fontProps.type})`);
-        this.handler.onExportFont(fontProps, true);
+        await this.handler.onExportFont(fontProps, true);
         return this.trackProgress();
     }
     /** Export a single font from the source iModel.
@@ -460,8 +547,8 @@ class IModelExporter {
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
      */
     async exportFontByNumber(fontNumber) {
-        /** sourceDbChanges now works by using TS ChangesetECAdaptor which doesn't pick up changes to fonts since fonts is not an ec table.
-         * So lets always export fonts for the time being by always setting isUpdate = true.
+        /** ChangedInstanceIds contains EC-mapped changes, but the font table is not EC-mapped.
+         * Always export fonts because their changes are therefore absent from sourceDbChanges.
          * It is very rare and even problematic for the font table to reach a large size, so it is not a bottleneck in transforming changes.
          * See https://github.com/iTwin/imodel-transformer/pull/135 for removed code.
          */
@@ -475,6 +562,9 @@ class IModelExporter {
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
      */
     async exportModel(modeledElementId) {
+        return this.runScopedElementExport(async () => this.exportModelImpl(modeledElementId));
+    }
+    async exportModelImpl(modeledElementId) {
         const model = this.sourceDb.models.getModel(modeledElementId);
         if (model.isTemplate && !this.wantTemplateModels) {
             return;
@@ -485,7 +575,7 @@ class IModelExporter {
             wantBRepData: this.wantGeometry,
         });
         core_bentley_1.Logger.logTrace(loggerCategory, `exportModel(${modeledElementId})`);
-        if (this.shouldExportElement(modeledElement)) {
+        if (await this.shouldExportElement(modeledElement)) {
             await this.exportModelContainer(model);
             if (this.visitElements) {
                 await this.exportModelContents(modeledElementId);
@@ -508,7 +598,7 @@ class IModelExporter {
                 return; // not in changeset, don't export
             }
         }
-        this.handler.onExportModel(model, isUpdate);
+        await this.handler.onExportModel(model, isUpdate);
         return this.trackProgress();
     }
     _yieldManager = new core_bentley_1.YieldManager();
@@ -519,6 +609,9 @@ class IModelExporter {
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
      */
     async exportModelContents(modelId, elementClassFullName = core_backend_1.Element.classFullName, skipRootSubject) {
+        return this.runScopedElementExport(async () => this.exportModelContentsImpl(modelId, elementClassFullName, skipRootSubject));
+    }
+    async exportModelContentsImpl(modelId, elementClassFullName, skipRootSubject) {
         if (skipRootSubject) {
             // NOTE: IModelTransformer.processAll should skip the root Subject since it is specific to the individual iModel and is not part of the changes that need to be synchronized
             // NOTE: IModelExporter.exportAll should not skip the root Subject since the goal is to export everything
@@ -534,19 +627,33 @@ class IModelExporter {
                 !this._sourceDbChanges.model.updateIds.has(modelId)) {
                 return; // this optimization assumes that the Model changes (LastMod) any time an Element in the Model changes
             }
+            if (this.canUseChangedElementForest() &&
+                elementClassFullName === core_backend_1.Element.classFullName) {
+                const forest = await this.getChangedElementForest();
+                if (forest !== undefined) {
+                    core_bentley_1.Logger.logTrace(loggerCategory, `exportModelContents(${modelId}) via changed-element index`);
+                    for (const rootId of forest.getModelRoots(modelId)) {
+                        if (skipRootSubject && rootId === core_common_1.IModel.rootSubjectId)
+                            continue;
+                        await this.exportElement(rootId);
+                        await this._yieldManager.allowYield();
+                    }
+                    return;
+                }
+            }
         }
         core_bentley_1.Logger.logTrace(loggerCategory, `exportModelContents(${modelId})`);
-        let sql;
-        if (skipRootSubject) {
-            sql = `SELECT ECInstanceId FROM ${elementClassFullName} WHERE Parent.Id IS NULL AND Model.Id=:modelId AND ECInstanceId!=:rootSubjectId ORDER BY ECInstanceId`;
-        }
-        else {
-            sql = `SELECT ECInstanceId FROM ${elementClassFullName} WHERE Parent.Id IS NULL AND Model.Id=:modelId ORDER BY ECInstanceId`;
-        }
+        const rootFilter = skipRootSubject
+            ? "e.Parent.Id IS NULL AND e.Model.Id=:modelId AND e.ECInstanceId!=:rootSubjectId"
+            : "e.Parent.Id IS NULL AND e.Model.Id=:modelId";
         const params = new core_common_1.QueryBinder().bindId("modelId", modelId);
         if (skipRootSubject) {
             params.bindId("rootSubjectId", core_common_1.IModel.rootSubjectId);
         }
+        if (this.canUseSetBasedTraversal()) {
+            return this.exportElementTreesStreamed(`SELECT e.ECInstanceId, 0 FROM ${elementClassFullName} e WHERE ${rootFilter}`, params);
+        }
+        const sql = `SELECT e.ECInstanceId FROM ${elementClassFullName} e WHERE ${rootFilter} ORDER BY e.ECInstanceId`;
         for await (const row of this.sourceDb.createQueryReader(sql, params, {
             usePrimaryConn: true,
         })) {
@@ -554,17 +661,70 @@ class IModelExporter {
             await this._yieldManager.allowYield();
         }
     }
+    /** Whether the public element traversal methods still have their base implementations. */
+    hasDefaultElementTraversal() {
+        // The optimized helpers bypass these public overridable methods. Compare function
+        // identity so subclass, bound, wrapped, or instrumented methods retain legacy dispatch.
+        return (this.exportElement === IModelExporter.prototype.exportElement &&
+            this.exportChildElements === IModelExporter.prototype.exportChildElements);
+    }
+    /** Whether hierarchy traversal can use the streamed query.
+     * Changes mode and overrides of the public traversal methods require legacy dispatch.
+     */
+    canUseSetBasedTraversal() {
+        return (this._sourceDbChanges === undefined && this.hasDefaultElementTraversal());
+    }
+    /** Stream element trees in the legacy depth-first order with one recursive ECSQL query.
+     * Rejected subtrees are skipped in the exporter without loading their descendants.
+     * @param anchorSelect a SELECT producing `(ECInstanceId, 0)` rows for the tree roots
+     */
+    async exportElementTreesStreamed(anchorSelect, params) {
+        // The anchor seeds roots at depth 0; the recursive term follows parent links.
+        // SQLite's documented recursive-CTE queue behavior makes this ORDER BY a
+        // depth-first priority queue, with ascending IDs breaking ties. Supported
+        // iModel databases use SQLite, so the outer SELECT intentionally consumes
+        // the CTE rows in this queue order.
+        const sql = `
+      WITH RECURSIVE ElementTree (ECInstanceId, Depth) AS (
+        ${anchorSelect}
+        UNION ALL
+        SELECT c.ECInstanceId, t.Depth + 1 FROM ${core_backend_1.Element.classFullName} c
+          JOIN ElementTree t ON c.Parent.Id = t.ECInstanceId
+        ORDER BY 2 DESC, 1 ASC
+      )
+      SELECT ECInstanceId, Depth FROM ElementTree`;
+        let pruneDepth;
+        for await (const row of this.sourceDb.createQueryReader(sql, params, {
+            usePrimaryConn: true,
+        })) {
+            const elementId = row[0];
+            const depth = row[1];
+            const isPruned = pruneDepth !== undefined && depth > pruneDepth;
+            if (!isPruned) {
+                pruneDepth = undefined;
+                if ((await this.exportElementShallow(elementId)) === "skip")
+                    pruneDepth = depth;
+            }
+            // Keep the streamed loop responsive, including while consuming a rejected subtree.
+            await this._yieldManager.allowYield();
+        }
+    }
     /** Export the sub-models directly below the specified model.
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
      */
     async exportSubModels(parentModelId) {
+        return this.runScopedElementExport(async () => this.exportSubModelsImpl(parentModelId));
+    }
+    async exportSubModelsImpl(parentModelId) {
         core_bentley_1.Logger.logTrace(loggerCategory, `exportSubModels(${parentModelId})`);
         const definitionModelIds = [];
         const otherModelIds = [];
         const sql = `SELECT ECInstanceId FROM ${core_backend_1.Model.classFullName} WHERE ParentModel.Id=:parentModelId ORDER BY ECInstanceId`;
         const params = new core_common_1.QueryBinder().bindId("parentModelId", parentModelId);
-        for await (const row of this.sourceDb.createQueryReader(sql, params)) {
-            const modelId = row.ecinstanceid;
+        for await (const row of this.sourceDb.createQueryReader(sql, params, {
+            usePrimaryConn: true,
+        })) {
+            const modelId = row.id;
             const model = this.sourceDb.models.getModel(modelId);
             if (model instanceof core_backend_1.DefinitionModel) {
                 definitionModelIds.push(modelId);
@@ -585,16 +745,15 @@ class IModelExporter {
      * This considers the standard IModelExporter exclusion rules plus calls [IModelExportHandler.shouldExportElement]($transformer) for any custom exclusion rules.
      * @note This method is called from within [[exportChanges]] and [[exportAll]], so usually does not need to be called directly.
      */
-    shouldExportElement(element) {
+    async shouldExportElement(element) {
         if (this._excludedElementIds.has(element.id)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${element.id} by Id`);
             return false;
         }
-        if (element instanceof core_backend_1.GeometricElement) {
-            if (this._excludedElementCategoryIds.has(element.category)) {
-                core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${element.id} by Category`);
-                return false;
-            }
+        if (element instanceof core_backend_1.GeometricElement &&
+            this._excludedElementCategoryIds.has(element.category)) {
+            core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${element.id} by Category`);
+            return false;
         }
         if (!this.wantTemplateModels &&
             element instanceof core_backend_1.RecipeDefinitionElement) {
@@ -608,28 +767,86 @@ class IModelExporter {
             }
         }
         // element has passed standard exclusion rules, now give handler a chance to accept/reject
-        return this.handler.shouldExportElement(element);
+        if (!(await this.handler.shouldExportElement(element))) {
+            return false;
+        }
+        return true;
     }
-    /** Export the specified element, its child elements (if applicable), and any owned ElementAspects.
+    /** Export the specified element and its child elements (if applicable).
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
+     * @note ElementAspects are exported separately in owner-scoped groups, so their callbacks are not guaranteed to follow this element callback.
      */
     async exportElement(elementId) {
+        return this.runScopedElementExport(async () => this.exportElementImpl(elementId));
+    }
+    async exportElementImpl(elementId) {
         if (!this.visitElements) {
             core_bentley_1.Logger.logTrace(loggerCategory, `visitElements=false, skipping exportElement(${elementId})`);
             return;
         }
-        // Return early if the elementId is already in the excludedElementIds, that way we don't need to load the element from the db.
+        const childVisit = await this.exportElementShallow(elementId);
+        if (childVisit === "visit")
+            return this.exportChildElements(elementId);
+        if (childVisit === "passThrough") {
+            // The element's own filter result is decided later, if a changed descendant is reached.
+            this._unchangedAncestors.push({ elementId });
+            try {
+                await this.exportChildElements(elementId);
+            }
+            finally {
+                this._unchangedAncestors.pop();
+            }
+        }
+    }
+    /** Returns the filter result for an unchanged ancestor on the current change-processing path, or `undefined` if it has not been filtered.
+     * @internal
+     */
+    getUnchangedAncestorFilterResult(elementId) {
+        return this._unchangedAncestors.find((ancestor) => ancestor.elementId === elementId)?.accepted;
+    }
+    /** Filters the unchanged ancestors of a changed element, top-down, once each.
+     * @returns `false` if an ancestor is rejected.
+     */
+    async acceptUnchangedAncestors() {
+        for (const ancestor of this._unchangedAncestors) {
+            if (ancestor.accepted === undefined) {
+                const element = this.sourceDb.elements.getElement({
+                    id: ancestor.elementId,
+                    wantGeometry: this.wantGeometry,
+                    wantBRepData: this.wantGeometry,
+                });
+                ancestor.accepted = await this.shouldExportElement(element);
+                if (!ancestor.accepted)
+                    await this.handler.onSkipElement(ancestor.elementId);
+            }
+            if (!ancestor.accepted)
+                return false;
+        }
+        return true;
+    }
+    /** Runs the export callbacks for a single element without visiting its children.
+     * @returns how to continue with the element's children: skip them, visit them, or pass through an unchanged element to reach changed descendants.
+     */
+    async exportElementShallow(elementId) {
+        // Descendants of a rejected unchanged ancestor are skipped, as in a full export.
+        if (this._unchangedAncestors.some((ancestor) => ancestor.accepted === false))
+            return "skip";
+        // Return early if the elementId is already excluded so it does not need to be loaded.
         if (this._excludedElementIds.has(elementId)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${elementId} by Id`);
-            this.handler.onSkipElement(elementId);
-            return;
+            await this.handler.onSkipElement(elementId);
+            return "skip";
         }
-        // are we processing changes?
         const isUpdate = this._sourceDbChanges?.element.insertIds.has(elementId)
             ? false
             : this._sourceDbChanges?.element.updateIds.has(elementId)
                 ? true
                 : undefined;
+        // An unchanged element may still connect a changed descendant to its model root.
+        if (this._sourceDbChanges !== undefined && isUpdate === undefined)
+            return "passThrough";
+        if (!(await this.acceptUnchangedAncestors()))
+            return "skip";
         const element = this.sourceDb.elements.getElement({
             id: elementId,
             wantGeometry: this.wantGeometry,
@@ -637,26 +854,41 @@ class IModelExporter {
         });
         core_bentley_1.Logger.logTrace(loggerCategory, `exportElement(${element.id}, "${element.getDisplayLabel()}")${this.getChangeOpSuffix(isUpdate)}`);
         // the order and `await`ing of calls beyond here is depended upon by the IModelTransformer for a current bug workaround
-        if (this.shouldExportElement(element)) {
+        if (await this.shouldExportElement(element)) {
             await this.handler.preExportElement(element);
             await this.handler.onExportElement(element, isUpdate);
             await this.trackProgress();
-            await this._exportElementAspectsStrategy.exportElementAspectsForElement(elementId);
-            return this.exportChildElements(elementId);
-        }
-        else {
-            this.handler.onSkipElement(element.id);
+            await this._elementAspectExportCoordinator.addAcceptedOwner(elementId);
+            return "visit";
         }
+        await this.handler.onSkipElement(element.id);
+        return "skip";
     }
     /** Export the child elements of the specified element from the source iModel.
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
      */
     async exportChildElements(elementId) {
+        return this.runScopedElementExport(async () => this.exportChildElementsImpl(elementId));
+    }
+    async exportChildElementsImpl(elementId) {
         if (!this.visitElements) {
             core_bentley_1.Logger.logTrace(loggerCategory, `visitElements=false, skipping exportChildElements(${elementId})`);
             return;
         }
-        const childElementIds = this.sourceDb.elements.queryChildren(elementId);
+        if (this.canUseSetBasedTraversal()) {
+            core_bentley_1.Logger.logTrace(loggerCategory, `exportChildElements(${elementId})`);
+            // Seed the stream with direct children; the helper adds their descendants.
+            return this.exportElementTreesStreamed(`SELECT e.ECInstanceId, 0 FROM ${core_backend_1.Element.classFullName} e WHERE e.Parent.Id=:parentId`, new core_common_1.QueryBinder().bindId("parentId", elementId));
+        }
+        let childElementIds;
+        if (this.canUseChangedElementForest()) {
+            const forest = await this.getChangedElementForest();
+            if (forest !== undefined) {
+                core_bentley_1.Logger.logTrace(loggerCategory, `exportChildElements(${elementId}) via changed-element index`);
+                childElementIds = forest.getChildren(elementId);
+            }
+        }
+        childElementIds ??= this.sourceDb.elements.queryChildren(elementId);
         if (childElementIds.length > 0) {
             core_bentley_1.Logger.logTrace(loggerCategory, `exportChildElements(${elementId})`);
             for (const childElementId of childElementIds) {
@@ -664,13 +896,282 @@ class IModelExporter {
             }
         }
     }
-    /** Exports all aspects present in the iModel.
+    /** Whether change processing may use the sparse hierarchy as the child-id source.
+     * Custom traversal overrides retain the previous full element dispatch.
      */
-    async exportAllAspects() {
-        return this._exportElementAspectsStrategy.exportAllElementAspects();
+    canUseChangedElementForest() {
+        return (this._sourceDbChanges !== undefined &&
+            this._changedElementTraversal?.useForest === true &&
+            this.hasDefaultElementTraversal());
+    }
+    getOverriddenElementTraversalMethods() {
+        const methods = [];
+        if (this.exportElement !== IModelExporter.prototype.exportElement)
+            methods.push("exportElement");
+        if (this.exportChildElements !== IModelExporter.prototype.exportChildElements)
+            methods.push("exportChildElements");
+        return methods;
+    }
+    disableChangedElementForest(reason) {
+        if (!this._changedElementTraversal?.useForest)
+            return;
+        this._changedElementTraversal.useForest = false;
+        core_bentley_1.Logger.logInfo(loggerCategory, `Using full element traversal for change processing because ${reason}.`);
+    }
+    async createChangedElementForest() {
+        (0, node_assert_1.strict)(this._sourceDbChanges !== undefined, "changed-element traversal requires sourceDbChanges");
+        const excludedElementIds = this._excludedElementIds;
+        const candidateCountUpperBound = this._sourceDbChanges.element.insertIds.size +
+            this._sourceDbChanges.element.updateIds.size +
+            excludedElementIds.size;
+        if (candidateCountUpperBound > this._changedElementForestElementLimit) {
+            this.disableChangedElementForest(`${candidateCountUpperBound} candidate element references exceed the ${this._changedElementForestElementLimit}-element in-memory index limit`);
+            return undefined;
+        }
+        const forest = await ChangedElementForest_1.ChangedElementForest.create(this.sourceDb, [
+            ...this._sourceDbChanges.element.insertIds,
+            ...this._sourceDbChanges.element.updateIds,
+            ...excludedElementIds,
+        ], this._changedElementForestElementLimit);
+        if (forest === undefined) {
+            this.disableChangedElementForest(`the required parent hierarchy exceeds the ${this._changedElementForestElementLimit}-element in-memory index limit`);
+        }
+        return forest;
+    }
+    async getChangedElementForest() {
+        const traversal = this._changedElementTraversal;
+        (0, node_assert_1.strict)(traversal !== undefined, "changed-element index requires an active traversal scope");
+        return (traversal.forest ??= this.createChangedElementForest());
+    }
+    /** Exports all aspects owned by the supplied elements. */
+    async exportAspectsForOwners(ownerElementIds) {
+        return this._elementAspectExportCoordinator.exportOwners(ownerElementIds);
+    }
+    async filterOwnerElementIdsForAspectExport(ownerElementIds) {
+        if (ownerElementIds.size === 0)
+            return new Set();
+        const elementFacts = await this.queryAspectElementHierarchyFacts(ownerElementIds);
+        const modelFacts = await this.queryAspectModelHierarchyFacts(new Set([...elementFacts.values()].map((elementFact) => elementFact.modelId)));
+        await this.queryAspectElementFacts(new Set(modelFacts.keys()), elementFacts);
+        const elementIds = new Set();
+        for (const elementId of ownerElementIds) {
+            if (this._skipPropagateChangesToRootElements &&
+                this._rootElementIds.has(elementId)) {
+                continue;
+            }
+            if (await this.shouldExportElementHierarchyForAspect(elementId, elementFacts, modelFacts)) {
+                elementIds.add(elementId);
+            }
+        }
+        return elementIds;
+    }
+    async shouldExportElementHierarchyForAspect(elementId, elementFacts, modelFacts) {
+        let elementFact = elementFacts.get(elementId);
+        while (elementFact !== undefined) {
+            if (!(await this.shouldExportElementForAspect(elementFact.id, elementFact)))
+                return false;
+            if (!(await this.shouldExportModelForAspect(elementFact.modelId, elementFacts, modelFacts))) {
+                return false;
+            }
+            const parentId = elementFact.parentId;
+            if (parentId === undefined ||
+                (this._skipPropagateChangesToRootElements &&
+                    parentId === core_common_1.IModel.rootSubjectId)) {
+                return true;
+            }
+            elementFact = elementFacts.get(parentId);
+        }
+        return false;
+    }
+    async shouldExportModelForAspect(modelId, elementFacts, modelFacts) {
+        const modelFact = modelFacts.get(modelId);
+        if (modelFact === undefined) {
+            this.sourceDb.models.getModel(modelId);
+            return false;
+        }
+        if (modelFact.isTemplate && !this.wantTemplateModels)
+            return false;
+        if (modelFact.id !== core_common_1.IModel.repositoryModelId &&
+            modelFact.id !== core_common_1.IModel.dictionaryId &&
+            modelFact.id !== "0xe" &&
+            !(await this.shouldExportElementForAspect(modelFact.id, elementFacts.get(modelFact.id)))) {
+            return false;
+        }
+        if (modelFact.parentModelId === undefined ||
+            modelFact.parentModelId === modelFact.id) {
+            return true;
+        }
+        return this.shouldExportModelForAspect(modelFact.parentModelId, elementFacts, modelFacts);
+    }
+    beginChangedElementTraversalScope() {
+        if (this._sourceDbChanges === undefined ||
+            this._changedElementTraversal !== undefined) {
+            return false;
+        }
+        this._changedElementTraversal = { useForest: true };
+        const overriddenMethods = this.getOverriddenElementTraversalMethods();
+        if (this.visitElements && overriddenMethods.length > 0) {
+            this.disableChangedElementForest(`${overriddenMethods.join(" and ")} ${overriddenMethods.length === 1 ? "is" : "are"} overridden by the exporter subclass`);
+        }
+        return true;
+    }
+    endChangedElementTraversalScope() {
+        this._changedElementTraversal = undefined;
+    }
+    async runScopedElementExport(exportElements) {
+        const ownsChangedElementTraversal = this.beginChangedElementTraversalScope();
+        try {
+            await this._elementAspectExportCoordinator.run(exportElements);
+        }
+        finally {
+            if (ownsChangedElementTraversal)
+                this.endChangedElementTraversalScope();
+        }
+    }
+    /** Apply the element export filter when deciding whether to process an aspect owner. @internal */
+    async shouldExportElementForAspect(elementId, elementFact) {
+        if (!this.visitElements)
+            return false;
+        if (this.shouldExportElement ===
+            IModelExporter.prototype.shouldExportElement &&
+            elementFact !== undefined &&
+            !this.shouldExportElementFact(elementFact)) {
+            return false;
+        }
+        const element = this.sourceDb.elements.getElement({
+            id: elementId,
+            wantGeometry: false,
+            wantBRepData: false,
+        });
+        return this.shouldExportElement(element);
+    }
+    shouldExportElementFact(elementFact) {
+        if (this._excludedElementIds.has(elementFact.id)) {
+            core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${elementFact.id} by Id`);
+            return false;
+        }
+        const elementClass = this.sourceDb.getJsClass(elementFact.classFullName);
+        if ((elementFact.classFullName === core_backend_1.GeometricElement.classFullName ||
+            elementClass.prototype instanceof core_backend_1.GeometricElement) &&
+            elementFact.categoryId !== undefined &&
+            this._excludedElementCategoryIds.has(elementFact.categoryId)) {
+            core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${elementFact.id} by Category`);
+            return false;
+        }
+        if (!this.wantTemplateModels &&
+            (elementFact.classFullName === core_backend_1.RecipeDefinitionElement.classFullName ||
+                elementClass.prototype instanceof core_backend_1.RecipeDefinitionElement)) {
+            core_bentley_1.Logger.logInfo(loggerCategory, `Excluded RecipeDefinitionElement ${elementFact.id} because wantTemplate=false`);
+            return false;
+        }
+        for (const excludedElementClass of this._excludedElementClasses) {
+            if (elementFact.classFullName === excludedElementClass.classFullName ||
+                elementClass.prototype instanceof excludedElementClass) {
+                core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${elementFact.id} by class: ${excludedElementClass.classFullName}`);
+                return false;
+            }
+        }
+        return true;
+    }
+    async queryAspectElementHierarchyFacts(elementIds) {
+        const elementFacts = new Map();
+        const queriedElementIds = new Set();
+        let pendingElementIds = new Set(elementIds);
+        while (pendingElementIds.size > 0) {
+            const currentElementIds = pendingElementIds;
+            pendingElementIds = new Set();
+            await this.queryAspectElementFacts(currentElementIds, elementFacts);
+            for (const elementId of currentElementIds)
+                queriedElementIds.add(elementId);
+            for (const elementId of currentElementIds) {
+                const parentId = elementFacts.get(elementId)?.parentId;
+                if (parentId !== undefined &&
+                    !queriedElementIds.has(parentId) &&
+                    !elementFacts.has(parentId)) {
+                    pendingElementIds.add(parentId);
+                }
+            }
+        }
+        return elementFacts;
+    }
+    async queryAspectElementFacts(elementIds, elementFacts) {
+        const unqueriedElementIds = new Set([...elementIds].filter((elementId) => !elementFacts.has(elementId)));
+        if (unqueriedElementIds.size === 0)
+            return;
+        for (const elementIdBatch of this.getAspectOwnerIdBatches(unqueriedElementIds)) {
+            const queryParams = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIdBatch);
+            for await (const row of this.sourceDb.createQueryReader(`SELECT e.ECInstanceId id, e.Parent.Id parentId, e.Model.Id modelId,
+                ec_className(e.ECClassId, 's') schemaName,
+                ec_className(e.ECClassId, 'c') className
+         FROM bis.Element e
+         INNER JOIN IdSet(:elementIds) ids ON ids.id = e.ECInstanceId`, queryParams, { usePrimaryConn: true })) {
+                elementFacts.set(row.id, {
+                    id: row.id,
+                    parentId: row.parentId ?? undefined,
+                    modelId: row.modelId,
+                    classFullName: `${row.schemaName}:${row.className}`,
+                });
+            }
+            if (this._excludedElementCategoryIds.size > 0) {
+                const categoryQueryParams = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIdBatch);
+                for await (const row of this.sourceDb.createQueryReader(`SELECT g.ECInstanceId id, g.Category.Id categoryId
+           FROM bis.GeometricElement g
+           INNER JOIN IdSet(:elementIds) ids ON ids.id = g.ECInstanceId`, categoryQueryParams, { usePrimaryConn: true })) {
+                    const elementFact = elementFacts.get(row.id);
+                    if (elementFact !== undefined) {
+                        elementFact.categoryId = row.categoryId;
+                    }
+                }
+            }
+        }
+    }
+    async queryAspectModelHierarchyFacts(modelIds) {
+        const modelFacts = new Map();
+        const queriedModelIds = new Set();
+        let pendingModelIds = new Set(modelIds);
+        while (pendingModelIds.size > 0) {
+            const currentModelIds = pendingModelIds;
+            pendingModelIds = new Set();
+            for (const modelIdBatch of this.getAspectOwnerIdBatches(currentModelIds)) {
+                const queryParams = new core_common_1.QueryBinder().bindIdSet("modelIds", modelIdBatch);
+                for await (const row of this.sourceDb.createQueryReader(`SELECT model.ECInstanceId id, model.ParentModel.Id parentModelId, model.IsTemplate isTemplate
+           FROM bis.Model model
+           INNER JOIN IdSet(:modelIds) ids ON ids.id = model.ECInstanceId`, queryParams, { usePrimaryConn: true })) {
+                    modelFacts.set(row.id, {
+                        id: row.id,
+                        parentModelId: row.parentModelId ?? undefined,
+                        isTemplate: row.isTemplate === true || row.isTemplate === 1,
+                    });
+                }
+            }
+            for (const modelId of currentModelIds)
+                queriedModelIds.add(modelId);
+            for (const modelId of currentModelIds) {
+                const parentModelId = modelFacts.get(modelId)?.parentModelId;
+                if (parentModelId !== undefined &&
+                    !queriedModelIds.has(parentModelId) &&
+                    !modelFacts.has(parentModelId)) {
+                    pendingModelIds.add(parentModelId);
+                }
+            }
+        }
+        return modelFacts;
+    }
+    *getAspectOwnerIdBatches(ids) {
+        let batch = new Set();
+        for (const id of ids) {
+            batch.add(id);
+            if (batch.size === IModelExporter._elementAspectOwnerBatchSize) {
+                yield batch;
+                batch = new Set();
+            }
+        }
+        if (batch.size > 0)
+            yield batch;
     }
     /** Exports all relationships that subclass from the specified base class.
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
+     * @note This is the bulk traversal path. It hydrates relationships with one streaming query and calls [[exportRelationshipInstance]] directly; it does not call [[exportRelationship]] once per row.
      */
     async exportRelationships(baseRelClassFullName) {
         if (!this.visitRelationships) {
@@ -678,39 +1179,154 @@ class IModelExporter {
             return;
         }
         core_bentley_1.Logger.logTrace(loggerCategory, `exportRelationships(${baseRelClassFullName})`);
-        const sql = `SELECT r.ECInstanceId, ec_className(r.ECClassId, 's.c') as ClassName FROM ${baseRelClassFullName} r
-                  JOIN bis.Element s ON s.ECInstanceId = r.SourceECInstanceId
-                  JOIN bis.Element t ON t.ECInstanceId = r.TargetECInstanceId
-                  WHERE s.ECInstanceId IS NOT NULL AND t.ECInstanceId IS NOT NULL`;
-        for await (const row of this.sourceDb.createQueryReader(sql)) {
-            const relationshipId = row.ecinstanceid;
-            const relationshipClass = row.classname;
-            await this.exportRelationship(relationshipClass, relationshipId); // must call exportRelationship using the actual classFullName, not baseRelClassFullName
-            await this._yieldManager.allowYield();
+        const changedRelationshipIds = this._sourceDbChanges === undefined
+            ? undefined
+            : new Set([
+                ...this._sourceDbChanges.relationship.insertIds,
+                ...this._sourceDbChanges.relationship.updateIds,
+            ]);
+        if (changedRelationshipIds?.size === 0) {
+            // Deleted relationships are handled by exportChanges after this traversal; they are no
+            // longer present in the source iModel and must not cause a full relationship scan here.
+            core_bentley_1.Logger.logTrace(loggerCategory, "No inserted or updated relationships, skipping exportRelationships()");
+            return;
+        }
+        const changedRelationshipJoin = changedRelationshipIds === undefined
+            ? undefined
+            : "INNER JOIN IdSet(:changedRelationshipIds) changed ON changed.id = r.ECInstanceId";
+        const relationshipWhereClause = "s.ECInstanceId IS NOT NULL AND t.ECInstanceId IS NOT NULL";
+        // Bound the async reader's retained raw rows while preserving batched query throughput.
+        // Keyset pagination avoids rescanning rows returned by earlier batches.
+        const relationshipQueryBatchSize = 1000;
+        let lastRelationshipId;
+        while (true) {
+            let rowsRead = 0;
+            const whereClause = lastRelationshipId === undefined
+                ? relationshipWhereClause
+                : `${relationshipWhereClause} AND r.ECInstanceId > :lastRelationshipId`;
+            // QueryBinder parameters are immutable after binding a name. Recreate the binder for each
+            // keyset page so the changing boundary can be bound without redefining a property.
+            const queryParams = changedRelationshipIds === undefined && lastRelationshipId === undefined
+                ? undefined
+                : new core_common_1.QueryBinder();
+            if (queryParams !== undefined) {
+                if (changedRelationshipIds !== undefined) {
+                    queryParams.bindIdSet("changedRelationshipIds", changedRelationshipIds);
+                }
+                if (lastRelationshipId !== undefined) {
+                    queryParams.bindId("lastRelationshipId", lastRelationshipId);
+                }
+            }
+            const reader = this.sourceDb.createQueryReader(this.getRelationshipQuery(baseRelClassFullName, "JOIN", whereClause, changedRelationshipJoin), queryParams, {
+                usePrimaryConn: true,
+                limit: { count: relationshipQueryBatchSize },
+            });
+            for await (const row of reader) {
+                rowsRead++;
+                const relInstanceId = row.relInstanceId;
+                lastRelationshipId = relInstanceId;
+                const changesetFilter = this.checkRelationshipChangesetFilter(relInstanceId);
+                if (changesetFilter.skip) {
+                    await this._yieldManager.allowYield();
+                    continue;
+                }
+                await this.exportHydratedRelationship(row.rawInstance, row.sourceFedGuid, row.targetFedGuid, changesetFilter.isUpdate);
+                await this._yieldManager.allowYield();
+            }
+            if (rowsRead < relationshipQueryBatchSize)
+                break;
         }
     }
-    /** Export a relationship from the source iModel. */
+    /** Builds the raw relationship query used by the bulk and targeted export paths. */
+    getRelationshipQuery(relClassFullName, endpointJoin, whereClause, relationshipJoin) {
+        return `SELECT r.$ AS rawInstance, r.ECInstanceId AS relInstanceId, s.FederationGuid AS sourceFedGuid, t.FederationGuid AS targetFedGuid FROM ${relClassFullName} r
+                  ${relationshipJoin ?? ""}
+                  ${endpointJoin} bis.Element s ON s.ECInstanceId = r.SourceECInstanceId
+                  ${endpointJoin} bis.Element t ON t.ECInstanceId = r.TargetECInstanceId
+                  WHERE ${whereClause}
+                  ORDER BY r.ECInstanceId
+                  OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`;
+    }
+    /** Applies the changeset filter (when exporting changes) to a relationship instance id.
+     * @returns whether to skip the relationship, and whether the export is an update.
+     */
+    checkRelationshipChangesetFilter(relInstanceId) {
+        if (undefined === this._sourceDbChanges)
+            return { skip: false, isUpdate: undefined };
+        if (this._sourceDbChanges.relationship.insertIds.has(relInstanceId))
+            return { skip: false, isUpdate: false };
+        if (this._sourceDbChanges.relationship.updateIds.has(relInstanceId))
+            return { skip: false, isUpdate: true };
+        return { skip: true, isUpdate: undefined }; // not in changeset, don't export
+    }
+    /** Converts a raw `$` instance-access row into [RelationshipProps]($common). */
+    getRelationshipProps(rawInstance) {
+        const parsedRow = typeof rawInstance === "string"
+            ? JSON.parse(rawInstance, core_common_1.Base64EncodedString.reviver)
+            : rawInstance;
+        if (!core_bentley_1.JsonUtils.isObject(parsedRow))
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidRelationshipData,
+                },
+                message: "Expected a Relationship 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[core_common_1.ECJsNames.toJsName(ecPropertyName)] = value;
+        }
+        const className = row.className;
+        if (typeof className !== "string")
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidRelationshipData,
+                },
+                message: "Expected a Relationship instance query to return a className",
+            });
+        row.classFullName = className.replace(".", ":");
+        delete row.className;
+        delete row.sourceClassName;
+        delete row.targetClassName;
+        return row;
+    }
+    /** Export one specified relationship from the source iModel.
+     * @note This targeted path is separate from [[exportRelationships]], which traverses a class hierarchy. It uses the same raw instance query and passes endpoint FederationGuids to the handler.
+     */
     async exportRelationship(relClassFullName, relInstanceId) {
         if (!this.visitRelationships) {
             core_bentley_1.Logger.logTrace(loggerCategory, `visitRelationships=false, skipping exportRelationship(${relClassFullName}, ${relInstanceId})`);
             return;
         }
-        let isUpdate;
-        if (undefined !== this._sourceDbChanges) {
-            // is changeset information available?
-            if (this._sourceDbChanges.relationship.insertIds.has(relInstanceId)) {
-                isUpdate = false;
-            }
-            else if (this._sourceDbChanges.relationship.updateIds.has(relInstanceId)) {
-                isUpdate = true;
-            }
-            else {
-                return; // not in changeset, don't export
-            }
+        const changesetFilter = this.checkRelationshipChangesetFilter(relInstanceId);
+        if (changesetFilter.skip)
+            return;
+        const queryParams = new core_common_1.QueryBinder().bindId("relInstanceId", relInstanceId);
+        const reader = this.sourceDb.createQueryReader(this.getRelationshipQuery(relClassFullName, "LEFT JOIN", "r.ECInstanceId = :relInstanceId"), queryParams, { usePrimaryConn: true });
+        if (await reader.step()) {
+            const row = reader.current;
+            await this.exportHydratedRelationship(row.rawInstance, row.sourceFedGuid, row.targetFedGuid, changesetFilter.isUpdate);
+            return;
         }
-        // passed changeset test, now apply standard exclusion rules
-        core_bentley_1.Logger.logTrace(loggerCategory, `exportRelationship(${relClassFullName}, ${relInstanceId})`);
+        // Preserve the previous not-found behavior if the targeted query returned no row.
         const relationship = this.sourceDb.relationships.getInstance(relClassFullName, relInstanceId);
+        await this.exportRelationshipInstance(relationship, changesetFilter.isUpdate, this.sourceDb.elements.getFederationGuidFromId(relationship.sourceId), this.sourceDb.elements.getFederationGuidFromId(relationship.targetId));
+    }
+    /** Hydrates a relationship query row and runs the common export pipeline. */
+    async exportHydratedRelationship(rawInstance, sourceFedGuid, targetFedGuid, isUpdate) {
+        const relationship = this.sourceDb.constructEntity(this.getRelationshipProps(rawInstance));
+        await this.exportRelationshipInstance(relationship, isUpdate, sourceFedGuid ?? undefined, targetFedGuid ?? undefined);
+    }
+    /** Applies exclusion rules and handler callbacks to an already-hydrated relationship instance.
+     * @param sourceFedGuid The FederationGuid of the relationship's source endpoint, if available.
+     * @param targetFedGuid The FederationGuid of the relationship's target endpoint, if available.
+     * @note This is the common protected hook used by both [[exportRelationship]] and [[exportRelationships]]. Most consumers should customize [[IModelExportHandler]] instead.
+     */
+    async exportRelationshipInstance(relationship, isUpdate, sourceFedGuid, targetFedGuid) {
+        // passed changeset test, now apply standard exclusion rules
+        core_bentley_1.Logger.logTrace(loggerCategory, `exportRelationship(${relationship.classFullName}, ${relationship.id})`);
         for (const excludedRelationshipClass of this._excludedRelationshipClasses) {
             if (relationship instanceof excludedRelationshipClass) {
                 core_bentley_1.Logger.logInfo(loggerCategory, `Excluded relationship by class: ${excludedRelationshipClass.classFullName}`);
@@ -718,8 +1334,8 @@ class IModelExporter {
             }
         }
         // relationship has passed standard exclusion rules, now give handler a chance to accept/reject export
-        if (this.handler.shouldExportRelationship(relationship)) {
-            await this.handler.onExportRelationship(relationship, isUpdate);
+        if (await this.handler.shouldExportRelationship(relationship)) {
+            await this.handler.onExportRelationship(relationship, isUpdate, sourceFedGuid, targetFedGuid);
             await this.trackProgress();
         }
     }
@@ -772,62 +1388,18 @@ class ChangedInstanceIds {
     aspect = new ChangedInstanceOps();
     relationship = new ChangedInstanceOps();
     font = new ChangedInstanceOps();
-    _codeSpecSubclassIds;
-    _modelSubclassIds;
-    _elementSubclassIds;
-    _aspectSubclassIds;
-    _relationshipSubclassIds;
-    _relationshipSubclassIdsToSkip;
+    _classKinds;
+    _aspectOwnerElementIds = new Set();
+    /** Element IDs that own the aspects represented by `aspect` changes.
+     * @internal
+     */
+    get aspectOwnerElementIds() {
+        return this._aspectOwnerElementIds;
+    }
     _db;
     constructor(db) {
         this._db = db;
     }
-    async setupECClassIds() {
-        this._codeSpecSubclassIds = new Set();
-        this._modelSubclassIds = new Set();
-        this._elementSubclassIds = new Set();
-        this._aspectSubclassIds = new Set();
-        this._relationshipSubclassIds = new Set();
-        this._relationshipSubclassIdsToSkip = new Set();
-        const addECClassIdsToSet = async (setToModify, baseClass) => {
-            for await (const row of this._db.createQueryReader(`SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (${baseClass})`)) {
-                setToModify.add(row.ECInstanceId);
-            }
-        };
-        const promises = [
-            addECClassIdsToSet(this._codeSpecSubclassIds, "BisCore.CodeSpec"),
-            addECClassIdsToSet(this._modelSubclassIds, "BisCore.Model"),
-            addECClassIdsToSet(this._elementSubclassIds, "BisCore.Element"),
-            addECClassIdsToSet(this._aspectSubclassIds, "BisCore.ElementUniqueAspect"),
-            addECClassIdsToSet(this._aspectSubclassIds, "BisCore.ElementMultiAspect"),
-            addECClassIdsToSet(this._relationshipSubclassIds, "BisCore.ElementRefersToElements"),
-            addECClassIdsToSet(this._relationshipSubclassIdsToSkip, "BisCore.ElementDrivesElement"),
-        ];
-        await Promise.all(promises);
-    }
-    get _ecClassIdsInitialized() {
-        return (this._codeSpecSubclassIds &&
-            this._modelSubclassIds &&
-            this._elementSubclassIds &&
-            this._aspectSubclassIds &&
-            this._relationshipSubclassIds &&
-            this._relationshipSubclassIdsToSkip);
-    }
-    isRelationship(ecClassId) {
-        return this._relationshipSubclassIds?.has(ecClassId);
-    }
-    isCodeSpec(ecClassId) {
-        return this._codeSpecSubclassIds?.has(ecClassId);
-    }
-    isAspect(ecClassId) {
-        return this._aspectSubclassIds?.has(ecClassId);
-    }
-    isModel(ecClassId) {
-        return this._modelSubclassIds?.has(ecClassId);
-    }
-    isElement(ecClassId) {
-        return this._elementSubclassIds?.has(ecClassId);
-    }
     /** Checks if there are any changes.
      * @returns true if there are any changes in the ChangedInstanceIds object.
      */
@@ -840,32 +1412,105 @@ class ChangedInstanceIds {
             !this.font.isEmpty);
     }
     /**
-     * Adds the provided [[ChangedECInstance]] to the appropriate set of changes by class type (codeSpec, model, element, aspect, or relationship) maintained by this instance of ChangedInstanceIds.
+     * Adds the provided [[ChangeInstance]] to the appropriate set of changes by class type (codeSpec, model, element, aspect, or relationship) maintained by this instance of ChangedInstanceIds.
      * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
      * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
-     * @param change ChangedECInstance which has the ECInstanceId, changeType (insert, update, delete) and ECClassId of the changed entity
+     * @param change Changed EC instance with the ID, operation, and EC class ID of the changed entity.
      */
     async addChange(change) {
-        if (!this._ecClassIdsInitialized)
-            await this.setupECClassIds();
-        const ecClassId = change.ECClassId ?? change.$meta?.fallbackClassId;
+        return this.recordChange(change, undefined);
+    }
+    /**
+     * Adds a change read from somewhere other than a changeset, such as a precomputed cache, like [[addChange]]
+     * does for a changeset reader's [ChangeInstance]($backend). Add changes in the order they were made, so that,
+     * for example, an insert followed by a delete of the same instance cancels out.
+     * @throws [ITwinError]($bentley) with key `AspectOwnerRequired` if a deleted aspect has no `aspectOwnerElementId`.
+     * @beta
+     */
+    async addChangeRecord(change) {
+        if (change.op === "Deleted" && change.aspectOwnerElementId === undefined) {
+            this._classKinds ??= await SourceClassKinds_1.SourceClassKinds.query(this._db);
+            const kind = this._classKinds.kindOf(change.ecClassId);
+            // The source no longer has the aspect, so without its owner the target aspect would silently stay.
+            if (kind === "aspect" || kind === "externalSourceAspect")
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.AspectOwnerRequired,
+                    },
+                    message: `Deleted ElementAspect change ${change.id} requires the owning element ID.`,
+                });
+        }
+        return this.applyChangeRecord(change, undefined);
+    }
+    async recordChange(change, unresolvedAspectIds) {
+        const ecClassId = change.ECClassId;
         if (ecClassId === undefined)
-            throw new Error(`ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`);
-        const changeType = change.$meta?.op;
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                },
+                message: `ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change.$meta.tables}`,
+            });
+        const changeType = change.$meta.op;
         if (changeType === undefined)
-            throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
-        if (this._relationshipSubclassIdsToSkip?.has(ecClassId))
-            return;
-        if (this.isRelationship(ecClassId))
-            this.handleChange(this.relationship, changeType, change.ECInstanceId);
-        else if (this.isCodeSpec(ecClassId))
-            this.handleChange(this.codeSpec, changeType, change.ECInstanceId);
-        else if (this.isAspect(ecClassId))
-            this.handleChange(this.aspect, changeType, change.ECInstanceId);
-        else if (this.isModel(ecClassId))
-            this.handleChange(this.model, changeType, change.ECInstanceId);
-        else if (this.isElement(ecClassId))
-            this.handleChange(this.element, changeType, change.ECInstanceId);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                },
+                message: `ChangeType was undefined for id: ${change.ECInstanceId}.`,
+            });
+        return this.applyChangeRecord({
+            id: change.ECInstanceId,
+            ecClassId,
+            op: changeType,
+            aspectOwnerElementId: change.Element?.Id,
+        }, unresolvedAspectIds);
+    }
+    async applyChangeRecord(change, unresolvedAspectIds) {
+        // Await only the first time, so later changes are classified without yielding.
+        this._classKinds ??= await SourceClassKinds_1.SourceClassKinds.query(this._db);
+        const { id, ecClassId, op } = change;
+        switch (this._classKinds.kindOf(ecClassId)) {
+            case "relationship":
+                return this.handleChange(this.relationship, op, id);
+            case "codeSpec":
+                return this.handleChange(this.codeSpec, op, id);
+            case "aspect":
+            case "externalSourceAspect": {
+                let ownerElementId = change.aspectOwnerElementId;
+                if (ownerElementId === undefined) {
+                    if (unresolvedAspectIds !== undefined)
+                        unresolvedAspectIds.add(id);
+                    else
+                        ownerElementId = this.tryGetAspectOwnerElementId(id);
+                }
+                if (ownerElementId !== undefined)
+                    this._aspectOwnerElementIds.add(ownerElementId);
+                return this.handleChange(this.aspect, op, id);
+            }
+            case "model":
+                return this.handleChange(this.model, op, id);
+            case "element":
+                return this.handleChange(this.element, op, id);
+            case "skippedRelationship":
+            case undefined:
+                return;
+        }
+    }
+    tryGetAspectOwnerElementId(aspectId) {
+        try {
+            return this._db.elements.getAspect(aspectId).element.id;
+        }
+        catch (error) {
+            if (error instanceof core_common_1.IModelError &&
+                error.errorNumber === core_bentley_1.IModelStatus.NotFound) {
+                return undefined;
+            }
+            throw error;
+        }
     }
     /**
      * This method should only be called inside [[IModelTransformer.addCustomChanges]].
@@ -928,14 +1573,47 @@ class ChangedInstanceIds {
      * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
      * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
      * @note It is the responsibility of the caller to ensure that the provided id is, in fact an aspect.
+     * @param elementIds Owning element IDs. Required when `changeType` is
+     *        `Deleted` or the source aspect row is unavailable.
      * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
      * @beta
      */
-    addCustomAspectChange(changeType, ids) {
+    addCustomAspectChange(changeType, ids, elementIds) {
+        if (elementIds !== undefined) {
+            for (const elementId of core_bentley_1.Id64.iterable(elementIds)) {
+                this._aspectOwnerElementIds.add(elementId);
+            }
+        }
         for (const id of core_bentley_1.Id64.iterable(ids)) {
+            if (elementIds === undefined && changeType === "Deleted") {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.AspectOwnerRequired,
+                    },
+                    message: "Custom deleted ElementAspect changes require the owning element ID.",
+                });
+            }
+            if (elementIds === undefined && changeType !== "Deleted") {
+                const ownerElementId = this.tryGetAspectOwnerElementId(id);
+                if (ownerElementId === undefined) {
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.AspectOwnerRequired,
+                        },
+                        message: "Custom ElementAspect changes require the owning element ID when the source aspect is unavailable.",
+                    });
+                }
+                this._aspectOwnerElementIds.add(ownerElementId);
+            }
             this.handleChange(this.aspect, changeType, id);
         }
     }
+    recordCustomAspectChange(changeType, aspectId, ownerElementId) {
+        this._aspectOwnerElementIds.add(ownerElementId);
+        this.handleChange(this.aspect, changeType, aspectId);
+    }
     /**
      * There is an optimization in [IModelExporter.exportModelContents] which doesn't try to export elements within a model unless the model itself is marked as `Updated` or 'Inserted' in sourceDbChanges. This method is used in [[addCustomElementChange]] and [[addCustomModelChange]] to add the parent model hierarchy to the 'updatedIds' so that the custom element changes are exported.
      * Transformer will insert 'Updated' model to target if it does not exist there already. To handle such case, modeled elements of parent models are also marked as updated. This is done, because model can not be inserted without it's modeled element.
@@ -944,7 +1622,9 @@ class ChangedInstanceIds {
         const params = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIds);
         const ecQuery = `
     WITH RECURSIVE hierarchy (parentId) AS (
-        SELECT Model.Id FROM bis.Element WHERE InVirtualSet(:elementIds, ECInstanceId)
+        SELECT element.Model.Id
+        FROM bis.Element element
+        INNER JOIN IdSet(:elementIds) ids ON ids.id = element.ECInstanceId
         UNION
         SELECT ParentModel.id
         FROM bis.Model e
@@ -953,7 +1633,9 @@ class ChangedInstanceIds {
         SELECT parentId FROM hierarchy where parentId is not null
     `;
         const parentModelIds = new Set();
-        for await (const row of this._db.createQueryReader(ecQuery, params)) {
+        for await (const row of this._db.createQueryReader(ecQuery, params, {
+            usePrimaryConn: true,
+        })) {
             // Transformer handles update as insert when element does not exist in target.
             // Which means that in scenario where child and parent model are filtered out from target,
             // and child element is inserted trough custom change, its parent model will be marked as updated.
@@ -967,11 +1649,19 @@ class ChangedInstanceIds {
         return parentModelIds;
     }
     async markElementRelationshipsAsInserted(relationshipClassName, elementIds) {
-        const ecQuery = `SELECT ECInstanceId FROM ${relationshipClassName}
-        WHERE InVirtualSet(:elementIds, TargetECInstanceId)
-        OR InVirtualSet(:elementIds, SourceECInstanceId)`;
+        const ecQuery = `SELECT relationship.ECInstanceId
+        FROM ${relationshipClassName} relationship
+        INNER JOIN IdSet(:elementIds) ids
+          ON ids.id = relationship.TargetECInstanceId
+        UNION
+        SELECT relationship.ECInstanceId
+        FROM ${relationshipClassName} relationship
+        INNER JOIN IdSet(:elementIds) ids
+          ON ids.id = relationship.SourceECInstanceId`;
         const queryBinder = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIds);
-        const queryReader = this._db.createQueryReader(ecQuery, queryBinder);
+        const queryReader = this._db.createQueryReader(ecQuery, queryBinder, {
+            usePrimaryConn: true,
+        });
         for await (const row of queryReader) {
             this.handleChange(this.relationship, "Inserted", row.ECInstanceId);
         }
@@ -981,11 +1671,16 @@ class ChangedInstanceIds {
             core_backend_1.ElementUniqueAspect.classFullName,
             core_backend_1.ElementMultiAspect.classFullName,
         ]) {
-            const ecQuery = `Select ECInstanceId from ${aspectClassName} where InVirtualSet(:elementIds, Element.Id)`;
+            const ecQuery = `SELECT aspect.ECInstanceId, aspect.Element.Id
+        FROM ${aspectClassName} aspect
+        INNER JOIN IdSet(:elementIds) ids ON ids.id = aspect.Element.Id`;
             const queryBinder = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIds);
-            const queryReader = this._db.createQueryReader(ecQuery, queryBinder);
+            const queryReader = this._db.createQueryReader(ecQuery, queryBinder, {
+                usePrimaryConn: true,
+            });
             for await (const row of queryReader) {
-                this.addCustomAspectChange("Inserted", row.toArray()[0]);
+                const [aspectId, elementId] = row.toArray();
+                this.recordCustomAspectChange("Inserted", aspectId, elementId);
             }
         }
     }
@@ -1041,36 +1736,40 @@ class ChangedInstanceIds {
                 ? opts.changesetRanges
                 : undefined;
         const csFileProps = changesetRanges !== undefined
-            ? (await Promise.all(changesetRanges.map(async ([first, end]) => core_backend_1.BriefcaseManager.downloadChangesets({
-                iModelId,
-                range: { first, end },
-                targetDir: core_backend_1.BriefcaseManager.getChangeSetsPath(iModelId),
-            })))).flat()
+            ? (await ChangesetScanner_1.ChangesetScanner.download(opts.iModel, changesetRanges)).flat()
             : "csFileProps" in opts
                 ? opts.csFileProps
                 : undefined;
         if (csFileProps === undefined)
             return undefined;
         const changedInstanceIds = new ChangedInstanceIds(opts.iModel);
-        for (const csFile of csFileProps) {
-            const csReader = core_backend_1.SqliteChangesetReader.openFile({
-                fileName: csFile.pathname,
-                db: opts.iModel,
-                disableSchemaCheck: true,
-            });
-            const csAdaptor = new core_backend_1.ChangesetECAdaptor(csReader);
-            const ecChangeUnifier = new core_backend_1.PartialECChangeUnifier(opts.iModel);
-            while (csAdaptor.step()) {
-                ecChangeUnifier.appendFrom(csAdaptor);
-            }
-            const changes = [...ecChangeUnifier.instances];
-            for (const change of changes) {
-                await changedInstanceIds.addChange(change);
-            }
-            csReader.close();
-        }
+        await ChangesetScanner_1.ChangesetScanner.scan(opts.iModel, [csFileProps], {
+            changedInstanceIds,
+            collectDeletionRecords: false,
+        });
         return changedInstanceIds;
     }
+    /** Record an ordered batch, then resolve missing aspect owners against current source state.
+     * @internal
+     */
+    async addChanges(changes) {
+        const unresolvedAspectIds = new Set();
+        for (const change of changes)
+            await this.recordChange(change, unresolvedAspectIds);
+        // Only resolve missing owners from current source state. Changeset-provided
+        // owners, including historical owners, were retained while recording changes.
+        if (unresolvedAspectIds.size > 0) {
+            this._db.withQueryReader(`WITH AspectIds AS (SELECT id FROM IdSet(:aspectIds))
+         SELECT Element.Id FROM BisCore.ElementMultiAspect
+         WHERE ECInstanceId IN (SELECT id FROM AspectIds)
+         UNION ALL
+         SELECT Element.Id FROM BisCore.ElementUniqueAspect
+         WHERE ECInstanceId IN (SELECT id FROM AspectIds)`, (reader) => {
+                while (reader.step())
+                    this._aspectOwnerElementIds.add(reader.current[0]);
+            }, new core_common_1.QueryBinder().bindIdSet("aspectIds", unresolvedAspectIds));
+        }
+    }
 }
 exports.ChangedInstanceIds = ChangedInstanceIds;
 //# sourceMappingURL=IModelExporter.js.map