Crea e gestisci schemi Avro

Gli schemi Apache Avro in Bigtable ti consentono di eseguire query su singoli campi all'interno dei record Avro che Bigtable archivia come byte serializzati nelle colonne. Per eseguire query su questi campi, carica gli schemi Avro in formato JSON in un bundle di schemi, una risorsa a livello di tabella che contiene uno o più schemi di record Avro. Per saperne di più sugli schemi Apache Avro, consulta la documentazione di Apache Avro.

Il caricamento di un bundle di schemi Avro non modifica il modo in cui scrivi i dati in Bigtable. Continui a scrivere record Avro come byte serializzati. Il payload della cella deve contenere solo i byte non elaborati, senza uno schema incorporato o un fingerprint dello schema.

Dopo aver caricato un bundle di schemi in Bigtable, puoi eseguire query sui dati Avro utilizzando GoogleSQL per Bigtable, viste materializzate continue o viste logiche.

Prima di iniziare

Prima di creare e gestire i bundle di schemi Avro, segui questi passaggi:

  1. Installa Google Cloud CLI.

  2. Inizializza gcloud CLI:

    gcloud init

  3. Assicurati di avere un'istanza e una tabella Bigtable.

  4. Abilita l'API Cloud Bigtable e l'API Cloud Bigtable Admin:

    gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire i bundle di schemi, chiedi all'amministratore di concederti il ruolo IAM (Identity and Access Management) Bigtable Administrator (roles/bigtable.admin) sulla tabella.

Per ottenere l'accesso di sola lettura ai bundle di schemi ed eseguire query sui record Avro utilizzando GoogleSQL per Bigtable, chiedi all'amministratore di concederti il ruolo Bigtable Reader (roles/bigtable.reader) o Bigtable User (roles/bigtable.user) sulla tabella.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per lavorare con i bundle di schemi ed eseguire query sui dati Avro. Per visualizzare le autorizzazioni richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per creare e gestire i bundle di schemi, devi disporre delle seguenti autorizzazioni a livello di tabella o di bundle di schemi, a seconda dell'operazione:

  • bigtable.schemaBundles.create: crea bundle di schemi per una tabella
  • bigtable.schemaBundles.update: aggiorna la definizione di un bundle di schemi
  • bigtable.schemaBundles.delete: elimina un bundle di schemi
  • bigtable.schemaBundles.get: ottieni informazioni su un bundle di schemi
  • bigtable.schemaBundles.list: elenca i bundle di schemi in una tabella
  • bigtable.schemaBundles.getIamPolicy: recupera la policy IAM per un bundle di schemi
  • bigtable.schemaBundles.setIamPolicy: imposta la policy IAM per un bundle di schemi

Per leggere o filtrare i record Avro utilizzando GoogleSQL per Bigtable, devi disporre delle seguenti autorizzazioni:

  • bigtable.tables.readRows
  • bigtable.instances.executeQuery

Puoi anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più sui ruoli e sulle autorizzazioni di Bigtable, consulta Controllo dell'accesso con IAM.

Prepara i file di schema Avro

Prima di creare un bundle di schemi Avro, prepara uno o più file di schema Avro formattati in JSON nel formato file AVSC o JSON. Ogni file deve contenere uno schema Avro record valido e autonomo al livello più alto con tutte le dipendenze in linea. Se più file di un bundle incorporano lo stesso record o enum nello stesso spazio dei nomi, le definizioni devono corrispondere, inclusi doc e aliases.

Crea un bundle di schemi Avro

Per creare un bundle di schemi Avro in una tabella, utilizza il comando gcloud bigtable schema-bundles create:

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

Sostituisci quanto segue:

  • SCHEMA_BUNDLE_ID: un ID univoco per il bundle di schemi. L'ID deve avere una lunghezza compresa tra 1 e 50 caratteri, può contenere solo lettere, numeri, trattini bassi e trattini, non può iniziare con un trattino e non può contenere un punto (.).
  • INSTANCE_ID: l'ID dell'istanza che contiene la tabella.
  • TABLE_ID: l'ID della tabella in cui creare il bundle di schemi.
  • AVRO_SCHEMA_PATH: il percorso di un file di schema Avro in formato JSON o di una directory contenente uno o più file di schema Avro. Ogni file deve essere un oggetto JSON autonomo con tutte le dipendenze incorporate.

Visualizza informazioni sui bundle di schemi

Puoi visualizzare le informazioni sui bundle di schemi in una tabella recuperando la definizione di un singolo bundle di schemi o elencando tutti i bundle di schemi nella tabella.

Ottieni una definizione del bundle di schemi Avro

Per recuperare la definizione dello schema Avro in formato JSON per un bundle di schemi, utilizza il comando gcloud bigtable schema-bundles describe:

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Sostituisci quanto segue:

  • SCHEMA_BUNDLE_ID: l'ID del bundle di schemi
  • INSTANCE_ID: l'ID dell'istanza
  • TABLE_ID: l'ID della tabella

