microsoft / microsoft/multiclouddb-sdk-for-java
feat: implement Hierarchical Partition Key (HPK) abstraction across providers
@allenkim0129 is already working on this.
Since Mar 26, 2026.
- Dominant language
- Java
- Stars
- 7
- Forks
- 7
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 1
Description
Background
Raised during PR #20 review (see discussion).
Problem
The current SDK exposes a flat partitionKey + sortKey model. DynamoDB has no native Hierarchical Partition Key (HPK) concept, but when a logical partition reaches its storage limit, DynamoDB automatically splits it — the partition key effectively becomes a hash range over the resulting N partitions.
Proposed solution (from @TheovanKraay)
To match DynamoDB's behavior (the lowest common denominator), HPK needs to be implemented but abstracted:
- Partition key → parent partition key in HPK
- Sort key → item id (second/bottom-level key in HPK)
When DynamoDB eventually introduces explicit HPK support, we can surface it more explicitly. For now the abstraction should mirror what DynamoDB does internally.
Scope
- Update
HyperscaleDbKeyto model HPK components - Map HPK components to Cosmos DB's native HPK path (e.g.
/region/tenantId/id) - Map HPK components to DynamoDB's flat partition + sort key (abstracted split)
- Map HPK components to Spanner's composite primary key columns
- Update conformance tests and documentation
References
- PR #20 review comment: https://github.com/microsoft/hyperscale-db-sdk-for-java/pull/20#discussion_r2994482519
HyperscaleDbKey.of(partitionKey, sortKey, components)factory already exists as a placeholder (line 82,HyperscaleDbKey.java)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.