bigtable-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bigtable Basics

Bigtable 基础

This skill provides core workflows and guidance for administering and developing with Google Bigtable.

本技能提供了管理和开发Google Bigtable的核心工作流与指导。

Core Principles

核心原则

Control Plane vs. Data Plane:
- Use gcloud
  for Control Plane operations: Manage Instances, Clusters, App Profiles, Backups and IAM. Create Tables, Logical Views, Materialized Views and Authorized Views.
- Use cbt
  for Data Plane operations: Update Tables, Column Families, and reading/writing data.
Performance First: Bigtable is a NoSQL database. Efficiency is tied to Row Key design. Always warn about Full Table Scans.
Client Selection: For production use cases, prefer Java or Go for their superior performance and feature coverage compared to other languages.
Observability: When diagnosing performance or hotspotting, always mention Key Visualizer (via Cloud Console) as the primary diagnostic tool because it provides the most granular view of access patterns across row keys. This should be followed by the hot-tablets tool and table stats in gcloud CLI and
```
include-stats=full
```
option under
```
cbt read
```
to diagnose slow queries.

[!IMPORTANT] Safety Rule: You MUST obtain explicit user confirmation before making non-emulator database changes. You MUST mention this safety requirement when providing commands or instructions that modify the database structure or data.

控制平面 vs 数据平面：
- 使用**
```
gcloud
```
  **执行控制平面操作：管理实例、集群、应用配置文件、备份和IAM。创建表、逻辑视图、物化视图和授权视图。
- 使用**
```
cbt
```
  **执行数据平面操作：更新表、列族，以及读写数据。
性能优先： Bigtable是一款NoSQL数据库，效率与行键设计紧密相关。需始终提醒用户注意全表扫描的问题。
客户端选择： 对于生产场景，优先选择Java或Go，相较于其他语言，它们具备更出色的性能和功能覆盖。
可观测性： 在诊断性能或热点问题时，务必提及Key Visualizer（通过Cloud Console访问）作为主要诊断工具，因为它能提供跨行键访问模式的最细粒度视图。之后可结合gcloud CLI中的hot-tablets工具和表统计信息，以及
```
cbt read
```
下的
```
include-stats=full
```
选项来诊断慢查询。

[!IMPORTANT] 安全规则： 在进行非模拟器数据库更改前，必须获得用户的明确确认。当提供修改数据库结构或数据的命令或说明时，必须提及此安全要求。

Quick Recipes

快速方案

1. Querying Data

1. 查询数据

Use SQL for complex transforms or aggregations and key-value APIs for simpler query patterns. Note: Use exact match, prefix (
_key LIKE 'myprefix%'
), or range predicates on
_key
to avoid expensive unbounded scans. Recommend explicit row ranges (
_key BETWEEN 'start' AND 'end'
) as a more performant alternative to prefix matches where possible.

If expensive scans (either unbounded or prefix or range queries scanning a large range) are unavoidable due to multiple access patterns that can’t all be accommodated in a single schema, consider one of these two options:

If the query will be used in user facing and/or latency sensitive applications, use continuous materialized views with keys optimized for the additional access patterns.
If secondary access patterns are infrequent, batch patterns like ETL, ML model training or analytical read-only tasks, use Bigtable Data Boost instead.

复杂转换或聚合操作使用SQL，简单查询模式使用键值API。注意：使用精确匹配、前缀（
_key LIKE 'myprefix%'
）或针对
_key
的范围谓词，避免代价高昂的无界扫描。在可能的情况下，推荐使用明确的行范围（
_key BETWEEN 'start' AND 'end'
）作为前缀匹配的更高效替代方案。

若由于存在多种访问模式无法全部适配单一模式而不得不进行代价高昂的扫描（无论是无界扫描，还是扫描大范围的前缀或范围查询），可考虑以下两种方案之一：

如果查询用于面向用户和/或对延迟敏感的应用，使用连续物化视图，其键针对额外的访问模式进行优化。
如果次要访问模式不频繁，属于ETL、ML模型训练或分析类只读任务等批处理场景，则使用Bigtable Data Boost。

2. Manipulating Data

2. 数据操作

Use key-value APIs for insert, update, increment and delete operations. SQL API is read-only.

插入、更新、递增和删除操作使用键值API。SQL API为只读。

3. Data Model Definition (DDL)

3. 数据模型定义（DDL）

SQL API doesn't support DDL operations. Table creation, deletion, updates should be made using gcloud CLI. Logical Views and Continuous Materialized Views are defined as SQL queries but they must be created using gcloud CLI.

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

Reference Guides

参考指南

CLI Operations:
- infrastructure_management.md: Provisioning instances, clusters, and table schemas.
- cli_data_access.md: Reading and writing data via the
```
cbt
```
  CLI.
Design & Discovery:
- schema_design.md: Best practices for row keys and performance with tables and continuous materialized views.
- dataplex.md: Data catalog search for Bigtable assets.
Querying & Code:
- sql_guide.md: Querying structured row keys via SQL and CLI.
- client_libraries.md: Patterns for high-performance Go/Java/Python code.

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代码模式。

Common Workflows

常见工作流

Schema Evolution (DevOps)

模式演进（DevOps）

Prefer Terraform for production schema changes to prevent accidental data loss.
For manual
```
cbt
```
changes, first check the existing state by listing the table's column families and GC policies before proposing any modifications:
bash
```
cbt ls {table}
```
If modifications are needed, create the family or update the GC policy:
bash
```
cbt createfamily {table} {family}
cbt setgcpolicy {table} {family} "maxversions=5 AND maxage=30d"
```
Reference infrastructure_management.md for full syntax.

优先使用Terraform进行生产环境模式变更，以防止意外数据丢失。
对于手动
```
cbt
```
变更，在提出任何修改前，先通过列出表的列族和GC策略检查现有状态：
bash
```
cbt ls {table}
```
若需要修改，创建列族或更新GC策略：
bash
```
cbt createfamily {table} {family}
cbt setgcpolicy {table} {family} "maxversions=5 AND maxage=30d"
```
完整语法请参考infrastructure_management.md。