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

Offen
  • Stimmt etwas nicht?
#12,670 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Muss geklärt werden
Aktivitätsstatus
Ruhig
Tech-Stack
gcp, java
Bereich
cloud, database

Rechercherichtung

Beginnen Sie mit dem angeforderten Umfang von MutationCountEstimator und der Dokumentation zu den Spanner-Kontingenten und Commit-Statistiken, und prüfen Sie anschließend das verknüpfte google-cloud-go issue 1721. Vergleichen Sie die angeforderte Abdeckung für INSERT, UPDATE, INSERT_OR_UPDATE, REPLACE und DELETE, einschließlich STORING und generierter Spalten sowie der Write-only-Phase des Index. Als abgeschlossen gilt die Aufgabe, wenn ein Implementierungs- oder Dokumentationsumfang festgelegt wurde und Validierungskriterien vorliegen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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

Vorherrschende Sprache
Java
Sterne
2.1k
Forks
1.2k
Ø Merge
2 T. 14 Std.
Gemergte PRs (30 T.)
192

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus googleapis/google-cloud-java

Alle Issues in googleapis/google-cloud-java

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.