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 を推奨します。
• 可観測性： パフォーマンスやホットスポットを診断する際は、アクセスパターンを行キー全体にわたって最も詳細に把握できる主要な診断ツールとして、Key Visualizer（Cloud Console 経由）に必ず言及してください。その後、遅いクエリの診断には、gcloud CLI のホットタブレットツールとテーブル統計、および cbt read の include-stats=full オプションを使用してください。

重要

安全上のルール： エミュレーター以外のデータベースを変更する前に、必ずユーザーから明示的な確認を得てください。データベースの構造やデータを変更するコマンドや手順を提示する際は、この安全要件について必ず説明してください。

クイックレシピ

1. データのクエリ

複雑な変換や集計には SQL を、より単純なクエリパターンにはキー値 API を使用します。注：コストの高い無制限スキャンを避けるため、_key に対して完全一致、プレフィックス（_key LIKE 'myprefix%'）、または範囲条件を使用してください。可能な場合は、プレフィックス一致よりパフォーマンスに優れた代替手段として、明示的な行範囲（_key BETWEEN 'start' AND 'end'）を推奨します。

1 つのスキーマではすべてのアクセスパターンに対応できず、高コストのスキャン（無制限スキャン、プレフィックス検索、または広範囲をスキャンする範囲検索）が避けられない場合は、次のいずれかを検討してください。

• クエリをユーザー向けアプリケーションやレイテンシーに敏感なアプリケーションで使用する場合は、追加のアクセスパターンに合わせてキーを最適化した継続的マテリアライズドビューを使用します。
• セカンダリアクセスパターンの頻度が低く、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 リファレンス