microsoft / microsoft/multiclouddb-sdk-for-java
Add capability-gated atomic full-document replace operation
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 7
- Forks
- 7
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 1
Description
Problem
microsoft/multiclouddb-sdk-for-java#105 changes update() from full-document
replace-if-present semantics to shallow partial update. upsert() is not an
equivalent replacement because it creates a missing item, while a
read-then-upsert sequence can recreate an item deleted or expired between calls.
The portable API therefore needs separate operations for:
replace()— atomically replace an existing complete document; fail with
NOT_FOUNDwhen missingupdate()— partially update an existing documentupsert()— create or fully replace a document
Proposed direction
- Add
MulticloudDbClient.replace(...)overloads and corresponding provider SPI
support. - Add a well-known full-document-replace capability.
- Advertise support from Cosmos DB and DynamoDB.
- Treat omitted declarations from Spanner and legacy providers as unsupported.
- Reject unsupported calls before provider I/O with normalized
UNSUPPORTED_CAPABILITY. - Implement Cosmos DB with native
replaceItem. - Implement DynamoDB with a conditional
PutItemguarded by
attribute_exists. - Do not emulate replace through read-then-upsert because that is not atomic.
- Do not require a Spanner production implementation until that provider enters
the applicable release scope.
Acceptance criteria
- Replacing an existing item removes omitted logical fields.
- Replacing a missing item returns non-retryable
NOT_FOUNDand does not create
the item. - Cosmos DB and DynamoDB expose identical observable behavior.
- Spanner and legacy providers fail at the capability gate before provider I/O.
- Error operation names, diagnostics, conformance tests, API/SPI Javadocs,
compatibility documentation, and changelogs are aligned. - Request-count and cost differences are documented.
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.
Research direction
Begin at the proposed MulticloudDbClient.replace(...) overloads and provider SPI support, then trace capability gating and the Cosmos DB and DynamoDB provider entry points. Use the conformance tests to verify atomic replacement, missing-item behavior, normalized errors, and provider capability differences; finish by checking the API/SPI Javadocs, compatibility documentation, and changelogs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend, database
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100