Caricamento dei dati Avro da Cloud Storage

Avro è una piattaforma aperta formato dei dati di origine che raggruppa i dati serializzati con lo schema dei dati nel lo stesso file.

Quando carichi dati Avro da Cloud Storage, puoi caricarli in un nuovo tabella o partizione oppure puoi aggiungere o sovrascrivere una tabella o della partizione di testo. Quando i dati vengono caricati in BigQuery, convertito in formato a colonne per Condensatore (formato di archiviazione di BigQuery).

Quando carichi i dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa regione regionale come bucket Cloud Storage.

Per informazioni sul caricamento dei dati Avro da un file locale, consulta Caricare dati in BigQuery da un'origine dati locale.

Nota: BigQuery non supporta il caricamento autonomo File di schema Avro (.avsc). Per importare uno schema in BigQuery, Specifica un file di schema JSON.

Limitazioni

Quando carichi dati in: BigQuery da un bucket Cloud Storage:

• Se la località del set di dati è impostata su un valore diverso dall'area multiregionale US, il bucket Cloud Storage deve trovarsi nella stessa regione o contenuto nella stessa località (multiregionale) del set di dati.
• BigQuery non garantisce la coerenza dei dati esterni fonti. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono comportare comportamenti imprevisti.
• BigQuery non supporta Controllo delle versioni degli oggetti Cloud Storage. Se includi un numero di generazione nell'URI di Cloud Storage, il job di caricamento non riesce.

Requisiti del file di input

Per evitare resourcesExceeded errori durante il caricamento di file Avro in BigQuery, segui queste linee guida:

• Mantieni le dimensioni delle righe fino a 50 MB o inferiori.
• Se la riga contiene molti campi di array, o campi di array molto lunghi, interrompi i valori dell'array in campi separati.

Prima di iniziare

Concedi ruoli IAM (Identity and Access Management) che concedono agli utenti le risorse necessarie autorizzazioni per eseguire ogni attività in questo documento, in cui archiviare i dati.

Autorizzazioni obbligatorie

Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati nelle tabelle e nelle partizioni BigQuery. Se carichi dati da Cloud Storage, devi disporre anche delle autorizzazioni IAM per accedere al bucket che contiene i dati.

Autorizzazioni per caricare i dati in BigQuery

