perf(cosmos): strip unused fields when constructing PartitionKeyRange from ObjectNode

[xinlian12]

Summary

Reduce per-instance memory footprint of every PartitionKeyRange the SDK deserializes from a service response by stripping fields the SDK does not need to retain. This is the Java port of the per-record half of Azure/azure-sdk-for-python#46297 (item #2 — "Strip unused fields → compact PKRange").

Background

A typical PartitionKeyRange returned by Cosmos DB carries 13 fields:

{
  "_rid" : "90t-ALzvP44CAAAAAAAAUA==",
  "id" : "0",
  "_etag" : "\"00001e02-0000-0800-0000-6a2c41690000\"",
  "minInclusive" : "",
  "maxExclusive" : "FF",
  "ridPrefix" : 0,
  "_self" : "dbs/90t-AA==/colls/90t-ALzvP44=/pkranges/90t-ALzvP44CAAAAAAAAUA==/",
  "throughputFraction" : 1,
  "status" : "online",
  "parents" : [ ],
  "ownedArchivalPKRangeIds" : [ ],
  "_ts" : 1781285225,
  "lsn" : 87,
  "_lsn" : 87
}

In Java, every PartitionKeyRange stores those fields in a Jackson ObjectNode (JsonSerializable.propertyBag). Each unused string field carries entry + TextNode + String overhead — the large strings (_self path, base64 _rid, quoted _etag) are the main cost. Across many physical partitions × many CosmosClient instances this becomes material per-JVM heap.

Change

The strip happens in PartitionKeyRange(ObjectNode) — the single constructor funnel every server-deserialized partition key range flows through (via JsonSerializable.instantiateFromObjectNodeAndType, which FeedResponse<PartitionKeyRange> and the change-feed path both use). One source of truth; no cache-side helper needed.

private static final String[] DROPPED_FIELDS = new String[] {
    "_rid", "_etag", "ridPrefix", "_self",
    "ownedArchivalPKRangeIds", "_ts", "lsn"
};

public PartitionKeyRange(ObjectNode objectNode) {
    super(stripUnusedFields(objectNode));
}

private static ObjectNode stripUnusedFields(ObjectNode objectNode) {
    if (objectNode != null) {
        for (String field : DROPPED_FIELDS) {
            objectNode.remove(field);
        }
    }
    return objectNode;
}

Compatibility

• PartitionKeyRange is in com.azure.cosmos.implementation — internal, not public.
• No wire-protocol or serialization change.
• equals / hashCode semantics unchanged.
• (String) constructor still returns a full-fidelity instance for test/sample code that needs it.

[Copilot]

Pull request overview

This PR reduces Azure Cosmos DB Java client routing-map memory usage by compacting cached PartitionKeyRange instances to retain only the fields actually consumed by the routing map (id, minInclusive, maxExclusive, and non-empty parents), while adding unit tests and documenting the change in the Cosmos SDK changelog.

Changes:

• Compact cached PartitionKeyRange objects in RxPartitionKeyRangeCache.updateRoutingMap by stripping unused fields before building the routing map.
• Add unit tests ensuring stripped fields are removed from cached ranges and that non-empty parents is preserved.
• Add a release note entry describing the memory optimization.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxPartitionKeyRangeCache.java	Strips unused fields from PartitionKeyRange instances before caching in the routing map; adds documentation for the optimization.
sdk/cosmos/azure-cosmos/CHANGELOG.md	Documents the routing-map memory optimization in the Unreleased notes.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/caches/RxPartitionKeyRangeCacheTest.java	Adds unit tests validating unused fields are stripped and parents is preserved when non-empty.

Copilot's findings

• Files reviewed: 3/3 changed files
• Comments generated: 4

[xinlian12]

@sdkReviewAgent

[xinlian12]

✅ Review complete (31:57)

Posted 4 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (33:49)

Posted 3 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (36:58)

Posted 2 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (36:44)

Posted 4 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

@sdkReviewAgent

[xinlian12]

Status update after pushing 6901e6e2ec1:

Review comments

• ✅ @xinlian12 (CHANGELOG suggestion) — applied; shortened the entry and linked back to this PR.
• ✅ Copilot "duplicate #### Other Changes header" — fixed; entry now lives under the single existing header.
• ⚠️ The other three Copilot comments (RxPartitionKeyRangeCache.java JavaDoc, stripUnusedFields visibility, RxPartitionKeyRangeCacheTest.java comment) are stale — they reference an earlier revision that did the strip inside RxPartitionKeyRangeCache. The current PR does the strip inside PartitionKeyRange(ObjectNode) and does not touch RxPartitionKeyRangeCache at all, so those points no longer apply.

CI failures (both look unrelated to this change):

• Build Test windows2022_18_NotFromSource_TestsOnly — Scala plugin failed with scala-maven-plugin:4.8.1: A required class was missing while executing ... xsbt/ExtractAPI during the -am install of azure-cosmos-spark_3-3_2-12. That's a Maven plugin/classpath issue in the build infrastructure, not a code failure.
• Test Emulator windows2022_KafkaIntegrationTeststargetingCosmosEmulatorJava17 — single failure in CosmosSinkTaskTest.retryOnServiceUnavailable[false] with CosmosWriteException: INVALID resource id null. This is a fault-injection test (forces GONE 503 then expects retry success). The only ResourceId.parse(...) call sites in the SDK parse the resource id off request/collection/sessionToken — never off a PartitionKeyRange instance — so the field strip cannot make this id null. The previous deny-list revision of this PR also stripped _rid and this test passed; the allow-list revision strips the same plus _lsn/unknown future fields, none of which feed into ResourceId.parse. Flagging as flaky.

Will let the rest of the pipeline finish to confirm.

[xinlian12]

✅ Review complete (33:47)

Posted 1 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (35:22)

Posted 1 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (36:35)

Posted 3 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[xinlian12]

✅ Review complete (37:27)

No new comments — existing review coverage is sufficient.

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, test-coverage | ⊘ synthesis}

[xinlian12]

Pushed c62ed2022be to address the blocking finding.

Root cause confirmed. The reviewer is right and I was wrong to dismiss the earlier Kafka CI failure as flaky. AddressResolver.isSameCollection() at AddressResolver.java:122-123 calls getResourceId() on PartitionKeyRange instances during retry target-change detection. With _rid stripped, ResourceId.parse(null) throws "INVALID resource id null" — which is exactly the CosmosSinkTaskTest.retryOnServiceUnavailable failure (fault-injection forces a 410/Gone → retry → isSameCollection → parse(null)).

When I grepped earlier I only looked for the literal string getResourceId adjacent to a pkRange/partitionKeyRange variable name and missed the AddressResolver call site where the two arguments are bound to parameters named initiallyResolved / newlyResolved. That's the bug.

Fix: added Constants.Properties.R_ID (_rid) to KEPT_FIELDS. The allow-list is now Python's PKRange slots + _rid (Java-specific). Javadoc updated to call out the AddressResolver reason so this isn't re-removed later.

Tests:

• STRIPPED_FIELDS no longer contains _rid; KEPT_FIELDS adds it.
• Added the recommended getResourceId() assertion on a stripped instance.
• Adjusted objectNodeConstructor_preservesNonEmptyParents to assert _rid survives (was asserting it was stripped).

Other comments:

• ✅ Duplicate #### Other Changes header — fixed in prior commit 6901e6e2ec1.
• ✅ Testing recommendation — added getResourceId() assertion.

[xinlian12]

/azp run java - cosmos - tests

[xinlian12]

/azp run java - cosmos - spark

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[xinlian12]

/azp run java - cosmos - kafka

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).