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 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 consultas de 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 ejemplo, 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.
Console
Para definir un esquema de clave de fila con la Google Cloud consola de, sigue estos pasos:
En la Google Cloud consola de, abre la página Instancias de Bigtable.
Elige una instancia de la lista.
En el menú de navegación, haz clic en Bigtable Studio.
En el panel Explorador, se muestra una lista de tablas, vistas y consultas en la instancia.
En la lista Tablas, para la tabla en la que deseas crear un esquema de clave de fila , haz clic en el menú Ver acciones y, luego, en Crear esquema de clave de fila.
Se abrirá la pestaña Esquema de clave de fila.
En la lista Codificación, selecciona un tipo de codificación para tu esquema de clave de fila.
Si seleccionaste DelimitedBytes, en el campo Delimitador, ingresa un delimitador que separe los segmentos en tus claves de fila existentes. El valor predeterminado es un símbolo de hash (
#).En el campo Segmento, ingresa un nombre para el segmento, como
device_type.En la lista Tipo, selecciona el tipo de datos del segmento de clave de fila.
Según el tipo de datos seleccionado, en la lista Codificación de bytes, deja el tipo de codificación predeterminado del segmento de clave de fila o cámbialo.
Opcional: Si tu segmento de clave de fila tiene más de una parte, haz clic en Agregar segmento de clave de fila para agregar campos adicionales.
Haz clic en Guardar.
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
Console
Para borrar el esquema de clave de fila de una tabla con la Google Cloud consola de, sigue estos pasos:
En la Google Cloud consola de, abre la página Instancias de Bigtable.
Elige una instancia de la lista.
En el menú de navegación, haz clic en Bigtable Studio.
En el panel Explorador, se muestra una lista de tablas, vistas y consultas en la instancia.
En la lista de tablas, haz clic en la tabla con el esquema de clave de fila que deseas borrar.
Haz clic en el menú Ver acciones para el esquema de clave de fila que deseas borrar.
Haz clic en Borrar.
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
Console
Para ver el esquema de clave de fila de una tabla con la Google Cloud consola de, sigue estos pasos:
En la Google Cloud consola de, abre la página Instancias de Bigtable.
Haz clic en la instancia cuyo esquema de clave de fila de la tabla deseas ver.
En el menú de navegación, haz clic en Bigtable Studio.
En el panel Explorador, se muestra una lista de tablas, vistas y consultas en la instancia.
En la lista de tablas, haz clic en la tabla con el esquema de clave de fila que deseas ver.
Haz clic en el esquema de clave de fila.
Se abrirá la pestaña de detalles.
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 la 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=="
}
}
}