Gerenciar esquemas de chave de linha

Com as chaves de linha estruturadas, é possível acessar os dados do Bigtable usando chaves de várias partes, semelhantes às chaves compostas em bancos de dados relacionais. Ao definir chaves de linha estruturadas para uma tabela, é possível acessar partes específicas delas usando o GoogleSQL para consultas do Bigtable.

Ao criar um esquema de chave de linha, é possível definir o tipo de dados de cada segmento de uma chave de linha e como ele é codificado. O Bigtable armazena as chaves de linha como bytes classificados lexicograficamente, e o esquema de chave de linha informa ao GoogleSQL para Bigtable como decodificar e interpretar esses bytes.

As práticas recomendadas para projetar chaves de linha se aplicam ao uso de chaves de linha estruturadas ou não. Para mais informações, consulte Chaves de linha.

Considere a seguinte chave de linha de exemplo, que tem delimitadores entre valores para tipo de dispositivo, país, ID do fabricante e número de série:

`phone#india#pke5preri2eru#8923695`

No esquema da chave de linha, você pode identificar # como o delimitador e definir os segmentos da chave de linha da seguinte maneira:

Permissões necessárias

As permissões necessárias dependem da ação que você quer realizar.

Para receber essas permissões, peça ao administrador para conceder a você um papel na tabela que inclui as permissões:

• Ver um esquema de chave de linha: bigtable.tables.get
• Crie um esquema de chave de linha: bigtable.tables.update
• Excluir um esquema de chave de linha: bigtable.tables.update

Para mais informações sobre como conceder acesso, consulte Gerenciar o acesso a projetos, pastas e organizações.

Criar um esquema de chave de linha

Quando você cria uma visualização materializada contínua, o Bigtable gera automaticamente um esquema de chave de linha para a visualização. Para mais informações, consulte Visualizações materializadas contínuas.

Para definir um esquema de chave de linha para uma tabela que não seja uma visualização materializada contínua, atualize a tabela adicionando um campo RowKeySchema armazenado como parte dela.

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

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

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)

Excluir um esquema de chave de linha

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

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

Modificar um esquema de chave de linha

Não é possível modificar um esquema de chave de linha diretamente. Para mudar um esquema de chave de linha, é necessário excluir o esquema e criar um novo que inclua suas mudanças.

Ver um esquema de chave de linha

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

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'

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

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

Como consultar chaves de linha estruturadas

Para consultar as colunas em chaves de linha estruturadas, use SQL. O método ReadRows da API Bigtable Data ignora um esquema de chave de linha ao ler de uma tabela.

Para exemplos de consultas que selecionam chaves de linha estruturadas, consulte Consultas de chave de linha estruturada.

Para conferir uma lista de bibliotecas de cliente do Bigtable que oferecem suporte a consultas SQL, incluindo exemplos de código, consulte Usar SQL com uma biblioteca de cliente do Bigtable.

Exemplos de arquivos de esquema

Ao criar um esquema de chave de linha usando a CLI gcloud, é possível definir as chaves de linha estruturadas usando um arquivo YAML ou JSON.

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: "#"

{
  "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": "#"
    }
  }
}

A seguir

• Criar e gerenciar visualizações materializadas contínuas
• Visão geral do GoogleSQL para Bigtable