microsoft / microsoft/multiclouddb-sdk-for-java

feat: implement Hierarchical Partition Key (HPK) abstraction across providers

Open
#29 0 comments 0 reactions 1 assignee View on GitHub

@allenkim0129 is already working on this.

Since Mar 26, 2026.

enhancement
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 HyperscaleDbKey to 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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.