Gestire gli schemi delle chiave di riga
Le chiavi di riga strutturate ti consentono di accedere ai dati Bigtable utilizzando chiavi in più parti, simili alle chiavi composite nei database relazionali. La definizione di chiavi di riga strutturate per una tabella consente di accedere a parti specifiche delle chiavi di riga utilizzando GoogleSQL per le query Bigtable.
Creando uno schema della chiave di riga, puoi definire il tipo di dati di ogni segmento di una chiave di riga e la relativa codifica. Bigtable archivia le chiavi di riga come byte ordinati lessicograficamente e lo schema della chiave di riga indica a GoogleSQL per Bigtable come decodificare e interpretare questi byte.
Le best practice per la progettazione delle chiavi di riga si applicano indipendentemente dal fatto che tu stia utilizzando o meno le chiavi di riga strutturate. Per ulteriori informazioni, vedi Chiavi di riga.
Considera la seguente chiave di riga di esempio, che ha delimitatori tra i valori per il tipo di dispositivo, il paese, l'ID produttore e il numero di serie:
`phone#india#pke5preri2eru#8923695`
Nello schema della chiave di riga, puoi identificare # come delimitatore e definire i segmenti della chiave di riga come segue:
| Segmento chiave di riga | Tipo | Codifica |
|---|---|---|
| Tipo di dispositivo (telefono) | STRING | UTF-8 |
| Paese (India) | STRING | UTF-8 |
| ID produttore (pke5preri2eru) | STRING | UTF-8 |
| Numero di serie (8923695) | BYTES | Dati |
Autorizzazioni obbligatorie
Le autorizzazioni necessarie dipendono dall'azione che vuoi eseguire.
Per ottenere queste autorizzazioni, chiedi all'amministratore di concederti un ruolo nella tabella che includa le autorizzazioni:
- Visualizzare uno schema della chiave di riga:
bigtable.tables.get - Creare uno schema della chiave di riga:
bigtable.tables.update - Eliminare uno schema della chiave di riga:
bigtable.tables.update
Per saperne di più sulla concessione dell'accesso, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.
Creare uno schema della chiave di riga
Quando crei una vista materializzata continua, Bigtable crea automaticamente uno schema della chiave di riga per la vista. Per ulteriori informazioni, vedi Viste materializzate continue.
Per definire uno schema della chiave di riga per una tabella che non è una vista materializzata continua, aggiorna la tabella aggiungendo un campo RowKeySchema che viene archiviato come parte della tabella.
Console
Per definire uno schema della chiave di riga utilizzando la Google Cloud console, segui questi passaggi:
Nella Google Cloud console, apri la pagina Istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Il riquadro Explorer mostra un elenco di tabelle, viste e query nell'istanza.
Nell'elenco Tabelle, fai clic sul menu Visualizza azioni per la tabella in cui vuoi creare uno schema della chiave di riga e poi fai clic su Crea schema della chiave di riga.
Si apre la scheda Schema della chiave di riga.
Nell'elenco Codifica, seleziona un tipo di codifica per lo schema della chiave di riga.
Se hai selezionato DelimitedBytes, nel campo Delimitatore inserisci un delimitatore che separi i segmenti nelle chiavi di riga esistenti. Il valore predefinito è un simbolo di cancelletto (
#).Nel campo Segmento, inserisci un nome per il segmento, ad esempio
device_type.Nell'elenco Tipo, seleziona il tipo di dati del segmento della chiave di riga.
A seconda del tipo di dati selezionato, nell'elenco Codifica byte, lascia il tipo di codifica predefinito del segmento della chiave di riga o modificalo.
(Facoltativo) Se il segmento della chiave di riga ha più di una parte, fai clic su Aggiungi segmento della chiave di riga per aggiungere altri campi.
Fai clic su Salva.
gcloud
Per definire uno schema della chiave di riga utilizzando la gcloud CLI, utilizza il
gcloud beta bigtable tables
update
comando con un file YAML o JSON che definisce lo schema.
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
Sostituisci quanto segue:
- TABLE_ID: l'ID univoco della tabella che vuoi aggiornare
- INSTANCE_ID: l'ID dell'istanza in cui si trova la tabella
- ROW_KEY_SCHEMA_DEFINITION_FILE: il percorso del file YAML o JSON che definisce lo schema della chiave di riga. Per esempi di come dovrebbero essere questi file, vedi File-schema-di-esempio.
Per impostazione predefinita, la codifica Base64 viene applicata a tutti i campi binari in un file YAML o JSON, ad esempio encoding.delimitedBytes.delimiter per il delimitatore della chiave di riga. Il flag --row-key-schema-pre-encoded-bytes indica a Bigtable che i campi binari sono codificati nel file e non devono essere codificati di nuovo.
Go
Utilizza la funzione UpdateTableWithRowKeySchema per creare uno schema della chiave di riga per una tabella.
func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error
L'esempio seguente crea uno schema denominato rks e lo aggiunge alla tabella.
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)
Eliminare uno schema della chiave di riga
Console
Per eliminare lo schema della chiave di riga di una tabella utilizzando la Google Cloud console, segui questi passaggi:
Nella Google Cloud console, apri la pagina Istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Il riquadro Explorer mostra un elenco di tabelle, viste e query nell'istanza.
Nell'elenco delle tabelle, fai clic sulla tabella con lo schema della chiave di riga che vuoi eliminare.
Fai clic sul menu Visualizza azioni per lo schema della chiave di riga che vuoi eliminare.
Fai clic su Elimina.
gcloud
Per eliminare lo schema della chiave di riga di una tabella, utilizza il
gcloud beta bigtable tables
update
comando con il --clear-row-key-schema flag.
gcloud beta bigtable tables update TABLE_NAME \
--instance=INSTANCE_ID \
--clear-row-key-schema
Sostituisci quanto segue:
- TABLE_NAME: il nome univoco della tabella da cui vuoi eliminare lo schema della chiave di riga
- INSTANCE_ID: l'ID dell'istanza in cui si trova la tabella
Go
Utilizza la funzione UpdateTableRemoveRowKeySchema per cancellare lo schema della chiave di riga di una tabella:
func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error
Modificare uno schema della chiave di riga
Non puoi modificare direttamente uno schema della chiave di riga. Per modificare uno schema della chiave di riga, devi eliminarlo e crearne uno nuovo che includa le modifiche.
Visualizzare uno schema della chiave di riga
Console
Per visualizzare lo schema della chiave di riga di una tabella utilizzando la Google Cloud console, segui questi passaggi:
Nella Google Cloud console, apri la pagina Istanze Bigtable.
Fai clic sull'istanza di cui vuoi visualizzare lo schema della chiave di riga della tabella.
Nel menu di navigazione, fai clic su Bigtable Studio.
Il riquadro Explorer mostra un elenco di tabelle, viste e query nell'istanza.
Nell'elenco delle tabelle, fai clic sulla tabella con lo schema della chiave di riga che vuoi visualizzare.
Fai clic sullo schema della chiave di riga.
Si apre la scheda dei dettagli.
gcloud
Per visualizzare uno schema della chiave di riga, utilizza il gcloud beta bigtable tables
describe comando:
gcloud bigtable tables describe TABLE_NAME \
--instance=INSTANCE_ID
Sostituisci quanto segue:
- TABLE_NAME: il nome univoco della tabella di cui vuoi visualizzare lo schema della chiave di riga
- INSTANCE_ID: l'ID dell'istanza in cui si trova la tabella
La risposta nel terminale è simile alla seguente. Se la tabella non ha uno schema della chiave di riga, la risposta non include una sezione 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
Il campo RowKeySchema è disponibile come parte dell'oggetto TableInfo e
puoi recuperarlo utilizzando il metodo .TableInfo().
type TableInfo struct {
...
RowKeySchema *StructType
}
func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)
Eseguire query sulle chiavi di riga strutturate
Per eseguire query sulle colonne nelle chiavi di riga strutturate, devi utilizzare SQL. Il metodo ReadRows dell'API Bigtable Data ignora uno schema della chiave di riga quando legge da una tabella.
Per esempi di query che selezionano chiavi di riga strutturate, vedi Query sulle chiavi di riga strutturate.
Per un elenco delle librerie client Bigtable che supportano le query SQL, inclusi esempi di codice, vedi Utilizzare SQL con una libreria client Bigtable.
File di schema di esempio
Quando crei uno schema della chiave di riga utilizzando la gcloud CLI, puoi definire le chiavi di riga strutturate utilizzando un file 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=="
}
}
}