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:

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 ulteriori informazioni sulla concessione dell'accesso, vedi 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 archiviato come parte della tabella.

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

func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error

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

  gcloud beta bigtable tables update TABLE_NAME \
    --instance=INSTANCE_ID \
    --clear-row-key-schema

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

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

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'

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.

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=="

{
  "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=="
    }
  }
}

Passaggi successivi

• Creare e gestire viste materializzate continue
• Panoramica di GoogleSQL per Bigtable