@itwin/imodel-transformer 2.0.0-dev.5 → 2.0.0-dev.50

package/lib/cjs/IModelExporter.js

@@ -13,8 +13,11 @@ 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 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 +29,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,37 +37,37 @@ 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. */
-    onDeleteModel(_modelId) { }
+    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`.
      */
-    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.
      */
-    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.
      * @note This should be overridden to actually do the export.
      */
-    onExportElement(_element, _isUpdate) { }
+    async onExportElement(_element, _isUpdate) { }
     /**
      * Do any asynchronous actions before exporting an element
      * @note Do not implement this handler manually, it is internal, it will be removed.
@@ -73,11 +76,11 @@ class IModelExportHandler {
      */
     async preExportElement(_element) { }
     /** Called when an element should be deleted. */
-    onDeleteElement(_elementId) { }
+    async onDeleteElement(_elementId) { }
     /** 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.
@@ -85,29 +88,31 @@ 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.
      */
-    onExportElementUniqueAspect(_aspect, _isUpdate) { }
+    async onExportElementUniqueAspect(_aspect, _isUpdate) { }
     /** Called when ElementMultiAspects should be exported.
      * @note This should be overridden to actually do the export.
      */
-    onExportElementMultiAspects(_aspects) { }
+    async onExportElementMultiAspects(_aspects) { }
     /** 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.
      */
-    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 +131,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.
@@ -175,7 +184,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 +204,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, {
-            onExportElementMultiAspects: (aspects) => this.handler.onExportElementMultiAspects(aspects),
-            onExportElementUniqueAspect: (aspect, isUpdate) => this.handler.onExportElementUniqueAspect(aspect, isUpdate),
-            shouldExportElementAspect: (aspect) => this.handler.shouldExportElementAspect(aspect),
+        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: 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 +252,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) {
@@ -244,7 +276,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 +289,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,35 +302,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);
+        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);
         }
-        else {
-            await this.exportModel(core_common_1.IModel.repositoryModelId);
+        for (const elementId of this._sourceDbChanges.element.updateIds) {
+            aspectOnlyOwnerElementIds.delete(elementId);
         }
-        await this.exportAllAspects();
+        await this.exportAspectsForOwners(await this.filterOwnerElementIdsForAspectExport(aspectOnlyOwnerElementIds));
         await this.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
         // handle deletes
         if (this.visitElements) {
             // must delete models first since they have a constraint on the submodeling element which may also be deleted
             for (const modelId of this._sourceDbChanges.model.deleteIds) {
-                this.handler.onDeleteModel(modelId);
+                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
@@ -307,7 +373,7 @@ class IModelExporter {
                 // 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);
+                    await this.handler.onDeleteElement(elementId);
                 }
                 catch (err) {
                     const isMissingErr = err instanceof core_common_1.IModelError &&
@@ -320,21 +386,24 @@ class IModelExporter {
         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,26 +414,35 @@ class IModelExporter {
       `}
       ORDER BY ECInstanceId
     `;
-        const schemaNamesToExport = [];
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        this.sourceDb.withPreparedStatement(sql, (statement) => {
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const schemaName = statement.getValue(0).getString();
-                const versionMajor = statement.getValue(1).getInteger();
-                const versionWrite = statement.getValue(2).getInteger();
-                const versionMinor = statement.getValue(3).getInteger();
-                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}`,
+                });
             }
