Administra esquemas de clave de fila
Las claves de fila estructuradas te permiten acceder a tus datos de Bigtable con claves de varias partes, de forma similar a las claves compuestas en las 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 GoogleSQL para las consultas de Bigtable.
Si creas un esquema de claves 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 del 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:
- Visualiza un esquema de clave de fila:
bigtable.tables.get - Crea un esquema de clave de fila:
bigtable.tables.update - Borra 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, debes actualizar la tabla agregando 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 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
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 la clave de fila. Para ver ejemplos de cómo deberían verse esos archivos, consulta Example-schema-files.
De forma predeterminada, la codificación Base64 se aplica a todos los campos binarios en 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 codificar de nuevo.
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 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
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 la clave de fila de una tabla:
func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error
Cómo modificar 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.
Cómo 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
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)
Cómo consultar claves de filas estructuradas
Para consultar las columnas en las claves de filas estructuradas, debes usar SQL. El método ReadRows de la API de Bigtable Data 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 claves de fila estructuradas.
Para obtener una lista de las bibliotecas cliente de Bigtable que admiten consultas SQL, incluidos ejemplos de código, consulta Usa SQL con una biblioteca cliente de Bigtable.
Ejemplos de archivos de esquema
Cuando creas un esquema de clave de fila con gcloud CLI, puedes definir las claves de filas estructuradas con un archivo YAML o un archivo JSON.
YAML
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: "#"
JSON
{
"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": "#"
}
}
}