Gestionar esquemas de claves de fila
Las claves de fila estructuradas te permiten acceder a tus datos de Bigtable mediante claves de varias partes, de forma similar a las claves compuestas de las bases de datos relacionales. Si defines claves de fila estructuradas para una tabla, puedes acceder a partes específicas de las claves de fila mediante consultas de GoogleSQL para Bigtable.
Si creas un esquema de clave de fila, puedes definir el tipo de datos de cada segmento de una clave de fila y cómo se codifica. Bigtable almacena las claves de las filas como bytes ordenados lexicográficamente, y el esquema de claves de las filas indica a GoogleSQL para Bigtable cómo decodificar e interpretar esos bytes.
Las prácticas recomendadas para diseñar claves de fila se aplican tanto si usas claves de fila estructuradas como si no. Para obtener más información, consulta Claves de fila.
Veamos la siguiente clave de fila de ejemplo, que tiene delimitadores entre los valores de tipo de dispositivo, país, ID de fabricante y número de serie:
`phone#india#pke5preri2eru#8923695`
En el esquema de clave de fila, puede identificar # como delimitador y definir los segmentos de clave de fila de la siguiente manera:
| Segmento de clave de fila | Tipo | Codificación |
|---|---|---|
| Tipo de dispositivo (teléfono) | STRING | UTF-8 |
| País (India) | STRING | UTF-8 |
| ID del fabricante (pke5preri2eru) | STRING | UTF-8 |
| Número de serie (8923695) | BYTES | Sin procesar |
Permisos obligatorios
Los permisos que necesitas dependen de la acción que quieras realizar.
Para obtener estos permisos, pide a tu administrador que te asigne un rol en la tabla que incluya los permisos:
- Ver el esquema de una clave de fila:
bigtable.tables.get - Crea un esquema de clave de fila:
bigtable.tables.update - Para eliminar un esquema de clave de fila, sigue estos pasos:
bigtable.tables.update
Para obtener más información sobre cómo conceder acceso, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.
Crear un esquema de clave de fila
Cuando creas una vista materializada continua, Bigtable crea automáticamente un esquema de clave de fila para la vista. Para obtener más información, consulta Vistas materializadas continuas.
Para definir un esquema de clave de fila para una tabla que no sea una vista materializada continua, actualiza la tabla añadiendo un campo RowKeySchema que se almacene como parte de la tabla.
gcloud
Para definir un esquema de clave de fila con gcloud CLI, usa el comando gcloud beta bigtable tables
update con un archivo YAML o JSON que defina el 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
Haz los cambios siguientes:
- TABLE_ID: el ID único de la tabla que quieres actualizar
- INSTANCE_ID: el ID de la instancia en la que se encuentra la tabla
- ROW_KEY_SCHEMA_DEFINITION_FILE: la ruta a tu archivo YAML o JSON que define el esquema de clave de fila. Para ver ejemplos de cómo deben ser esos archivos, consulta Example-schema-files.
De forma predeterminada, la codificación Base64 se aplica a todos los campos binarios de un archivo YAML o JSON, como encoding.delimitedBytes.delimiter para el delimitador de la clave de fila. La marca --row-key-schema-pre-encoded-bytes indica a Bigtable que los campos binarios están codificados en el archivo y no se deben volver a codificar.
Go
Usa la función UpdateTableWithRowKeySchema para crear un esquema de clave de fila para una tabla.
func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error
En el siguiente ejemplo se crea un esquema llamado rks y se añade a la tabla.
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)
Eliminar un esquema de clave de fila
gcloud
Para eliminar el esquema de clave de fila de una tabla, usa el comando
gcloud beta bigtable tables
update
con la marca --clear-row-key-schema.
gcloud beta bigtable tables update TABLE_NAME \
--instance=INSTANCE_ID \
--clear-row-key-schema
Haz los cambios siguientes:
- TABLE_NAME: el nombre único de la tabla de la que quieres eliminar el esquema de clave de fila.
- INSTANCE_ID: el ID de la instancia en la que se encuentra la tabla
Go
Usa la función UpdateTableRemoveRowKeySchema para borrar el esquema de clave de fila de una tabla:
func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error
Modificar un esquema de clave de fila
No puedes modificar directamente un esquema de clave de fila. Para cambiar un esquema de clave de fila, debes eliminar el esquema y crear uno nuevo que incluya los cambios.
Ver un esquema de clave de fila
gcloud
Para ver un esquema de clave de fila, usa el comando gcloud beta bigtable tables
describe:
gcloud bigtable tables describe TABLE_NAME \
--instance=INSTANCE_ID
Haz los cambios siguientes:
- TABLE_NAME: nombre único de la tabla cuyo esquema de clave de fila quieres ver
- INSTANCE_ID: el ID de la instancia en la que se encuentra la tabla
La respuesta en el terminal es similar a la siguiente. Si la tabla no tiene un esquema de clave de fila, la respuesta no incluye una sección 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
El campo RowKeySchema está disponible como parte del objeto TableInfo y se obtiene mediante el método .TableInfo().
type TableInfo struct {
...
RowKeySchema *StructType
}
func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)
Consultar claves de fila estructuradas
Para consultar las columnas de las claves de fila estructuradas, debes usar SQL. El método ReadRows de la API Data de Bigtable ignora un esquema de clave de fila cuando lee de una tabla.
Para ver ejemplos de consultas que seleccionan claves de fila estructuradas, consulta Consultas de claves de fila estructuradas.
Para ver una lista de bibliotecas de cliente de Bigtable que admiten consultas de SQL, incluidos ejemplos de código, consulta Usar SQL con una biblioteca de cliente de Bigtable.
Ejemplos de archivos de esquema
Cuando creas un esquema de clave de fila con la CLI de gcloud, puedes definir las claves de fila estructuradas con un archivo YAML o 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=="
}
}
}