-        });
-        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})`);
+            yield schema;
+        }
+    }
+    /** 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);
         }));
     }
@@ -378,15 +456,11 @@ class IModelExporter {
     async exportCodeSpecs() {
         core_bentley_1.Logger.logTrace(loggerCategory, "exportCodeSpecs()");
         const sql = "SELECT Name FROM BisCore:CodeSpec ORDER BY ECInstanceId";
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        async (statement) => {
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const codeSpecName = statement.getValue(0).getString();
-                await this.exportCodeSpecByName(codeSpecName);
-            }
-        });
+        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.
      * @note This method is called from [[exportChanges]] and [[exportAll]], so it only needs to be called directly when exporting a subset of an iModel.
@@ -412,9 +486,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();
         }
     }
@@ -430,41 +504,63 @@ class IModelExporter {
      */
     async exportFonts() {
         core_bentley_1.Logger.logTrace(loggerCategory, "exportFonts()");
-        for (const font of this.sourceDb.fontMap.fonts.values()) {
-            await this.exportFontByNumber(font.id);
+        for (const font of this.sourceDb.fonts.queryMappedFamilies()) {
+            await this.exportFontByFontProps(font);
         }
     }
     /** Export a single font 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.
+     * @note multiple fonts can have the same font name, if a font with a specific type is needed use exportFontByFontFamilyDescriptor.
+     * If not this will only export the first font with this type in the db.
      */
     async exportFontByName(fontName) {
         core_bentley_1.Logger.logTrace(loggerCategory, `exportFontByName(${fontName})`);
-        const font = this.sourceDb.fontMap.getFont(fontName);
-        if (undefined !== font) {
-            await this.exportFontByNumber(font.id);
+        const fontId = this.sourceDb.fonts.findId({
+            name: fontName,
+        });
+        if (undefined !== fontId) {
+            await this.exportFontByNumber(fontId);
+        }
+    }
+    /** Export a single font 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 exportFontByFontProps(fontProps) {
+        core_bentley_1.Logger.logTrace(loggerCategory, `exportFontByFamily(${fontProps.name}, ${fontProps.type})`);
+        await this.handler.onExportFont(fontProps, true);
+        return this.trackProgress();
+    }
+    /** Export a single font 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 exportFontByFontFamilyDescriptor(fontFamily) {
+        core_bentley_1.Logger.logTrace(loggerCategory, `exportFontByFamilyDescriptor(${fontFamily.name}, ${fontFamily.type})`);
+        const fontId = await this.sourceDb.fonts.acquireId(fontFamily);
+        if (undefined !== fontId) {
+            await this.exportFontByFontProps({ ...fontFamily, id: fontId });
         }
     }
     /** Export a single font 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 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.
          */
-        const isUpdate = true;
         core_bentley_1.Logger.logTrace(loggerCategory, `exportFontById(${fontNumber})`);
-        const font = this.sourceDb.fontMap.getFont(fontNumber);
+        const font = this.sourceDb.fonts.findDescriptor(fontNumber);
         if (undefined !== font) {
-            this.handler.onExportFont(font, isUpdate);
-            return this.trackProgress();
+            await this.exportFontByFontFamilyDescriptor(font);
         }
     }
     /** Export the model container, contents, and sub-models 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 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;
@@ -475,7 +571,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);
@@ -498,7 +594,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();
@@ -509,6 +605,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
@@ -533,44 +632,41 @@ class IModelExporter {
         else {
             sql = `SELECT ECInstanceId FROM ${elementClassFullName} WHERE Parent.Id IS NULL AND Model.Id=:modelId ORDER BY ECInstanceId`;
         }
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        async (statement) => {
-            statement.bindId("modelId", modelId);
-            if (skipRootSubject) {
-                statement.bindId("rootSubjectId", core_common_1.IModel.rootSubjectId);
-            }
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                await this.exportElement(statement.getValue(0).getId());
-                await this._yieldManager.allowYield();
-            }
-        });
+        const params = new core_common_1.QueryBinder().bindId("modelId", modelId);
+        if (skipRootSubject) {
+            params.bindId("rootSubjectId", core_common_1.IModel.rootSubjectId);
+        }
+        for await (const row of this.sourceDb.createQueryReader(sql, params, {
+            usePrimaryConn: true,
+        })) {
+            await this.exportElement(row.id);
+            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`;
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        this.sourceDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        (statement) => {
-            statement.bindId("parentModelId", parentModelId);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const modelId = statement.getValue(0).getId();
-                const model = this.sourceDb.models.getModel(modelId);
-                if (model instanceof core_backend_1.DefinitionModel) {
-                    definitionModelIds.push(modelId);
-                }
-                else {
-                    otherModelIds.push(modelId);
-                }
+        const params = new core_common_1.QueryBinder().bindId("parentModelId", parentModelId);
+        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);
             }