Elenca i bundle di schemi in una tabella

Per elencare gli ID di tutti i bundle di schemi in una tabella, inclusi i bundle di schemi Avro e protobuf, utilizza il comando gcloud bigtable schema-bundles list:

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Sostituisci quanto segue:

  • INSTANCE_ID: l'ID dell'istanza
  • TABLE_ID: l'ID della tabella

Per esaminare le definizioni dello schema sottostante per un bundle di schemi specifico dall'elenco, esegui il comando gcloud bigtable schema-bundles describe.

Aggiorna un bundle di schemi Avro

Per aggiornare un bundle di schemi Avro, utilizza il comando gcloud bigtable schema-bundles update. Puoi solo aggiungere nuove definizioni di record o enum Avro a un bundle di schemi Avro esistente e non puoi modificare il tipo di un bundle di schemi tra Avro e protobuf. Quando aggiorni il bundle, devi passare un file o una directory che includa sia i nuovi schemi sia tutti quelli esistenti.

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

Sostituisci quanto segue:

  • SCHEMA_BUNDLE_ID: l'ID del bundle di schemi da aggiornare
  • INSTANCE_ID: l'ID dell'istanza che contiene il bundle di schemi
  • TABLE_ID: l'ID della tabella che contiene il bundle di schemi
  • AVRO_SCHEMA_PATH: il percorso di un file di schema Avro in formato JSON o di una directory contenente uno o più file di schema Avro

Elimina un bundle di schemi Avro

Se una vista materializzata continua o una vista logica fa riferimento a un bundle di schemi, non puoi eliminare il bundle. Prima di eliminare il bundle, elimina tutte le viste materializzate continue che fanno riferimento al bundle. Per tutte le visualizzazioni logiche che fanno riferimento al bundle, aggiornale per rimuovere il riferimento o eliminale. Per saperne di più, consulta Crea e gestisci viste materializzate continue o Crea e gestisci viste logiche.

Per eliminare un bundle di schemi Avro, utilizza il comando gcloud bigtable schema-bundles delete:

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Sostituisci quanto segue:

  • SCHEMA_BUNDLE_ID: l'ID del bundle di schemi da eliminare
  • INSTANCE_ID: l'ID dell'istanza che contiene il bundle di schemi
  • TABLE_ID: l'ID della tabella che contiene il bundle di schemi

Prezzi

Non sono previsti costi aggiuntivi per la creazione o la gestione dei bundle di schemi Avro. Per le richieste e le risposte vengono applicati i costi standard per la larghezza di banda di rete. Se utilizzi il serverless computing di Data Boost per leggere i dati da Bigtable, paghi per le risorse di computing utilizzate dalle query. Per saperne di più, consulta i prezzi di Bigtable.

Limitazioni

I bundle di schemi Avro presentano le seguenti limitazioni:

  • Puoi leggere ed eseguire query su una colonna come record Avro utilizzando GoogleSQL per Bigtable, viste materializzate continue e viste logiche. L'API Bigtable ReadRows e le tabelle esterne BigQuery non supportano l'analisi Avro lato server.
  • Puoi creare fino a 10 bundle di schemi per tabella. Questo limite si applica sia ai bundle di schemi Avro che a quelli di Protobuf.
  • La dimensione totale degli schemi Avro in formato JSON all'interno di un singolo bundle di schemi non può superare i 4 MB. Bigtable converte anche il bundle in un set di descrittori protobuf interno, che non può superare i 4 MB.
  • Bigtable non supporta i seguenti tipi di schema, strutture e pattern di denominazione Avro:
    • Il tipo fixed e i tipi logici, come date, duration, time-micros e uuid.
    • Unioni con più rami con più di un tipo non null. Sono supportate solo le unioni nullable, come ["null", "string"].
    • Raccolte nidificate, come array o mappe, che contengono altri array o mappe.
    • Array con elementi nullable. Le mappe con valori nullable, come {"type": "map", "values": ["null", "string"]}, sono supportate.
    • Array con elementi di record vuoti e senza campi.
    • Definizioni di record cicliche o ricorsive o riferimenti a record e oggetti JSON complessi, come record, array, mappe ed enum in linea, nidificati a più di 32 livelli.
    • Trattini bassi (_) nei valori Avro namespace.
    • Nomi di simboli enum duplicati in diversi tipi di enum nello stesso spazio dei nomi.
    • Più campi map nello stesso record i cui nomi vengono convertiti nella stessa stringa in notazione a cammello, ad esempio my_map, myMap e my__map.
  • Quando esegue query sui dati, Bigtable ignora alcuni attributi dello schema Avro, come i valori predefiniti dei campi (default), aliases, doc e l'ordinamento (order). Tuttavia, se più file in un bundle definiscono lo stesso record o enum nello stesso spazio dei nomi, le loro definizioni devono corrispondere, inclusi doc e aliases.

Passaggi successivi