googleapis / googleapis/google-cloud-java

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

未关闭
#12,670 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
api: spanner
主要语言
Java
星标
2.1k
派生
1.2k
平均合并
1 天 23 小时
30 天内合并 PR
157

描述

**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**
- https://cloud.google.com/blog/products/databases/cloud-spanner-doubles-the-number-of-updates-per-transaction — references mutation counting but does not cover the index impact.
- https://github.com/googleapis/google-cloud-go/issues/1721 — open since 2019, requesting programmatic mutation calculation. The formula was confirmed informally but never made it into the docs.
- The https://docs.cloud.google.com/spanner/docs/commit-statistics provides post-commit mutation counts but not pre-commit estimation.

贡献指南

打开贡献指南

调研方向

先从所请求的 MutationCountEstimator 范围以及 Spanner 配额和提交统计信息文档开始,然后查看链接的 google-cloud-go issue 1721。比较对 INSERT、UPDATE、INSERT_OR_UPDATE、REPLACE 和 DELETE 的请求覆盖范围,包括 STORING 和生成列,以及索引的 write-only 阶段。完成的要求是确定实现范围或文档范围,并制定验证标准。

由索引模型根据 Issue 内容生成。

评估

技术栈
gcp, java
领域
cloud, database
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
冷清
描述清晰度
需要澄清
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。