このページは Cloud Translation API によって翻訳されました。

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

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

行キースキーマを作成すると、行キーの各セグメントのデータ型とエンコード方法を定義できます。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 bigtable beta 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

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

  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:
  - field_name: "user_id"
    type:
      bytesType:
        encoding:
          raw: {}
  - fieldBame: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      bytes_type:
        encoding:
          utf8Bytes: {}
encoding:
  delimited_bytes:
    delimiter: "#"

JSON

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "bytesType": {
          "encoding": {
            "raw": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "bytesType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "#"
    }
  }
}

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

必要な権限

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

gcloud

Go

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

gcloud

Go

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

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

gcloud

Go

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

スキーマ ファイルの例

YAML

JSON

次のステップ

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

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

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

スキーマファイルの例