Add NativeChangesetReader API with filtering

.vscode/launch.json

@@ -627,7 +627,7 @@
       ]
     },
     {
-      "name": "[perftests] Changeset PerfTests (Offline)",
+      "name": "[perftests] Sqlite Changeset Reader and ChangesetECAdaptor PerfTests (Offline)",
       "presentation": {
         "group": "Perftests"
       },
@@ -637,7 +637,24 @@
       "runtimeExecutable": "npm",
       "runtimeArgs": [
         "run",
-        "perftest:changesetPerformance"
+        "perftest:sqliteChangesetReaderAndChangesetECAdaptorPerformance"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/full-stack-tests/*/lib/**/*.js"
+      ]
+    },
+    {
+      "name": "[perftests] ChangesetReader PerfTests (Offline)",
+      "presentation": {
+        "group": "Perftests"
+      },
+      "cwd": "${workspaceFolder}/full-stack-tests/backend",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "perftest:changesetReaderPerformance"
       ],
       "outFiles": [
         "${workspaceFolder}/full-stack-tests/*/lib/**/*.js"

common/api/core-backend.api.md

@@ -858,6 +858,14 @@ export class CategorySelector extends DefinitionElement {
 }
 
 // @beta
+export interface ChangeCache extends Disposable {
+    all(): IterableIterator<ChangeInstance>;
+    count(): number;
+    get(key: string): ChangeInstance | undefined;
+    set(key: string, value: ChangeInstance): void;
+}
+
+// @beta @deprecated
 export interface ChangedECInstance {
     // (undocumented)
     $meta?: ChangeMetaData;
@@ -899,6 +907,12 @@ export interface ChangeFormatArgs {
     includeTableName?: true;
 }
 
+// @beta
+export interface ChangeInstance {
+    $meta: ChangeMeta;
+    [key: string]: any;
+}
+
 // @beta
 export interface ChangeInstanceKey {
     changeType: "inserted" | "updated" | "deleted";
@@ -907,6 +921,19 @@ export interface ChangeInstanceKey {
 }
 
 // @beta
+export interface ChangeMeta {
+    changeFetchedPropNames: string[];
+    changeIndexes: number[];
+    instanceKey: string;
+    isIndirectChange: boolean;
+    op: SqliteChangeOp;
+    propFilter: PropertyFilter;
+    rowOptions?: RowFormatOptions;
+    stage: SqliteValueStage;
+    tables: string[];
+}
+
+// @beta @deprecated
 export interface ChangeMetaData {
     changeIndexes: number[];
     classFullName?: string;
@@ -922,7 +949,7 @@ export interface ChangesetArg extends IModelIdArg {
     readonly changeset: ChangesetIndexOrId;
 }
 
-// @beta
+// @beta @deprecated
 export class ChangesetECAdaptor implements Disposable {
     [Symbol.dispose](): void;
     constructor(reader: SqliteChangesetReader, disableMetaData?: boolean);
@@ -960,6 +987,58 @@ export interface ChangesetRangeArg extends IModelIdArg {
     readonly range?: ChangesetRange;
 }
 
+// @beta
+export class ChangesetReader implements Disposable, ChangeSource {
+    [Symbol.dispose](): void;
+    clearClassNameFilters(): void;
+    clearOpCodeFilters(): void;
+    clearTableNameFilters(): void;
+    close(): void;
+    readonly db: AnyDb;
+    deleted?: ChangeInstance;
+    inserted?: ChangeInstance;
+    get isECTable(): boolean;
+    get isIndirectChange(): boolean;
+    get op(): SqliteChangeOp;
+    static openFile(args: {
+        readonly fileName: string;
+    } & ChangesetReaderArgs): ChangesetReader;
+    static openGroup(args: {
+        readonly changesetFiles: string[];
+    } & ChangesetReaderArgs): ChangesetReader;
+    static openInMemoryChanges(args: Omit<ChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+    }): ChangesetReader;
+    static openLocalChanges(args: Omit<ChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+        includeInMemoryChanges?: boolean;
+    }): ChangesetReader;
+    static openTxn(args: Omit<ChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+        txnId: Id64String;
+    }): ChangesetReader;
+    setClassNameFilters(classNames: Set<string>): void;
+    setOpCodeFilters(ops: Set<SqliteChangeOp>): void;
+    setTableNameFilters(tableNames: Set<string>): void;
+    step(): boolean;
+    get tableName(): string;
+}
+
+// @beta
+export interface ChangesetReaderArgs {
+    readonly db: AnyDb;
+    readonly invert?: boolean;
+    readonly propFilter?: PropertyFilter;
+    readonly rowOptions?: RowFormatOptions;
+}
+
+// @beta
+export interface ChangeSource {
+    readonly deleted?: ChangeInstance;
+    readonly inserted?: ChangeInstance;
+    readonly op: SqliteChangeOp;
+}
+
 // @beta
 export interface ChangeSummary {
     // (undocumented)
@@ -994,6 +1073,12 @@ export class ChangeSummaryManager {
     static queryInstanceChange(iModel: BriefcaseDb, instanceChangeId: Id64String): InstanceChange;
 }
 
+// @beta (undocumented)
+export namespace ChangeUnifierCache {
+    export function createInMemoryCache(): ChangeCache;
+    export function createSqliteBackedCache(bufferedReadInstanceSizeInBytes?: number): ChangeCache;
+}
+
 // @beta
 export interface ChannelControl {
     // @internal (undocumented)
@@ -2248,15 +2333,15 @@ export abstract class DriverBundleElement extends InformationContentElement {
     static get className(): string;
 }
 
-// @beta
+// @beta @deprecated
 export interface ECChangeUnifierCache extends Disposable {
     all(): IterableIterator<ChangedECInstance>;
     count(): number;
     get(key: string): ChangedECInstance | undefined;
     set(key: string, value: ChangedECInstance): void;
 }
 
-// @beta (undocumented)
+// @beta @deprecated (undocumented)
 export namespace ECChangeUnifierCache {
     export function createInMemoryCache(): ECChangeUnifierCache;
     export function createSqliteBackedCache(db: AnyDb, bufferedReadInstanceSizeInBytes?: number): ECChangeUnifierCache;
@@ -5423,6 +5508,15 @@ export class OrthographicViewDefinition extends SpatialViewDefinition {
 export function parseTextAnnotationData(json: string | undefined): VersionedJSON<TextAnnotationProps> | undefined;
 
 // @beta
+export class PartialChangeUnifier implements Disposable {
+    [Symbol.dispose](): void;
+    constructor(_cache?: ChangeCache);
+    appendFrom(source: ChangeSource): void;
+    get instanceCount(): number;
+    get instances(): IterableIterator<ChangeInstance>;
+}
+
+// @beta @deprecated
 export class PartialECChangeUnifier implements Disposable {
     [Symbol.dispose](): void;
     constructor(_db: AnyDb, _cache?: ECChangeUnifierCache);
@@ -5609,6 +5703,13 @@ export interface ProjectInformationRecordCreateArgs extends ProjectInformation {
     parentSubjectId: Id64String;
 }
 
+// @beta
+export enum PropertyFilter {
+    All = 0,
+    BisCoreElement = 1,
+    InstanceKey = 2
+}
+
 // @public @preview
 export type PropertyHandler = (name: string, property: Property) => void;
 
@@ -5970,6 +6071,13 @@ export class RoleModel extends Model {
     static get className(): string;
 }
 
+// @beta
+export interface RowFormatOptions {
+    abbreviateBlobs?: boolean;
+    classIdsToClassNames?: boolean;
+    useJsName?: boolean;
+}
+
 // @public
 export class RpcTrace {
     static get currentActivity(): RpcActivity | undefined;

common/api/summary/core-backend.exports.csv

@@ -38,17 +38,27 @@ preview;class;Category
 public;class;CategoryOwnsSubCategories
 public;class;CategorySelector
 preview;class;CategorySelector
+beta;interface;ChangeCache
 beta;interface;ChangedECInstance
+deprecated;interface;ChangedECInstance
 internal;class;ChangedElementsDb
 beta;interface;ChangeFormatArgs
+beta;interface;ChangeInstance
 beta;interface;ChangeInstanceKey
+beta;interface;ChangeMeta
 beta;interface;ChangeMetaData
+deprecated;interface;ChangeMetaData
 public;interface;ChangesetArg
 beta;class;ChangesetECAdaptor
+deprecated;class;ChangesetECAdaptor
 internal;interface;ChangesetIndexArg
 public;interface;ChangesetRangeArg
+beta;class;ChangesetReader
+beta;interface;ChangesetReaderArgs
+beta;interface;ChangeSource
 beta;interface;ChangeSummary
 beta;class;ChangeSummaryManager
+beta;namespace;ChangeUnifierCache
 beta;interface;ChannelControl
 beta;namespace;ChannelControl
 beta;type;ChannelKey
@@ -170,7 +180,9 @@ public;class;DrawingViewDefinition
 preview;class;DrawingViewDefinition
 beta;class;DriverBundleElement
 beta;interface;ECChangeUnifierCache
+deprecated;interface;ECChangeUnifierCache
 beta;namespace;ECChangeUnifierCache
+deprecated;namespace;ECChangeUnifierCache
 public;class;ECDb
 public;enum;ECDbOpenMode
 public;interface;ECEnumValue
@@ -439,7 +451,9 @@ public;type;OpenBriefcaseArgs
 public;class;OrthographicViewDefinition
 preview;class;OrthographicViewDefinition
 internal;function;parseTextAnnotationData
+beta;class;PartialChangeUnifier
 beta;class;PartialECChangeUnifier
+deprecated;class;PartialECChangeUnifier
 public;class;PhysicalElement
 preview;class;PhysicalElement
 public;class;PhysicalElementAssemblesElements
@@ -466,6 +480,7 @@ public;type;ProgressFunction
 public;enum;ProgressStatus
 beta;class;ProjectInformationRecord
 beta;interface;ProjectInformationRecordCreateArgs
+beta;enum;PropertyFilter
 public;type;PropertyHandler
 preview;type;PropertyHandler
 beta;namespace;PropertyStore
@@ -498,6 +513,7 @@ public;class;RoleElement
 preview;class;RoleElement
 public;class;RoleModel
 preview;class;RoleModel
+beta;interface;RowFormatOptions
 public;class;RpcTrace
 beta;class;RunLayout
 public;class;Schema

common/changes/@itwin/core-backend/soham-native-ec-reader_2026-04-23-15-29.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "Added ChangesetReader api(along with new unifier apis) and deprecated ChangesetECAdaptor apis(including unifier apis)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

core/backend/src/BriefcaseManager.ts

@@ -49,7 +49,7 @@ interface PatchInstanceKey {
  */
 interface ChangedInstanceForSemanticRebase {
   isIndirect: boolean;
-  instance: ChangedECInstance;
+  instance: ChangedECInstance; // eslint-disable-line @typescript-eslint/no-deprecated
 }
 
 /** The argument for patch instances during high level rebase application
@@ -921,16 +921,19 @@ export class BriefcaseManager {
     const reader = SqliteChangesetReader.openTxn({
       txnId, db, disableSchemaCheck: true
     });
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     const adaptor = new ChangesetECAdaptor(reader);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     using indirectUnifier = new PartialECChangeUnifier(reader.db, ECChangeUnifierCache.createInMemoryCache());
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     using directUnifier = new PartialECChangeUnifier(reader.db, ECChangeUnifierCache.createInMemoryCache());
     while (adaptor.step()) {
       if (adaptor.reader.isIndirect)
-        indirectUnifier.appendFrom(adaptor);
+        indirectUnifier.appendFrom(adaptor); // eslint-disable-line @typescript-eslint/no-deprecated
       else
-        directUnifier.appendFrom(adaptor);
+        directUnifier.appendFrom(adaptor); // eslint-disable-line @typescript-eslint/no-deprecated
     }
-    return [...Array.from(directUnifier.instances).map((instance) => ({ isIndirect: false, instance })), ...Array.from(indirectUnifier.instances).map((instance) => ({ isIndirect: true, instance }))];
+    return [...Array.from(directUnifier.instances).map((instance) => ({ isIndirect: false, instance })), ...Array.from(indirectUnifier.instances).map((instance) => ({ isIndirect: true, instance }))]; // eslint-disable-line @typescript-eslint/no-deprecated
   }
 
   /**