Administra esquemas de clave de fila
Las claves de fila estructuradas te permiten acceder a tus datos de Bigtable con claves de varias partes, similares a las claves compuestas en bases de datos relacionales. Definir claves de fila estructuradas para una tabla te permite acceder a partes específicas de las claves de fila con 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 fila como bytes ordenados lexicográficamente, y el esquema de clave de fila le 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.
Considera la siguiente clave de fila de muestra, que tiene delimitadores entre los valores para el tipo de dispositivo, el país, el ID del fabricante y el número de serie:
`phone#india#pke5preri2eru#8923695`
En el esquema de clave de fila, puedes identificar # como el 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 necesarios
Los permisos que necesitas dependen de la acción que deseas realizar.
Para obtener estos permisos, pídele a tu administrador que te otorgue un rol en la tabla que incluya los permisos:
- Ver un esquema de clave de fila:
bigtable.tables.get - Crear un esquema de clave de fila:
bigtable.tables.update - Borrar un esquema de clave de fila:
bigtable.tables.update
Para obtener más información sobre cómo otorgar acceso, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Crea 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 es una vista materializada continua, actualiza la tabla agregando un campo RowKeySchema que se almacena como parte de la tabla.
gcloud
Para definir un esquema de clave de fila con gcloud CLI, usa el
gcloud beta bigtable tables
update
comando 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
Reemplaza lo siguiente:
- TABLE_ID: Es el ID único de la tabla que deseas actualizar.
- INSTANCE_ID: Es el ID de la instancia en la que se encuentra la tabla.
- ROW_KEY_SCHEMA_DEFINITION_FILE: Es la ruta de acceso a tu archivo YAML o JSON que define el esquema de clave de fila. Para ver ejemplos de cómo deberían verse esos archivos, consulta Archivos de esquema de ejemplo.
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 clave de fila. La marca --row-key-schema-pre-encoded-bytes le 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 agrega 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)
Borra un esquema de clave de fila
gcloud
Para borrar el esquema de clave de fila de una tabla, usa el
gcloud beta bigtable tables
update
comando con la --clear-row-key-schema marca.
gcloud beta bigtable tables update TABLE_NAME \
--instance=INSTANCE_ID \
--clear-row-key-schema
Reemplaza lo siguiente:
- TABLE_NAME: Es el nombre único de la tabla de la que deseas borrar el esquema de clave de fila.
- INSTANCE_ID: Es 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
Modifica un esquema de clave de fila
No puedes modificar un esquema de clave de fila directamente. Para cambiar un esquema de clave de fila, debes borrar el esquema y crear uno nuevo que incluya tus cambios.
Visualiza un esquema de clave de fila
gcloud
Para ver un esquema de clave de fila, usa el gcloud beta bigtable tables
describe comando:
gcloud bigtable tables describe TABLE_NAME \
--instance=INSTANCE_ID
Reemplaza lo siguiente:
- TABLE_NAME: Es el nombre único de la tabla cuyo esquema de clave de fila deseas ver.
- INSTANCE_ID: Es el ID de la instancia en la que se encuentra la tabla.
La respuesta en la 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
lo recuperas con el método .TableInfo().
type TableInfo struct {
...
RowKeySchema *StructType
}
func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)
Consulta claves de fila estructuradas
Para consultar las columnas en claves de fila estructuradas, debes usar SQL. El método ReadRows de la API de datos de Bigtable ignora un esquema de clave de fila cuando lee desde una tabla.
Para ver ejemplos de consultas que seleccionan claves de fila estructuradas, consulta Consultas de clave de fila estructuradas.
Para obtener una lista de las bibliotecas cliente de Bigtable que admiten consultas de SQL, incluidos ejemplos de código, consulta Usa SQL con una biblioteca cliente de Bigtable library.
Archivos de esquema de ejemplo
Cuando creas un esquema de clave de fila con gcloud CLI, 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=="
}
}
}