管理資料列索引鍵結構定義
結構化資料列索引鍵可讓您使用多部分索引鍵存取 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 欄位。
控制台
如要使用 Google Cloud 控制台定義資料列索引鍵結構定義，請按照下列步驟操作：
在 Google Cloud 控制台中，開啟「Bigtable instances」(Bigtable 執行個體) 頁面。
從清單中選取執行個體。
在導覽選單中，按一下「Bigtable Studio」。
「Explorer」窗格會顯示執行個體中的資料表、檢視區塊和查詢清單。
在「資料表」清單中，找到要建立資料列索引鍵結構定義的資料表，然後按一下「查看動作」選單，再點選「建立資料列索引鍵結構定義」。
系統會開啟「資料列索引鍵結構定義」分頁。
在「編碼」清單中，選取資料列索引鍵結構定義的編碼類型。
如果選取「DelimitedBytes」，請在「Delimiter」欄位中輸入分隔符號，用來分隔現有資料列鍵中的區隔。預設值為井號 (
#)。在「Segment」(區隔) 欄位中輸入區隔名稱，例如
device_type。在「類型」清單中，選取資料列索引鍵區隔的資料類型。
視所選資料類型而定，在「位元組編碼」清單中，保留資料列索引鍵區隔的預設編碼類型，或加以變更。
選用：如果資料列索引鍵區隔有多個部分，請按一下「新增資料列索引鍵區隔」新增其他欄位。
按一下 [儲存]。
gcloud
如要使用 gcloud CLI 定義資料列索引鍵結構定義，請使用 gcloud beta bigtable tables
update 指令，並搭配定義結構定義的 YAML 或 JSON 檔案。
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 檔案路徑。如要查看這些檔案的範例，請參閱「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)
刪除資料列索引鍵結構定義
控制台
如要使用 Google Cloud 控制台刪除資料表的資料列索引鍵結構定義，請按照下列步驟操作：
在 Google Cloud 控制台中，開啟「Bigtable instances」(Bigtable 執行個體) 頁面。
從清單中選取執行個體。
在導覽選單中，按一下「Bigtable Studio」。
「Explorer」窗格會顯示執行個體中的資料表、檢視區塊和查詢清單。
在資料表清單中，按一下要刪除資料列索引鍵結構定義的資料表。
找到要刪除的資料列索引鍵結構定義，然後按一下 「查看動作」選單。
點選「刪除」。
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
修改資料列索引鍵結構定義
您無法直接修改資料列索引鍵結構定義。如要變更資料列索引鍵結構定義，請刪除結構定義，然後建立包含變更的新結構定義。
查看資料列索引鍵結構定義
控制台
如要使用 Google Cloud 控制台查看資料表的資料列索引鍵結構定義，請按照下列步驟操作：
在 Google Cloud 控制台中，開啟「Bigtable instances」(Bigtable 執行個體) 頁面。
按一下您要查看資料表資料列索引鍵結構定義的執行個體。
在導覽選單中，按一下「Bigtable Studio」。
「Explorer」窗格會顯示執行個體中的資料表、檢視區塊和查詢清單。
在資料表清單中，按一下要查看資料列索引鍵結構定義的資料表。
按一下資料列索引鍵結構定義。
詳細資料分頁隨即開啟。
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=="
}
}
}