microsoft / microsoft/multiclouddb-sdk-for-java

Add capability-gated atomic full-document replace operation

Open
#115 0 comments 0 reactions 0 assignees View on GitHub

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_FOUND when missing
  • update() — partially update an existing document
  • upsert() — 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 PutItem guarded 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_FOUND and 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

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.