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

Ouverte
  • Quelque chose ne va pas ?
#12,670 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
35/100
Type d'issue
Fonctionnalité
Clarté
À clarifier
Activité
Calme
Stack technique
gcp, java
Domaine
cloud, database

Piste de recherche

Commencez par le périmètre demandé de MutationCountEstimator et la documentation sur les quotas Spanner et les statistiques de commit, puis examinez le google-cloud-go issue 1721 associé. Comparez la couverture demandée pour INSERT, UPDATE, INSERT_OR_UPDATE, REPLACE et DELETE, y compris STORING et les colonnes générées, ainsi que la phase write-only de l’index. La tâche est terminée lorsqu’un périmètre d’implémentation ou de documentation a été défini, avec des critères de validation.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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

Langage dominant
Java
Étoiles
2.1k
Forks
1.2k
Merge moyen
2 j 14 h
PR mergées (30 j)
192

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de googleapis/google-cloud-java

Toutes les issues de googleapis/google-cloud-java

Issues similaires

Plus d'issues Java

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.