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

Abierto
  • ¿Algo no está bien?
#12,670 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Tranquilo
Stack tecnológico
gcp, java
Área
cloud, database

Línea de trabajo

Comienza con el alcance solicitado de MutationCountEstimator y la documentación sobre las cuotas de Spanner y las estadísticas de commit; después, revisa el google-cloud-go issue 1721 enlazado. Compara la cobertura solicitada para INSERT, UPDATE, INSERT_OR_UPDATE, REPLACE y DELETE, incluidos STORING y las columnas generadas, así como la fase de solo escritura del índice. Se requiere haber decidido un alcance de implementación o documentación, con criterios de validación, para darlo por terminado.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Java
Estrellas
2.1k
Forks
1.2k
Merge medio
2 d 14 h
PR fusionados (30 d)
192

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de googleapis/google-cloud-java

Todos los issues de googleapis/google-cloud-java

Issues similares

Más issues de Java

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.