[java-spanner] Provide a mutation count estimation and document how mutations are calculated

Open
  • Is something wrong?
#12,670 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
gcp, java
Domain
cloud, database

Research direction

Start with the requested MutationCountEstimator scope and the Spanner quotas and commit-statistics documentation, then review the linked google-cloud-go issue 1721. Compare the requested coverage for INSERT, UPDATE, INSERT_OR_UPDATE, REPLACE, and DELETE, including STORING and generated columns and the index write-only phase. Done requires a decided implementation or documentation scope with validation criteria.

Written by the indexing model from the issue text.

Description

api: spanner

Is your feature request related to a problem? Please describe.
The https://docs.cloud.google.com/spanner/quotas only describes how secondary indexes affect mutation counts for delete operations. For inserts and updates, the docs state that "operations count with the multiplicity of the number of columns they affect" but do not describe how secondary indexes contribute to the count.

The full formula for inserts (number of columns + sum of columns across all secondary indexes) was only confirmed informally by Google's backend team in https://github.com/googleapis/google-cloud-go/issues/1721.

Additionally, when creating a new index on an existing table, we observe an immediate increase in mutation counts for writes to that table during the schema change (write-only phase), before the index is fully backfilled. This behavior and its impact on mutation budgets is not documented.

This forces teams to reverse-engineer mutation counting logic, which is fragile and breaks when the internal counting rules change.

Describe the solution you'd like

  1. A utility class in the Java client (e.g. MutationCountEstimator) that can calculate the expected mutation count for a given set of mutations before committing
    OR
  2. Complete documentation of how mutations are actually calculated for all operation types (INSERT, UPDATE, INSERT_OR_UPDATE, REPLACE, DELETE),
    including:
    - Indexes with STORING clauses
    - Computed/generated columns
    - The impact on mutation counts during index creation (write-only phase before backfill completes)

Ideally both :D

Describe alternatives you've considered

  • Reverse-engineering the count from schema metadata and secondary index definitions. This is error-prone and has caused production incidents when our
    calculation diverged from Spanner's actual count.
  • Committing a single row first, reading getMutationCount() from CommitResponse, then using that to size remaining batches.
  • Using a limit well below 80,000 (e.g. 75,000) to absorb miscalculations.

Additional context

Dominant language
Java
Stars
2.1k
Forks
1.2k
Avg merge
2d 14h
Merged PRs (30d)
192

Getting set up

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.

More from googleapis/google-cloud-java

All issues in googleapis/google-cloud-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.