Per caricare i dati in una nuova tabella o partizione BigQuery oppure per aggiungere o sovrascrivere una tabella o una partizione esistente, devi disporre delle seguenti autorizzazioni IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per caricare i dati in una tabella o una partizione BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (include l'autorizzazione bigquery.jobs.create)
• bigquery.user (include l'autorizzazione bigquery.jobs.create)
• bigquery.jobUser (include l'autorizzazione bigquery.jobs.create)

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi creare e aggiornare le tabelle utilizzando un job di caricamento nei set di dati che crei.

Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Autorizzazioni e ruoli predefiniti.

Autorizzazioni per caricare i dati da Cloud Storage

Per ottenere le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage, chiedi all'amministratore di concederti Ruolo IAM Storage Admin (roles/storage.admin) nel bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per caricare i dati da un bucket Cloud Storage, sono necessarie le seguenti autorizzazioni:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.

crea un set di dati e una tabella

Per archiviare i dati, devi creare un set di dati BigQuery, e poi creerai una tabella BigQuery all'interno del set di dati.

Vantaggi di Avro

Avro è il formato preferito per caricare i dati in BigQuery. Il caricamento di file Avro presenta i seguenti vantaggi rispetto ai file CSV e JSON (newline delimitato):

• Il formato binario Avro:
  • È più veloce da caricare. I dati possono essere letti in parallelo, anche se i blocchi vengono compressi.
  • Non richiede digitazione o serializzazione.
  • È più facile da analizzare perché non sono stati rilevati problemi di codifica in altre formati come ASCII.
• Quando carichi file Avro in BigQuery, lo schema della tabella viene automaticamente dai dati di origine autodescrittivi.

Schemi Avro

Quando carichi file Avro in una nuova tabella BigQuery, la tabella lo schema è recuperate automaticamente utilizzando i dati di origine. Quando BigQuery recupera lo schema dai dati di origine, viene utilizzato l'ultimo file in ordine alfabetico.

Ad esempio, hai i seguenti file Avro in Cloud Storage:

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

L'esecuzione di questo comando nello strumento a riga di comando bq carica tutti i file (come elenco separato da virgole) e lo schema deriva da mybucket/01/b.avro:

bq load \
--source_format=AVRO \
dataset.table \
"gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

Quando importi più file Avro con schemi Avro diversi, tutti gli schemi devono essere compatibili con La risoluzione dello schema di Avro.

Quando BigQuery rileva lo schema, alcuni tipi di dati Avro vengono convertiti in tipi di dati BigQuery per renderli compatibili Sintassi GoogleSQL. Per ulteriori informazioni, consulta la sezione Conversioni di Avro.

Per fornire uno schema per la creazione di tabelle esterne, imposta referenceFileSchemaUri nell'API BigQuery o il parametro
--reference_file_schema_uri nello strumento a riga di comando bq all'URL del file di riferimento.

Ad esempio, --reference_file_schema_uri="gs://mybucket/schema.avro".

Compressione Avro

BigQuery supporta i seguenti codec di compressione Contenuti del file Avro:

• Snappy
• DEFLATE

Caricare dati Avro in una nuova tabella

Per caricare dati Avro da Cloud Storage in una nuova tabella BigQuery, seleziona una delle seguenti opzioni:

Console

1. Nella console Google Cloud, apri la pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.

3. Espandi Azioni e fai clic su Apri.

4. Nel riquadro dei dettagli, fai clic su Crea tabella. .

5. Nella sezione Origine della pagina Crea tabella:

   • Per Crea tabella da, seleziona Google Cloud Storage.

   • Nel campo Origine, individua o inserisci il URI Cloud Storage. Tieni presente che non puoi includere più URI nel console Google Cloud, caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nella stessa località come set di dati contenente la tabella che stai creando.

     

   • Per Formato file, seleziona Avro.

6. Nella sezione Destinazione della pagina Crea tabella:

   • In Nome set di dati, scegli il set di dati appropriato.
   • Verifica che l'opzione Tipo di tabella sia impostata su Tabella nativa.
   • Nel campo Nome tabella, inserisci il nome della tabella che stai e la creazione in BigQuery.

7. Nella sezione Schema non è necessaria alcuna azione. Lo schema è autodescritte nei file Avro.

8. (Facoltativo) Per partizionare la tabella, scegli le opzioni nel Impostazioni di partizionamento e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate.

9. (Facoltativo) Per Filtro di partizionamento, fai clic su Richiedi partizione filtro per richiedere agli utenti di includere una clausola WHERE che specifica partizioni di memoria su cui eseguire la query. La richiesta di un filtro di partizionamento può ridurre i costi e a migliorare le prestazioni. Per ulteriori informazioni, vedi Esecuzione di query su tabelle partizionate. Questa opzione non è disponibile se è selezionata l'opzione Nessun partizionamento.

10. (Facoltativo) Per raggruppare il cluster Nella casella Ordine di clustering, inserisci un numero di campi compreso tra uno e quattro names.

11. (Facoltativo) Fai clic su Opzioni avanzate.

    • In Write preference (Preferenza di scrittura), lascia selezionata l'opzione Write if empty (Scrivi se vuoto). Questo crea una nuova tabella e carica i dati al suo interno.
    • Per Valori sconosciuti, lascia deselezionata l'opzione Ignora valori sconosciuti. Questa opzione si applica solo ai file CSV e JSON.
    • In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una Chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.

12. Fai clic su Crea tabella.

Nota: quando carichi i dati in una tabella vuota utilizzando il metodo Console Google Cloud, non puoi aggiungere etichette, descrizioni e tabelle o alla scadenza della partizione.

Dopo aver creato la tabella, puoi aggiornarne la scadenza, descrizione ed etichette, ma non puoi aggiungere una scadenza per la partizione dopo viene creata usando la console Google Cloud. Per ulteriori informazioni, vedi Gestire le tabelle.

SQL

Utilizza la LOAD DATA Istruzione DDL. L'esempio seguente carica un file Avro nella nuova tabella mytable:

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor query, inserisci la seguente istruzione:

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire le query, vedi Eseguire una query interattiva.

bq

Usa il comando bq load e specifica AVRO tramite --source_format e includi un URI Cloud Storage. Puoi includere un singolo URI, un elenco di URI separati da virgole o un URI che contengono un carattere jolly.

(Facoltativo) Fornisci il flag --location e imposta il valore su località.

Altri flag facoltativi includono:

• --time_partitioning_type: abilita il partizionamento in base al tempo in una tabella e imposta il tipo di partizione. I valori possibili sono HOUR, DAY, MONTH e YEAR. Questo flag è facoltativo quando crei partizionata in base a una colonna DATE, DATETIME o TIMESTAMP. La il tipo di partizione predefinito per il partizionamento basato sul tempo è DAY. Non puoi modificare la specifica di partizionamento su una tabella esistente.
• --time_partitioning_expiration: un numero intero che specifica (in secondi) quando occorre eliminare una partizione temporale. La scadenza valuta con la data UTC della partizione più il valore intero.
• --time_partitioning_field: la colonna DATE o TIMESTAMP utilizzata per una tabella partizionata. Se il partizionamento basato sul tempo è abilitato senza viene creata una tabella partizionata per data di importazione.
• --require_partition_filter: quando è abilitata, questa opzione richiede agli utenti per includere una clausola WHERE che specifichi le partizioni su cui eseguire la query. La richiesta di un filtro di partizionamento può ridurre i costi e migliorare le prestazioni. Per saperne di più, consulta Esecuzione di query su tabelle partizionate.
• --clustering_fields: un elenco separato da virgole di massimo quattro nomi di colonna utilizzato per creare una tabella in cluster.

• --destination_kms_key: la chiave Cloud KMS per la crittografia dei file e i dati della tabella.

  Per saperne di più sulle tabelle partizionate, consulta:

  • Creazione di tabelle partizionate

  Per ulteriori informazioni sulle tabelle in cluster, consulta:

  • Creazione e utilizzo di tabelle in cluster

  Per ulteriori informazioni sulla crittografia delle tabelle, consulta:

  • Protezione dei dati con le chiavi Cloud KMS

Per caricare dati Avro in BigQuery, inserisci il comando seguente:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

Sostituisci quanto segue:

• location è la tua posizione. Il flag --location è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag su asia-northeast1. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.
• format è pari a AVRO.
• dataset è un set di dati esistente.
• table è il nome della tabella in cui vengono caricati i dati.
• path_to_source è un URI Cloud Storage completo oppure un elenco di URI separati da virgole. Caratteri jolly sono supportate.

Esempi:

Il seguente comando carica i dati da gs://mybucket/mydata.avro in un tabella denominata mytable in mydataset.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Il seguente comando carica i dati da gs://mybucket/mydata.avro in un tabella partizionata per data di importazione denominata mytable in mydataset.

    bq load \
    --source_format=AVRO \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Il seguente comando carica i dati da gs://mybucket/mydata.avro in un nuovo tabella partizionata denominata mytable in mydataset. La tabella è partizionata nella colonna mytimestamp.

    bq load \
    --source_format=AVRO \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Il seguente comando carica dati da più file in gs://mybucket/ in una tabella denominata mytable in mydataset. L'URI Cloud Storage utilizza un carattere jolly.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

Il seguente comando carica dati da più file in gs://mybucket/ in una tabella denominata mytable in mydataset. Il comando include una virgola elenco separato di URI di Cloud Storage con caratteri jolly.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

1. Crea un job load che punti ai dati di origine in Cloud Storage.

2. (Facoltativo) Specifica la tua località in la proprietà location nella sezione jobReference della risorsa job.

3. La proprietà source URIs deve essere completamente idonea, nel formato gs://bucket/object. Ogni URI può contenere un carattere "*" carattere jolly.

4. Specifica il formato dei dati Avro impostando la proprietà sourceFormat su AVRO.

5. Per controllare lo stato del lavoro, chiama jobs.get(job_id*), dove job_id è l'ID del job restituito dal richiesta.

   • Se status.state = DONE, il job è stato completato correttamente.
   • Se è presente la proprietà status.errorResult, la richiesta non è riuscita. e l'oggetto includerà informazioni che descrivono cosa non ha funzionato. Quando una richiesta non va a buon fine, non viene creata alcuna tabella e non vengono caricati dati.
   • Se il campo status.errorResult non è presente, il job è stato completato correttamente. anche se potrebbero essersi verificati alcuni errori non irreversibili, come problemi importando alcune righe. Gli errori non irreversibili sono elencati nel job restituito dell'oggetto status.errors.

Note API:

• I job di caricamento sono atomici e coerenti, Se un job di caricamento non riesce, nessuno dei dati e, se un job di caricamento ha esito positivo, saranno disponibili tutti i dati.

• Come best practice, genera un ID univoco e passalo come jobReference.jobId durante la chiamata a jobs.insert per creare un job di caricamento. Questo è più efficace per gli errori di rete perché il client può eseguire il polling o riprova sull'ID job noto.

• Chiamare jobs.insert su un determinato ID job è idempotente. Puoi riprovare come tutte le volte che desideri per lo stesso ID job e al massimo una di queste operazioni avranno esito positivo.

Vai

Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvro() {
  // Imports a GCS file into a table with Avro source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(source_format=bigquery.SourceFormat.AVRO)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Estrarre i dati JSON dai dati Avro

Esistono due modi per garantire che i dati Avro vengano caricati BigQuery come Dati di JSON:

1. Annota lo schema Avro con sqlType impostato su JSON. Ad esempio, se caricare i dati con il seguente schema Avro, la colonna json_field verrà interpretato come un tipo JSON:

   {
       "type": {"type": "string", "sqlType": "JSON"},
       "name": "json_field"
   }
   

2. Specifica in modo esplicito lo schema della tabella di destinazione BigQuery imposta il tipo di colonna su JSON. Per ulteriori informazioni, vedi Specifica di uno schema.

Se non specifichi JSON come tipo nello schema Avro o nello schema Schema della tabella BigQuery, i dati verranno letti come STRING.

Aggiunta o sovrascrittura di una tabella con dati Avro

Puoi caricare dati aggiuntivi in una tabella dai file di origine o aggiungendo i risultati della query.

Nella console Google Cloud, utilizza l'opzione Preferenza di scrittura per specificare quale azione eseguire quando carichi i dati da un file di origine o da una query o il risultato finale.

Quando carichi dati aggiuntivi in una tabella, hai a disposizione le seguenti opzioni:

Opzione della console	flag strumento bq	Proprietà API BigQuery	Descrizione
Scrivi se vuota	Non supportata	WRITE_EMPTY	Scrive i dati solo se la tabella è vuota.
Aggiungi a tabella	--noreplace o --replace=false; if --[no]replace non è specificato. Il valore predefinito è Aggiungi	WRITE_APPEND	(valore predefinito) Aggiunge i dati alla fine della tabella.
Sovrascrivi tabella	--replace o --replace=true	WRITE_TRUNCATE	Cancella tutti i dati esistenti in una tabella prima di scrivere i nuovi dati. Questa azione elimina anche lo schema della tabella, la sicurezza a livello di riga e rimuove eventuali Chiave Cloud KMS.

Se carichi i dati in una tabella esistente, il job di caricamento può aggiungere i dati o sovrascrivere la tabella.

Nota: questa pagina non riguarda l'aggiunta o la sovrascrittura di tabelle partizionate. Per informazioni sull'aggiunta e la sovrascrittura delle tabelle partizionate, consulta: Aggiunta e sovrascrittura di tabella partizionata partizionate.

Per aggiungere o sovrascrivere una tabella con dati Avro:

Console

1. Nella console Google Cloud, apri la pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.

3. Espandi Azioni e fai clic su Apri.

4. Nel riquadro dei dettagli, fai clic su Crea tabella. .

5. Nella sezione Origine della pagina Crea tabella:

   • Per Crea tabella da, seleziona Cloud Storage.

   • Nel campo di origine, vai a o inserisci l'URI Cloud Storage. Tieni presente che non puoi Includono più URI nella console Google Cloud, ma caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nella stessa località come set di dati che contiene la tabella che stai aggiungendo o sovrascrivendo.

     

   • Per Formato file, seleziona Avro.

6. Nella sezione Destinazione della pagina Crea tabella:

   • In Nome set di dati, scegli il set di dati appropriato.

     

   • Nel campo Nome tabella, inserisci il nome della tabella che stai l'aggiunta o la sovrascrittura in BigQuery.

   • Verifica che l'opzione Tipo di tabella sia impostata su Tabella nativa.

7. Nella sezione Schema non è necessaria alcuna azione. Lo schema è autodescritte nei file Avro.

   Nota: è possibile modificare lo schema della tabella quando aggiungi o sovrascriverla. Per ulteriori informazioni sulle modifiche allo schema supportate durante dell'operazione di caricamento, vedi Modifica degli schemi delle tabelle.

8. In Impostazioni di partizionamento e clustering, lascia i valori predefiniti. Tu impossibile convertire una tabella in una tabella partizionata o in cluster aggiungendo o sovrascriverlo e la console Google Cloud non supporta aggiungendo o sovrascrivendo tabelle partizionate o in cluster in un job di caricamento.

9. Fai clic su Opzioni avanzate.

   • In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi dalla tabella.
   • Per Valori sconosciuti, lascia deselezionata l'opzione Ignora valori sconosciuti. Questa opzione si applica solo ai file CSV e JSON.
   • In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una Chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.

10. Fai clic su Crea tabella.

SQL

Utilizza la LOAD DATA Istruzione DDL. L'esempio seguente aggiunge un file Avro alla tabella mytable:

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor query, inserisci la seguente istruzione:

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'avro',
     uris = ['gs://bucket/path/file.avro']);
   

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire le query, vedi Eseguire una query interattiva.

bq

Inserisci il comando bq load con il flag --replace per sovrascrivere . Utilizza il flag --noreplace per aggiungere dati alla tabella. Se non è presente alcun flag specificato, il valore predefinito è l'aggiunta di dati. Fornisci il flag --source_format e lo imposti su AVRO. Poiché gli schemi Avro vengono recuperati automaticamente dai dati di origine autodescrittivi, non è necessario fornire uno schema definizione di Kubernetes.

Nota: è possibile modificare lo schema della tabella quando aggiungi o sovrascriverla. Per ulteriori informazioni sulle modifiche allo schema supportate durante dell'operazione di caricamento, vedi Modifica degli schemi delle tabelle.

(Facoltativo) Fornisci il flag --location e imposta il valore su località.

Altri flag facoltativi includono:

• --destination_kms_key: la chiave Cloud KMS per la crittografia dei file e i dati della tabella.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Sostituisci quanto segue:

• location è la tua località. Il flag --location è facoltativo. Puoi impostare un valore predefinito per usando il file.bigqueryrc.
• format è pari a AVRO.
• dataset è un set di dati esistente.
• table è il nome della tabella in cui vengono caricati i dati.
• path_to_source è un URI Cloud Storage completo oppure un elenco di URI separati da virgole. Caratteri jolly sono supportate.

Esempi:

Il comando seguente carica i dati da gs://mybucket/mydata.avro e sovrascrive una tabella denominata mytable in mydataset.

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Il comando seguente carica i dati da gs://mybucket/mydata.avro e accoda dati a una tabella denominata mytable in mydataset.

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Per informazioni sull'aggiunta e la sovrascrittura delle tabelle partizionate mediante a riga di comando bq, consulta: Aggiunta e sovrascrittura di tabella partizionata partizionate.

API

1. Crea un job load che punti ai dati di origine in Cloud Storage.

2. (Facoltativo) Specifica la tua località in la proprietà location nella sezione jobReference della risorsa job.

3. La proprietà source URIs devono essere pienamente qualificati, nel formato gs://bucket/object. Puoi Includere più URI sotto forma di elenco separato da virgole. Tieni presente che caratteri jolly sono .

4. Specifica il formato dei dati impostando il parametro configuration.load.sourceFormat a AVRO.

5. Specifica la preferenza di scrittura impostando il parametro configuration.load.writeDisposition proprietà a WRITE_TRUNCATE o WRITE_APPEND.

Vai

Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.AVRO,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Caricamento dei dati Avro partizionati in hive

BigQuery supporta il caricamento di dati Avro partizionati hive archiviati su Cloud Storage e compila le colonne di partizionamento hive come colonne in nella tabella gestita da BigQuery di destinazione. Per ulteriori informazioni, vedi Caricamento di dati partizionati esternamente da Cloud Storage.

Conversioni Avro

BigQuery converte i tipi di dati Avro nel seguente Tipi di dati BigQuery:

Tipi primitivi

Tipo di dati Avro senza attributo logicalType	Tipo di dati BigQuery	Note
null	BigQuery ignora questi valori
boolean	BOOLEANO
int	INTEGER
Lungo	INTEGER
numero in virgola mobile	FLOAT
double	FLOAT
byte	BYTES
string	STRINGA	Solo UTF-8

Tipi logici

Per impostazione predefinita, BigQuery ignora l'attributo logicalType per la maggior parte dei tipi e utilizza invece il tipo Avro sottostante. Per convertire tipi logici Avro ai tipi di dati BigQuery corrispondenti, imposta il flag --use_avro_logical_types su true utilizzando lo strumento a riga di comando bq oppure imposta la proprietà useAvroLogicalTypes nella risorse di lavoro quando chiami jobs.insert per creare un job di caricamento.

La tabella seguente mostra la conversione dei tipi logici Avro in Tipi di dati di BigQuery.

Tipo logico Avro	Tipo di dati BigQuery: tipo logico disabilitato	Tipo di dati BigQuery: tipo logico abilitato
data	INTEGER	DATA
tempo-millisecondi	INTEGER	TEMPO
time-micros	INTEGER (convertito da LONG)	TEMPO
timestamp-millisecondi	INTEGER (convertito da LONG)	TIMESTAMP
timestamp-micros	INTEGER (convertito da LONG)	TIMESTAMP
local-timestamp-millis	INTEGER (convertito da LONG)	DATETIME
local-timestamp-micros	INTEGER (convertito da LONG)	DATETIME
duration	BYTES (convertiti da fixed tipo di dimensione 12)	BYTES (convertiti da fixed tipo di dimensione 12)
decimal	NUMERIC, BIGNUMERIC o STRING (vedi Tipo logico decimale)	NUMERIC, BIGNUMERIC o STRING (vedi Tipo logico decimale)

Per ulteriori informazioni sui tipi di dati Avro, consulta Specifica Apache AvroTM 1.8.2.

Nota: quando esegui l'esportazione in Avro da BigQuery, DATETIME esportato come STRING con un orario logico personalizzato che non viene riconosciuto come DATETIME al momento dell'importazione di nuovo in BigQuery.

Tipo logico delle date

In qualsiasi file Avro che intendi caricare, devi specificare i tipi logici delle date nel seguente formato:

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

Tipo logico decimale

Decimal tipi logici possono essere convertiti in NUMERIC, BIGNUMERIC o STRING tipi. Il tipo convertito dipende sui parametri di precisione e scala del tipo logico decimal e tipi di target decimali specificati. Specifica il tipo di target decimale come segue:

• Per un job di caricamento utilizzando la proprietà API jobs.insert: utilizza JobConfigurationLoad.decimalTargetTypes .
• Per un job di caricamento utilizzando la proprietà bq load nello strumento a riga di comando bq: usa --decimal_target_types flag.
• Per una query su una tabella con origini esterne: usa ExternalDataConfiguration.decimalTargetTypes .
• Per una tabella esterna permanente creata con DDL: utilizza l'opzione decimal_target_types.

Per la compatibilità con le versioni precedenti, se i tipi di targeting decimale non sono specificati, carica un file Avro contenente una colonna bytes con il tipo logico decimal in una colonna BYTES di una tabella esistente. In questo il tipo logico decimal nella colonna del file Avro viene ignorato. Questo la modalità di conversione è deprecata e potrebbe essere rimossa in futuro.

Per ulteriori informazioni sul tipo logico Avro decimal, consulta Specifica Apache AvroTM 1.8.2.

Tipo logico temporale

In qualsiasi file Avro che intendi caricare, devi specificare tipi logici orali in una dei seguenti formati.

Per una precisione in millisecondi:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Per una precisione in microsecondi:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Tipo logico timestamp

In qualsiasi file Avro che intendi caricare, devi specificare tipi logici del timestamp in uno dei seguenti formati.

Per una precisione in millisecondi:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Per una precisione in microsecondi:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Tipo logico di timestamp locale

In qualsiasi file Avro che intendi caricare, devi specificare un valore logico local-timestamp devono essere digitati in uno dei seguenti formati.

Per una precisione in millisecondi:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Per una precisione in microsecondi:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

Tipi complessi

Tipo di dati Avro	Tipo di dati BigQuery	Note
disco	RECORD	Gli alias vengono ignorati Il documento viene convertito in una descrizione del campo. I valori predefiniti sono impostati al momento della lettura L'ordine viene ignorato Vengono eliminati i campi ricorsivi. Solo il primo livello la nidificazione è mantenuta per i campi ricorsivi
enum	STRINGA	La stringa è il valore simbolico dell'enumerazione Gli alias vengono ignorati Il documento viene convertito in una descrizione del campo.
matrice	campi ripetuti	Gli array di array non sono supportati. Array contenenti solo tipi NULL vengono ignorati.
mappa<T>	RECORD	BigQuery converte una mappa Avro<T> in un campo RECORD che contiene due campi: una chiave e un valore. BigQuery archivia la chiave come STRING e converte il valore nel suo del tipo di dati in BigQuery.
unione	Campo nullo RECORD con un elenco di campi assegnabili	Quando l'unione ha un solo tipo non null, viene convertita in un valore nullo . In caso contrario, viene convertito in un RECORD con un elenco di campi null. Solo uno di questi campi verrà impostato al momento della lettura.
fisso	BYTES	Gli alias vengono ignorati La dimensione viene ignorata

Limitazioni

• La formattazione degli array nidificati non è supportata in BigQuery. Avro i file in questo formato devono essere convertiti prima dell'importazione.
• In un file Avro, i nomi e gli spazi dei nomi di un nome completo possono contenere solo caratteri alfanumerici e il trattino basso _. La seguente espressione regolare mostra i caratteri consentiti: [A-Za-z_][A-Za-z0-9_]*

Per ulteriori informazioni, vedi Limiti dei job di caricamento BigQuery.