Add NativeChangesetReader API with filtering

.vscode/launch.json

@@ -643,6 +643,23 @@
         "${workspaceFolder}/full-stack-tests/*/lib/**/*.js"
       ]
     },
+    {
+      "name": "[perftests] ECChangesetReader PerfTests (Offline)",
+      "presentation": {
+        "group": "Perftests"
+      },
+      "cwd": "${workspaceFolder}/full-stack-tests/backend",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "perftest:ecChangesetReaderPerformance"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/full-stack-tests/*/lib/**/*.js"
+      ]
+    },
     {
       "name": "[perftests] Delete Multiple Relationship Instances (Offline)",
       "presentation": {

common/api/core-backend.api.md

@@ -850,7 +850,7 @@ export class CategorySelector extends DefinitionElement {
     toJSON(): CategorySelectorProps;
 }
 
-// @beta
+// @beta @deprecated
 export interface ChangedECInstance {
     // (undocumented)
     $meta?: ChangeMetaData;
@@ -899,7 +899,7 @@ export interface ChangeInstanceKey {
     id: Id64String;
 }
 
-// @beta
+// @beta @deprecated
 export interface ChangeMetaData {
     changeIndexes: number[];
     classFullName?: string;
@@ -915,7 +915,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);
@@ -2242,14 +2242,73 @@ export abstract class DriverBundleElement extends InformationContentElement {
 }
 
 // @beta
+export enum ECChangesetMode {
+    All_Properties = 0,
+    Bis_Element_Properties = 1,
+    Instance_Key = 2
+}
+
+// @beta
+export class ECChangesetReader implements Disposable, ECNativeChangeSource {
+    [Symbol.dispose](): void;
+    clearClassIdFilters(): void;
+    clearOpCodeFilters(): void;
+    clearTableNameFilters(): void;
+    close(): void;
+    readonly db: AnyDb;
+    deleted?: ECNativeChangeInstance;
+    inserted?: ECNativeChangeInstance;
+    get isECTable(): boolean;
+    get isIndirectChange(): boolean;
+    get op(): ECNativeChangeOp;
+    static openFile(args: {
+        readonly fileName: string;
+    } & ECChangesetReaderArgs): ECChangesetReader;
+    static openGroup(args: {
+        readonly changesetFiles: string[];
+    } & ECChangesetReaderArgs): ECChangesetReader;
+    static openInMemoryChanges(args: Omit<ECChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+    }): ECChangesetReader;
+    static openLocalChanges(args: Omit<ECChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+        includeInMemoryChanges?: boolean;
+    }): ECChangesetReader;
+    static openTxn(args: Omit<ECChangesetReaderArgs, "db"> & {
+        db: IModelDb;
+        txnId: Id64String;
+    }): ECChangesetReader;
+    setClassIdFilters(classIds: Set<Id64String>): void;
+    setOpCodeFilters(ops: Set<ECNativeChangeOp>): void;
+    setTableNameFilters(tableNames: Set<string>): void;
+    step(): boolean;
+    get tableName(): string;
+}
+
+// @beta
+export interface ECChangesetReaderArgs {
+    readonly db: AnyDb;
+    readonly invert?: boolean;
+    readonly mode?: ECChangesetMode;
+    readonly rowOptions?: ECChangesetRowAdapterOptions;
+}
+
+// @beta
+export interface ECChangesetRowAdapterOptions {
+    abbreviateBlobs?: boolean;
+    classIdsToClassNames?: boolean;
+    useJsName?: boolean;
+}
+
+// @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;
@@ -2326,6 +2385,61 @@ export interface ECEnumValue {
     value: number | string;
 }
 
+// @beta
+export interface ECNativeChangeCache extends Disposable {
+    all(): IterableIterator<ECNativeChangeInstance>;
+    count(): number;
+    get(key: string): ECNativeChangeInstance | undefined;
+    set(key: string, value: ECNativeChangeInstance): void;
+}
+
+// @beta
+export interface ECNativeChangeInstance {
+    $meta: ECNativeChangeMeta;
+    [key: string]: any;
+}
+
+// @beta
+export interface ECNativeChangeMeta {
+    changeFetchedPropNames: string[];
+    changeIndexes: number[];
+    isIndirectChange: boolean;
+    mode: string;
+    nativeKey: string;
+    op: ECNativeChangeOp;
+    rowOptions?: ECChangesetRowAdapterOptions;
+    stage: ECNativeChangeStage;
+    tables: string[];
+}
+
+// @beta
+export type ECNativeChangeOp = "Inserted" | "Updated" | "Deleted";
+
+// @beta
+export interface ECNativeChangeSource {
+    readonly deleted?: ECNativeChangeInstance;
+    readonly inserted?: ECNativeChangeInstance;
+    readonly op: ECNativeChangeOp;
+}
+
+// @beta
+export type ECNativeChangeStage = "Old" | "New";
+
+// @beta (undocumented)
+export namespace ECNativeChangeUnifierCache {
+    export function createInMemoryCache(): ECNativeChangeCache;
+    export function createSqliteBackedCache(bufferedReadInstanceSizeInBytes?: number): ECNativeChangeCache;
+}
+
+// @beta
+export class ECNativePartialChangeUnifier implements Disposable {
+    [Symbol.dispose](): void;
+    constructor(_cache?: ECNativeChangeCache);
+    appendFrom(source: ECNativeChangeSource): void;
+    get instanceCount(): number;
+    get instances(): IterableIterator<ECNativeChangeInstance>;
+}
+
 // @public @preview
 export class ECSchemaXmlContext {
     constructor();
@@ -5400,7 +5514,7 @@ export class OrthographicViewDefinition extends SpatialViewDefinition {
 // @internal
 export function parseTextAnnotationData(json: string | undefined): VersionedJSON<TextAnnotationProps> | undefined;
 
-// @beta
+// @beta @deprecated
 export class PartialECChangeUnifier implements Disposable {
     [Symbol.dispose](): void;
     constructor(_db: AnyDb, _cache?: ECChangeUnifierCache);

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

@@ -39,12 +39,15 @@ public;class;CategoryOwnsSubCategories
 public;class;CategorySelector
 preview;class;CategorySelector
 beta;interface;ChangedECInstance
+deprecated;interface;ChangedECInstance
 internal;class;ChangedElementsDb
 beta;interface;ChangeFormatArgs
 beta;interface;ChangeInstanceKey
 beta;interface;ChangeMetaData
+deprecated;interface;ChangeMetaData
 public;interface;ChangesetArg
 beta;class;ChangesetECAdaptor
+deprecated;class;ChangesetECAdaptor
 internal;interface;ChangesetIndexArg
 public;interface;ChangesetRangeArg
 beta;interface;ChangeSummary
@@ -169,12 +172,26 @@ preview;class;DrawingModel
 public;class;DrawingViewDefinition
 preview;class;DrawingViewDefinition
 beta;class;DriverBundleElement
+beta;enum;ECChangesetMode
+beta;class;ECChangesetReader
+beta;interface;ECChangesetReaderArgs
+beta;interface;ECChangesetRowAdapterOptions
 beta;interface;ECChangeUnifierCache
+deprecated;interface;ECChangeUnifierCache
 beta;namespace;ECChangeUnifierCache
+deprecated;namespace;ECChangeUnifierCache
 public;class;ECDb
 public;enum;ECDbOpenMode
 public;interface;ECEnumValue
 deprecated;interface;ECEnumValue
+beta;interface;ECNativeChangeCache
+beta;interface;ECNativeChangeInstance
+beta;interface;ECNativeChangeMeta
+beta;type;ECNativeChangeOp
+beta;interface;ECNativeChangeSource
+beta;type;ECNativeChangeStage
+beta;namespace;ECNativeChangeUnifierCache
+beta;class;ECNativePartialChangeUnifier
 public;class;ECSchemaXmlContext
 preview;class;ECSchemaXmlContext
 public;class;ECSqlBinder
@@ -440,6 +457,7 @@ public;class;OrthographicViewDefinition
 preview;class;OrthographicViewDefinition
 internal;function;parseTextAnnotationData
 beta;class;PartialECChangeUnifier
+deprecated;class;PartialECChangeUnifier
 public;class;PhysicalElement
 preview;class;PhysicalElement
 public;class;PhysicalElementAssemblesElements

common/changes/@itwin/core-backend/soham-native-ec-reader_2026-04-06-14-49.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "Added new ECChangesetReader api(along wit new unifier apis) and deprecated ECChangesetAdaptor 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
   }
 
   /**

core/backend/src/ChangesetECAdaptor.ts

@@ -11,6 +11,8 @@ import { Base64EncodedString } from "@itwin/core-common";
 import { ECDb } from "./ECDb";
 import { _nativeDb } from "./internal/Symbols";
 
+/* eslint-disable @typescript-eslint/no-deprecated */ // This file is marked as deprecated and will be removed subsequently, so we can allow usage of deprecated APIs within it.
+
 interface IClassRef {
   classId: Id64String;
   classFullName: string;
@@ -352,6 +354,7 @@ class ECDbMap {
 /**
  * Record meta data for the change.
  * @beta
+ * @deprecated Use ECNativeChangeMeta from ECChangesetReader instead..
  * */
 export interface ChangeMetaData {
   /** list of tables making up this EC change */
@@ -371,6 +374,7 @@ export interface ChangeMetaData {
 /**
  * Represent EC change derived from low level sqlite change
  * @beta
+ * @deprecated Use ECNativeChangeInstance from ECChangesetReader instead.
  */
 export interface ChangedECInstance {
   // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -384,6 +388,7 @@ export interface ChangedECInstance {
 /**
  * Helper function to convert between JS DateTime & SQLite JulianDay values.
  * @beta
+ * @deprecated The DateTime namespace is deprecated and will be removed in a future release.
  * */
 namespace DateTime {
   /**
@@ -411,6 +416,7 @@ namespace DateTime {
 /**
  * Represents a cache for unifying EC changes.
  * @beta
+ * @deprecated Use ECNativeChangeCache from ECChangesetReader instead.
  */
 export interface ECChangeUnifierCache extends Disposable {
   /**
@@ -439,7 +445,10 @@ export interface ECChangeUnifierCache extends Disposable {
    */
   count(): number;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated Use ECNativeChangeUnifierCache.createInMemoryCache / createSqliteBackedCache instead.
+*/
 export namespace ECChangeUnifierCache {
   /**
    * Creates and returns a new in-memory cache for EC change unification.
@@ -648,6 +657,7 @@ class SqliteBackedInstanceCache implements ECChangeUnifierCache {
  * Partial changes is per table and a single instance can
  * span multiple tables.
  * @beta
+ * @deprecated Use ECNativePartialChangeUnifier instead..
  */
 export class PartialECChangeUnifier implements Disposable {
   private _readonly = false;
@@ -815,6 +825,7 @@ export class PartialECChangeUnifier implements Disposable {
  * it is per table while a single instance can span multiple table.
  * @note PrimitiveArray and StructArray are not supported types.
  * @beta
+ * @deprecated Use ECChangesetReader instead.
  *
 */
 export class ChangesetECAdaptor implements Disposable {