管理資料列鍵結構定義

結構化資料列索引鍵可讓您使用多部分索引鍵存取 Bigtable 資料，類似於關係資料庫中的複合索引鍵。為資料表定義結構化資料列鍵後，您就能使用 GoogleSQL 查詢 Bigtable，存取資料列鍵的特定部分。

建立資料列鍵結構定義後，即可定義資料列鍵各區段的資料類型，以及編碼方式。Bigtable 會將資料列鍵儲存為按字典順序排序的位元組，而資料列鍵結構定義會告知 GoogleSQL for Bigtable 如何解碼及解讀這些位元組。

無論是否使用結構化資料列鍵，設計資料列鍵的最佳做法都適用。詳情請參閱「列鍵」。

請參考下列範例資料列鍵，其中裝置類型、國家/地區、製造商 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 定義資料列鍵結構定義，請搭配使用 gcloud beta bigtable tables update 指令，以及定義結構定義的 YAML 或 JSON 檔案。

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 檔案路徑。如要查看這些檔案的範例，請參閱「Example-schema-files」。

根據預設，系統會對 YAML 或 JSON 檔案中的所有二進位欄位套用 Base64 編碼，例如資料列鍵分隔符號的 encoding.delimitedBytes.delimiter。--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:
  - 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": "#"
    }
  }
}

後續步驟