管理行键架构

借助结构化行键，您可以使用多部分键（类似于关系数据库中的复合键）访问 Bigtable 数据。为表定义结构化行键后，您可以使用 GoogleSQL for 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 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 文件的路径。如需查看这些文件应采用的格式示例，请参阅示例架构文件。

默认情况下，系统会对 YAML 或 JSON 文件中的所有二进制字段（例如行键分隔符 encoding.delimitedBytes.delimiter）应用 Base64 编码。标志 --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 客户端库列表（包括代码示例），请参阅将 SQL 与 Bigtable 客户端库搭配使用。

架构文件示例

使用 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=="
    }
  }
}

后续步骤