行キーのスキーマを管理する

構造化された行キーを使用すると、リレーショナルデータベースの複合キーと同様に、マルチパートキーを使用して Bigtable データにアクセスできます。テーブルに行キーを構造化して定義すると、Bigtable 用の GoogleSQL クエリを使用して、行キーの特定の部分にアクセスできます。

行キーのスキーマを作成すると、行キーの各セグメントのデータ型とエンコード方法を定義できます。Bigtable は、行キーを辞書順に並べ替えられたバイトとして保存します。行キーのスキーマは、これらのバイトをデコードして解釈する方法を Bigtable 用の GoogleSQL に伝えます。

行キーを構造化するかどうかに関係なく、行キーを設計するためのベストプラクティスが適用されます。詳細については、行キーをご覧ください。

デバイスの種類、国、製造元 ID、シリアル番号の値の間に区切り文字がある次の行キーの例を考えてみましょう。

`phone#india#pke5preri2eru#8923695`

行キーのスキーマでは、# を区切り文字として識別し、行キーのセグメントを次のように定義します。

行キーのセグメント	型	エンコード
デバイスの種類（スマートフォン）	STRING	UTF-8
国（インド）	STRING	UTF-8
製造元 ID（pke5preri2eru）	STRING	UTF-8
シリアル番号（8923695）	BYTES	未加工

必要な権限

必要な権限は、実行するアクションによって異なります。

これらの権限を取得するには、管理者に依頼して、権限を含むテーブルのロールを付与してもらいます。

行キーのスキーマを表示する: bigtable.tables.get
行キーのスキーマを作成する: bigtable.tables.update
行キーのスキーマを削除する: bigtable.tables.update

アクセス権の付与の詳細については、プロジェクト、フォルダ、組織へのアクセスの管理をご覧ください。

行キーのスキーマを作成する

継続的なマテリアライズドビューを作成すると、Bigtable はビューの行キーのスキーマを自動的に作成します。詳細については、継続的なマテリアライズドビューをご覧ください。

継続的なマテリアライズドビューではないテーブルの行キーのスキーマを定義するには、テーブルの一部として保存される RowKeySchema フィールドを追加してテーブルを更新します。

gcloud

gcloud CLI を使用して行キーのスキーマを定義するには、スキーマを定義する YAML ファイルまたは JSON ファイルを指定して gcloud beta bigtable tables update コマンドを使用します。

gcloud beta bigtable tables update TABLE_ID \
  --instance=INSTANCE_ID \
  --row-key-schema-definition-file=ROW_KEY_SCHEMA_DEFINITION_FILE \
  --row-key-schema-pre-encoded-bytes

次のように置き換えます。

TABLE_ID: 更新するテーブルの一意の ID
INSTANCE_ID: テーブルが配置されているインスタンスの ID
ROW_KEY_SCHEMA_DEFINITION_FILE: 行キーのスキーマを定義する YAML ファイルまたは JSON ファイルのパス。これらのファイルの形式の例については、スキーマファイルの例をご覧ください。

デフォルトでは、Base64 エンコードは、行キーの区切り文字の encoding.delimitedBytes.delimiter など、YAML ファイルまたは JSON ファイル内のすべてのバイナリフィールドに適用されます。--row-key-schema-pre-encoded-bytes フラグは、ファイル内のバイナリフィールドがエンコード済みであり、再度エンコードしないように Bigtable に指示します。

Go

UpdateTableWithRowKeySchema 関数を使用して、テーブルの行キーのスキーマを作成します。

func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error

次の例では、rks という名前のスキーマを作成してテーブルに追加します。

rks := StructType{
Fields: []StructField{
    {FieldName: "key1", FieldType: Int64Type{Encoding: Int64OrderedCodeBytesEncoding{}}},
    {FieldName: "key2", FieldType: StringType{Encoding: StringUtf8BytesEncoding{}}},
  },
  Encoding: StructDelimitedBytesEncoding{Delimiter: []byte{'#'}}}

err := c.UpdateTableWithRowKeySchema(context.Background(), "my-table", rks)

行キーのスキーマを削除する

gcloud

テーブルの行キーのスキーマを削除するには、 gcloud beta bigtable tables update コマンドを--clear-row-key-schemaフラグとともに使用します。

  gcloud beta bigtable tables update TABLE_NAME \
    --instance=INSTANCE_ID \
    --clear-row-key-schema

次のように置き換えます。

TABLE_NAME: 行キーのスキーマを削除するテーブルの一意の名前
INSTANCE_ID: テーブルが配置されているインスタンスの ID

Go

UpdateTableRemoveRowKeySchema 関数を使用して、テーブルの行キーのスキーマをクリアします。

func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error

行キーのスキーマを変更する

行キーのスキーマを直接変更することはできません。行キーのスキーマを変更するには、スキーマを削除して、変更内容を含む新しいスキーマを作成する必要があります。

行キーのスキーマを表示する

gcloud

行キーのスキーマを表示するには、gcloud beta bigtable tables describe コマンドを使用します。

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

次のように置き換えます。

TABLE_NAME: 行キーのスキーマを表示するテーブルの一意の名前
INSTANCE_ID: テーブルが配置されているインスタンスの ID

ターミナルのレスポンスは次のようになります。テーブルに行キーのスキーマがない場合、レスポンスに rowKeySchema セクションは含まれません。

columnFamilies:
  cf: {}
createTime: '2025-05-28T17:25:39.433058Z'
granularity: MILLIS
name: projects/<project>/instances/<instance>/tables/<table>
rowKeySchema:
  encoding:
    delimitedBytes:
      delimiter: Iw==
  fields:
  - fieldName: <field_name_1>
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: <field_name_2>
    type:
      intType:
        encoding:
          bigEndianBytes: {}
  - fieldName: <field_name_3>
    type:
      timestampType:
        encoding:
          unixMicrosInt64: {
              encoding: {
                  orderedCodeBytes: {}
              }
          }
updateTime: '2025-05-28T17:25:39.433058Z'

Go

RowKeySchema フィールドは TableInfo オブジェクトの一部として使用できます。このフィールドを取得するには、.TableInfo() メソッドを使用します。

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)

構造化された行キーのクエリ

構造化された行キーの列に対してクエリを実行するには、SQL を使用する必要があります。Bigtable Data API の ReadRows メソッドは、テーブルから読み取る際に、行キーのスキーマを無視します。

構造化された行キーを選択するクエリの例については、構造化された行キーのクエリをご覧ください。

コードサンプルなど、SQL クエリをサポートする Bigtable クライアントライブラリの一覧については、Bigtable クライアントライブラリで SQL を使用するをご覧ください。

スキーマファイルの例

gcloud CLI を使用して行キーのスキーマを作成する場合は、YAML ファイルまたは JSON ファイルを使用して、構造化された行キーを定義できます。

YAML

fields:
  - fieldName: "user_id"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
encoding:
  delimitedBytes:
    delimiter: "Iw=="

JSON

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "Iw=="
    }
  }
}

行キーのスキーマを管理する

必要な権限

行キーのスキーマを作成する

gcloud

Go

行キーのスキーマを削除する

gcloud

Go

行キーのスキーマを変更する

行キーのスキーマを表示する

gcloud

Go

構造化された行キーのクエリ

スキーマ ファイルの例

YAML

JSON

次のステップ

スキーマファイルの例