-        });
+            else {
+                otherModelIds.push(modelId);
+            }
+        }
         // export DefinitionModels before other types of Models
         for (const definitionModelId of definitionModelIds) {
             await this.exportModel(definitionModelId);
@@ -583,16 +679,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) {
@@ -606,12 +701,19 @@ 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;
@@ -619,7 +721,7 @@ class IModelExporter {
         // Return early if the elementId is already in the excludedElementIds, that way we don't need to load the element from the db.
         if (this._excludedElementIds.has(elementId)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Excluded element ${elementId} by Id`);
-            this.handler.onSkipElement(elementId);
+            await this.handler.onSkipElement(elementId);
             return;
         }
         // are we processing changes?
@@ -628,6 +730,10 @@ class IModelExporter {
             : this._sourceDbChanges?.element.updateIds.has(elementId)
                 ? true
                 : undefined;
+        // Short-circuit: element is not in the changeset, skip its own export but still visit children
+        if (undefined !== this._sourceDbChanges && undefined === isUpdate) {
+            return this.exportChildElements(elementId);
+        }
         const element = this.sourceDb.elements.getElement({
             id: elementId,
             wantGeometry: this.wantGeometry,
@@ -635,21 +741,24 @@ 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);
-            this.handler.onExportElement(element, isUpdate);
+            await this.handler.onExportElement(element, isUpdate);
             await this.trackProgress();
-            await this._exportElementAspectsStrategy.exportElementAspectsForElement(elementId);
+            await this._elementAspectExportCoordinator.addAcceptedOwner(elementId);
             return this.exportChildElements(elementId);
         }
         else {
-            this.handler.onSkipElement(element.id);
+            await this.handler.onSkipElement(element.id);
         }
     }
     /** 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;
@@ -662,13 +771,216 @@ class IModelExporter {
             }
         }
     }
-    /** Exports all aspects present in the iModel.
-     */
-    async exportAllAspects() {
-        return this._exportElementAspectsStrategy.exportAllElementAspects();
+    /** 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);
+    }
+    async runScopedElementExport(exportElements) {
+        await this._elementAspectExportCoordinator.run(exportElements);
+    }
+    /** 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
+         OPTIONS ENABLE_EXPERIMENTAL_FEATURES`, 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
+           OPTIONS ENABLE_EXPERIMENTAL_FEATURES`, 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
+           OPTIONS ENABLE_EXPERIMENTAL_FEATURES`, 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) {
@@ -676,46 +988,154 @@ class IModelExporter {
             return;
         }
         core_bentley_1.Logger.logTrace(loggerCategory, `exportRelationships(${baseRelClassFullName})`);
-        const sql = `SELECT r.ECInstanceId, r.ECClassId 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`;
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        async (statement) => {
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const relationshipId = statement.getValue(0).getId();
-                const relationshipClass = statement
-                    .getValue(1)
-                    .getClassNameForClassId();
-                await this.exportRelationship(relationshipClass, relationshipId); // must call exportRelationship using the actual classFullName, not baseRelClassFullName
+        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;
+        }
+    }
+    /** 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 a relationship from the source iModel. */
+    /** 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}`);
@@ -723,8 +1143,8 @@ class IModelExporter {
             }
         }
         // relationship has passed standard exclusion rules, now give handler a chance to accept/reject export
-        if (this.handler.shouldExportRelationship(relationship)) {
-            this.handler.onExportRelationship(relationship, isUpdate);
+        if (await this.handler.shouldExportRelationship(relationship)) {
+            await this.handler.onExportRelationship(relationship, isUpdate, sourceFedGuid, targetFedGuid);
             await this.trackProgress();
         }
     }
@@ -783,6 +1203,13 @@ class ChangedInstanceIds {
     _aspectSubclassIds;
     _relationshipSubclassIds;
     _relationshipSubclassIdsToSkip;
+    _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;
@@ -795,7 +1222,7 @@ class ChangedInstanceIds {
         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})`)) {
+            for await (const row of this._db.createQueryReader(`SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (${baseClass})`, undefined, { usePrimaryConn: true })) {
                 setToModify.add(row.ECInstanceId);
             }
         };
@@ -845,33 +1272,63 @@ 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;
+        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}.`);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                },
+                message: `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))
+        else if (this.isAspect(ecClassId)) {
+            const ownerElementId = change.Element?.Id ??
+                this.tryGetAspectOwnerElementId(change.ECInstanceId);
+            if (ownerElementId !== undefined) {
+                this._aspectOwnerElementIds.add(ownerElementId);
+            }
             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);
     }
+    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]].
      * It adds the provided change to the element changes maintained by this instance of ChangedInstanceIds.
@@ -933,14 +1390,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.
@@ -949,16 +1439,21 @@ 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
             INNER JOIN hierarchy h ON h.parentId = e.ECInstanceId
         )
         SELECT parentId FROM hierarchy where parentId is not null
+        OPTIONS ENABLE_EXPERIMENTAL_FEATURES
     `;
         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.
@@ -972,11 +1467,20 @@ 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
+        OPTIONS ENABLE_EXPERIMENTAL_FEATURES`;
         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);
         }
@@ -986,11 +1490,17 @@ 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
+        OPTIONS ENABLE_EXPERIMENTAL_FEATURES`;
             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);
             }
         }
     }
@@ -1057,23 +1567,7 @@ class ChangedInstanceIds {
         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);
         return changedInstanceIds;
     }
 }