Faça a gestão dos esquemas de chaves de linhas
As chaves de linhas estruturadas permitem-lhe aceder aos seus dados do Bigtable através de chaves de várias partes, semelhantes às chaves compostas em bases de dados relacionais. A definição de chaves de linhas estruturadas para uma tabela permite-lhe aceder a partes específicas das chaves de linhas através do GoogleSQL para consultas do Bigtable.
Ao criar um esquema de chave de linha, pode definir o tipo de dados de cada segmento de uma chave de linha e como é codificado. O Bigtable armazena as chaves de linhas como bytes ordenados lexicograficamente, e o esquema de chaves de linhas indica ao GoogleSQL para Bigtable como descodificar e interpretar esses bytes.
As práticas recomendadas para criar chaves de linhas aplicam-se quer esteja a usar chaves de linhas estruturadas ou não. Para mais informações, consulte o artigo Teclas de linha.
Considere a seguinte chave de linha de exemplo, que tem delimitadores entre os valores para o tipo de dispositivo, o país, o ID do fabricante e o número de série:
`phone#india#pke5preri2eru#8923695`
No esquema de chaves de linhas, pode identificar # como o delimitador e definir os segmentos de chaves de linhas da seguinte forma:
| Segmento de chave da linha | Tipo | Codificação |
|---|---|---|
| Tipo de dispositivo (telemóvel) | STRING | UTF-8 |
| País (Índia) | STRING | UTF-8 |
| ID do fabricante (pke5preri2eru) | STRING | UTF-8 |
| Número de série (8923695) | BYTES | Não processados |
Autorizações necessárias
As autorizações de que precisa dependem da ação que quer realizar.
Para obter estas autorizações, peça ao seu administrador para lhe atribuir uma função na tabela que inclua as autorizações:
- Veja um esquema de chave de linha:
bigtable.tables.get - Crie um esquema de chave de linha:
bigtable.tables.update - Elimine um esquema de chave de linha:
bigtable.tables.update
Para mais informações sobre como conceder acesso, consulte o artigo Gerir o acesso a projetos, pastas e organizações.
Crie um esquema de chave de linha
Quando cria uma vista materializada contínua, o Bigtable cria automaticamente um esquema de chave de linha para a vista. Para mais informações, consulte o artigo Vistas materializadas contínuas.
Para definir um esquema de chave de linha para uma tabela que não seja uma vista materializada contínua, atualize a tabela adicionando um campo RowKeySchema que é armazenado como parte da tabela.
gcloud
Para definir um esquema de chave de linha através da CLI gcloud, use o comando
gcloud beta bigtable tables
update com um ficheiro YAML ou JSON que defina o esquema.
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
Substitua o seguinte:
- TABLE_ID: o ID exclusivo da tabela que quer atualizar
- INSTANCE_ID: o ID da instância onde a tabela se encontra
- ROW_KEY_SCHEMA_DEFINITION_FILE: o caminho para o ficheiro YAML ou JSON que define o esquema da chave da linha. Para ver exemplos do aspeto que esses ficheiros devem ter, consulte o artigo Ficheiros de esquema de exemplo.
Por predefinição, a codificação Base64 é aplicada a todos os campos binários num ficheiro YAML ou JSON, como encoding.delimitedBytes.delimiter para o delimitador da chave da linha. A flag --row-key-schema-pre-encoded-bytes indica ao Bigtable que os campos binários estão codificados no ficheiro e não devem ser codificados novamente.
Go
Use a função UpdateTableWithRowKeySchema para criar um esquema de chave de linha para uma tabela.
func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error
O exemplo seguinte cria um esquema denominado rks e adiciona-o à tabela.
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)
Elimine um esquema de chave de linha
gcloud
Para eliminar o esquema da chave de linha de uma tabela, use o comando
gcloud beta bigtable tables
update
com a flag --clear-row-key-schema.
gcloud beta bigtable tables update TABLE_NAME \
--instance=INSTANCE_ID \
--clear-row-key-schema
Substitua o seguinte:
- TABLE_NAME: o nome exclusivo da tabela da qual quer eliminar o esquema da chave da linha
- INSTANCE_ID: o ID da instância onde a tabela se encontra
Go
Use a função UpdateTableRemoveRowKeySchema para limpar o esquema de chaves de linhas
de uma tabela:
func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error
Modifique um esquema de chave de linha
Não pode modificar diretamente um esquema de chave de linha. Para alterar um esquema de chave de linha, tem de eliminar o esquema e criar um novo que inclua as alterações.
Veja um esquema de chaves de linhas
gcloud
Para ver um esquema de chave de linha, use o comando gcloud beta bigtable tables
describe:
gcloud bigtable tables describe TABLE_NAME \
--instance=INSTANCE_ID
Substitua o seguinte:
- TABLE_NAME: o nome exclusivo da tabela cujo esquema de chave de linha quer ver
- INSTANCE_ID: o ID da instância onde a tabela se encontra
A resposta no terminal é semelhante à seguinte. Se a tabela não tiver um esquema de chave de linha, a resposta não inclui uma secção 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
O campo RowKeySchema está disponível como parte do objeto TableInfo e
pode obtê-lo através do método .TableInfo().
type TableInfo struct {
...
RowKeySchema *StructType
}
func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)
Consultar chaves de linhas estruturadas
Para consultar as colunas em chaves de linhas estruturadas, tem de usar SQL. O método
Bigtable Data API ReadRows ignora um esquema de chave de linha quando
lê a partir de uma tabela.
Para ver exemplos de consultas que selecionam chaves de linhas estruturadas, consulte o artigo Consultas de chaves de linhas estruturadas.
Para ver uma lista de bibliotecas cliente do Bigtable que suportam consultas SQL, incluindo exemplos de código, consulte o artigo Use SQL with a Bigtable client library (Use SQL com uma biblioteca cliente do Bigtable).
Ficheiros de esquema de exemplo
Quando cria um esquema de chave de linha através da CLI gcloud, pode definir as chaves de linha estruturadas através de um ficheiro YAML ou de um ficheiro 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=="
}
}
}