bigtable-basics

Bigtable 基础指南

本 Skill 提供管理和开发 Google Bigtable 的核心工作流与指导规范。

核心原则

• 控制面与数据面分离：
  • 使用 gcloud 处理**控制面（Control Plane）**操作：管理实例（Instance）、集群（Cluster）、应用配置文件（App Profile）、备份和 IAM；创建表、逻辑视图（Logical View）、物化视图（Materialized View）及授权视图（Authorized View）。
  • 使用 cbt 处理**数据面（Data Plane）**操作：更新表、列族（Column Family），以及读写数据。
• 性能优先： Bigtable 是 NoSQL 数据库，读写效率极度依赖行键（Row Key）设计。务必对全表扫描（Full Table Scan）风险发出警告。
• 客户端选型： 在生产环境中，优先推荐使用 Java 或 Go SDK，相较于其他语言，它们具备更出色的性能表现和更完善的特性支持。
• 可观测性： 在排查性能问题或热点（hotspotting）时，必须首先推荐控制台（Cloud Console）中的 Key Visualizer 作为首选诊断工具，因为它能提供针对行键访问模式的最细粒度视图。其次可结合 gcloud CLI 中的 hot-tablets 工具、表统计信息（table stats），以及 cbt read 命令的 include-stats=full 选项来排查慢查询。

[!IMPORTANT] 安全规则： 对非模拟器（non-emulator）环境的数据库进行任何变更前，必须获得用户的明确确认。在提供任何会修改数据库结构或数据的命令/指令时，必须告知此安全要求。

常用操作速查

1. 查询数据

复杂转换或聚合计算推荐使用 SQL，简单查询模式推荐使用键值 API。注意：请对 _key 使用精确匹配、前缀匹配（_key LIKE 'myprefix%'）或范围谓词，避免高成本的无界全表扫描。在可能的情况下，建议优先使用明确的行范围匹配（_key BETWEEN 'start' AND 'end'），其性能优于前缀匹配。

若因访问模式多样无法在单一 Schema 中全部满足，导致高成本扫描（如无界扫描、大范围前缀/范围查询）无法避免时，可考虑以下两种方案：

• 对时延敏感或面向用户的应用： 使用连续物化视图（continuous materialized views），并针对额外的访问模式优化物化视图的主键。
• 对于低频访问、批处理场景（如 ETL、ML 模型训练或只读分析任务）： 推荐使用 Bigtable Data Boost。

2. 数据变更

插入、更新、自增和删除操作请使用键值 API。SQL API 目前仅支持只读操作。

3. 数据模型定义（DDL）

SQL API 不支持 DDL 操作。建表、删表及更新操作应通过 gcloud CLI 完成。逻辑视图（Logical View）和连续物化视图虽然用 SQL 语句定义，但也必须通过 gcloud CLI 创建。

参考指南

• CLI 命令行操作：
  • infrastructure_management.md：实例、集群和表 Schema 的资源配置。
  • cli_data_access.md：通过 cbt CLI 读写数据。
• 设计与数据资产发现：
  • schema_design.md：行键（Row Key）设计最佳实践，以及表和连续物化视图的性能优化建议。
  • dataplex.md：Bigtable 数据资产的数据目录检索。
• 查询与代码开发：
  • sql_guide.md：通过 SQL 和 CLI 查询结构化行键。
  • client_libraries.md：Go/Java/Python 高性能代码开发模式。

常见工作流

Schema 变更与演进（DevOps）

1. 生产环境优先推荐使用 Terraform 进行 Schema 变更，以防误操作导致数据丢失。

2. 若需使用 cbt 进行手动变更，在提出任何修改建议前，先检查现有状态（查看表的列族和垃圾回收 / GC 策略）：

   cbt ls {table}
   

   如果确认需要修改，可创建列族或更新 GC 策略：

   cbt createfamily {table} {family}
   cbt setgcpolicy {table} {family} "maxversions=5 AND maxage=30d"
   

3. 完整语法请参考 infrastructure_management.md。

外部资源

• Cloud Bigtable Documentation
• Bigtable SQL Reference
• cbt CLI Reference
• gcloud bigtable Reference