bigtable-basics

Bigtable 基础知识

此技能提供使用 Google Bigtable 进行管理和开发的核心工作流与指南。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须先阅读 使用归属信息。对于直接在终端中执行的命令（绝不用于生成的脚本、Terraform 或用户代码），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigtable-basics)" ，并在 User-Agent 请求头中追加 agent-skills/1.0 (skill:bigtable-basics)。

核心原则

• 控制平面与数据平面：
  • 使用 gcloud 执行控制平面操作：管理实例、集群、应用配置、备份和 IAM。创建表、逻辑视图、物化视图和授权视图。
  • 使用 cbt 执行数据平面操作：更新表、列族，以及读取和写入数据。
• 性能优先： Bigtable 是 NoSQL 数据库。效率与行键设计密切相关。务必警告用户全表扫描的风险。
• 客户端选择： 对于生产用例，优先选择 Java 或 Go，因为与其他语言相比，它们性能更出色、功能覆盖更全面。
• 可观测性： 诊断性能问题或热点时，务必提及通过 Cloud Console 使用 Key Visualizer 作为主要诊断工具，因为它能以最细粒度呈现各行键的访问模式。之后应使用 hot-tablets 工具和 gcloud CLI 中的表统计信息，并通过 cbt read 下的 include-stats=full 选项诊断慢查询。

重要

安全规则： 修改非模拟器数据库之前，必须先获得用户的明确确认。提供修改数据库结构或数据的命令或说明时，必须提及此安全要求。

快速操作指南

1. 查询数据

复杂转换或聚合使用 SQL，简单查询模式使用键值 API。注意：使用 _key 上的精确匹配、前缀（_key LIKE 'myprefix%'）或范围谓词，避免代价高昂的无界扫描。在可行的情况下，建议使用显式行范围（_key BETWEEN 'start' AND 'end'），因为它比前缀匹配性能更好。

如果由于多种访问模式无法全部通过单一架构满足，而昂贵的扫描（无界扫描、前缀查询或扫描大范围的范围查询）不可避免，请考虑以下两种方案之一：

• 如果查询用于面向用户和／或对延迟敏感的应用，请使用键经过优化、能够满足额外访问模式的连续物化视图。
• 如果二级访问模式不频繁，且属于批处理模式（例如 ETL、ML 模型训练或只读分析任务），请改用 Bigtable Data Boost。

2. 操作数据

插入、更新、递增和删除操作使用键值 API。SQL API 仅支持读取。

3. 定义数据模型（DDL）

SQL API 不支持 DDL 操作。应使用 gcloud CLI 创建、删除和更新表。逻辑视图和连续物化视图以 SQL 查询定义，但必须使用 gcloud CLI 创建。

参考指南

• CLI 操作：
  • infrastructure_management.md： 配置实例、集群和表架构。
  • cli_data_access.md：通过 cbt CLI 读取和写入 数据。
• 设计与发现：
  • schema_design.md：表和连续物化视图的行 键与性能最佳实践。
  • dataplex.md：搜索 Bigtable 资产的数据目录。
• 查询与代码：
  • sql_guide.md：通过 SQL 和 CLI 查询结构化的行 键。
  • client_libraries.md：高性能 Go/Java/Python 代码的 模式。

常见工作流

架构演进（DevOps）

1. 生产环境的架构变更优先使用 Terraform，以防意外丢失数据。

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 文档
• Bigtable SQL 参考
• cbt CLI 参考
• gcloud bigtable 参考