Caricamento dei dati CSV da Cloud Storage

Quando carichi dati CSV da Cloud Storage, puoi caricarli in una nuova tabella o partizione oppure puoi aggiungerli a una tabella o partizione esistente o sovrascriverli. Quando i dati vengono caricati in BigQuery, vengono convertiti in formato a colonne per Capacitor (il 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 località regionale o multiregionale del bucket Cloud Storage.

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

Provalo

Se non conosci Google Cloud, crea un account per valutare le prestazioni di BigQuery in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti senza addebiti per l'esecuzione, il test e il deployment dei workload.

Prova BigQuery gratuitamente

Limitazioni

Quando carichi i dati in BigQuery da un bucket Cloud Storage, sono previste le seguenti limitazioni:

• BigQuery non garantisce la coerenza dei dati per le origini dati esterne. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono comportare un comportamento imprevisto.
• BigQuery non supporta il controllo delle versioni degli oggetti Cloud Storage. Se includi un numero di generazione nell'URI Cloud Storage, il job di caricamento non va a buon fine.

Quando carichi file CSV in BigQuery, tieni presente quanto segue:

• I file CSV non supportano dati nidificati o ripetuti.
• Rimuovi i caratteri del byte order mark (BOM). Potrebbero causare problemi imprevisti.
• Se utilizzi la compressione gzip, BigQuery non può leggere i dati in parallelo. Il caricamento di dati CSV compressi in BigQuery è più lento rispetto al caricamento di dati non compressi. Vedi Caricamento di dati compressi e non compressi.
• Non puoi includere file compressi e non compressi nello stesso job di caricamento.
• La dimensione massima per un file gzip è 4 GB.
• Il caricamento dei dati CSV utilizzando il rilevamento automatico dello schema non rileva automaticamente le intestazioni se tutte le colonne sono di tipo stringa. In questo caso, aggiungi una colonna numerica all'input o dichiara lo schema in modo esplicito.
• Quando carichi dati CSV o JSON, i valori nelle colonne DATE devono utilizzare il separatore trattino (-) e la data deve essere nel seguente formato: YYYY-MM-DD (anno-mese-giorno).
• Quando carichi dati JSON o CSV, i valori nelle colonne TIMESTAMP devono utilizzare un trattino (-) o una barra (/) come separatore per la parte della data del timestamp e la data deve essere in uno dei seguenti formati: YYYY-MM-DD (anno-mese-giorno) o YYYY/MM/DD (anno/mese/giorno). La parte hh:mm:ss (ora-minuto-secondo) del timestamp deve utilizzare i due punti (:) come separatore.
• I file devono rispettare i limiti di dimensione dei file CSV descritti nei limiti dei job di caricamento.

Prima di iniziare

Concedi ruoli Identity and Access Management (IAM) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività descritta in questo documento e crea un set di dati per archiviare i tuoi dati.

Autorizzazioni obbligatorie

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

Autorizzazioni per caricare dati in BigQuery

Per caricare i dati in una nuova tabella o partizione BigQuery oppure per aggiungere o sovrascrivere una tabella o 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 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 tabelle utilizzando un job di caricamento nei set di dati che crei.

Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni 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 il ruolo IAM Amministratore archiviazione (roles/storage.admin) nel bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per vedere quali sono esattamente le autorizzazioni richieste, 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 ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Crea un set di dati

Crea un set di dati BigQuery per archiviare i tuoi dati.

Compressione CSV

Puoi utilizzare l'utilità gzip per comprimere i file CSV. Tieni presente che gzip esegue la compressione completa dei file, a differenza della compressione dei contenuti dei file eseguita dai codec di compressione per altri formati di file, come Avro. L'utilizzo di gzip per comprimere i file CSV potrebbe influire sulle prestazioni. Per ulteriori informazioni sui compromessi, consulta Caricamento di dati compressi e non compressi.

Caricamento di dati CSV in una tabella

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

Console

---

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

---

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
3. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
4. Nel riquadro Crea tabella, specifica i seguenti dettagli:
1. Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da. Poi, procedi nel seguente modo:
   1. Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage. Non puoi includere più URI nella Google Cloud console, ma i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nella stessa posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o sovrascrivere.
   2. Per Formato file, seleziona CSV.
2. Nella sezione Destinazione, specifica i seguenti dettagli:
   1. Per Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
   2. Nel campo Table (Tabella), inserisci il nome della tabella che vuoi creare.
   3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
3. Nella sezione Schema, inserisci la definizione dello schema. Per attivare il rilevamento automatico di uno schema, seleziona Rilevamento automatico. Puoi inserire manualmente le informazioni sullo schema utilizzando uno dei seguenti metodi:
   • Opzione 1: fai clic su Modifica come testo e incolla lo schema sotto forma di array JSON. Quando utilizzi un array JSON, generi lo schema utilizzando lo stesso processo di creazione di un file di schema JSON. Per visualizzare lo schema di una tabella esistente in formato JSON, inserisci il seguente comando:

         bq show --format=prettyjson dataset.table
         

   • Opzione 2: fai clic su Aggiungi campo e inserisci lo schema della tabella. Specifica il nome, il tipo e la modalità di ogni campo.
4. (Facoltativo) Specifica le impostazioni di partizionamento e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
5. Fai clic su Opzioni avanzate e segui questi passaggi:
   • In Preferenza di scrittura, lascia selezionata l'opzione Scrivi se vuota. Questa opzione crea una nuova tabella e carica i dati al suo interno.
   • Per Numero di errori consentiti, accetta il valore predefinito di 0 o inserisci il numero massimo di righe contenenti errori che possono essere ignorate. Se il numero di righe con errori supera questo valore, il job restituirà un messaggio invalid e avrà esito negativo. Questa opzione si applica solo ai file CSV e JSON.
   • Per Fuso orario, inserisci il fuso orario predefinito che verrà applicato durante l'analisi dei valori timestamp che non hanno un fuso orario specifico. Controlla qui per altri nomi di fusi orari validi. Se questo valore non è presente, i valori timestamp senza un fuso orario specifico vengono analizzati utilizzando il fuso orario UTC predefinito. (Anteprima).
   • Per Formato data, inserisci gli elementi di formato che definiscono come vengono formattati i valori DATE nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY). Se questo valore è presente, questo formato è l'unico formato DATE compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna DATE in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATE viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato datetime, inserisci gli elementi di formato che definiscono come vengono formattati i valori DATETIME nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato DATETIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna DATETIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATETIME viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato ora, inserisci gli elementi di formato che definiscono come vengono formattati i valori TIME nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato TIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIME viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato timestamp, inserisci gli elementi di formato che definiscono come vengono formattati i valori TIMESTAMP nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico TIMESTAMP compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIMESTAMP in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIMESTAMP viene analizzato con i formati predefiniti. (Anteprima).
   • Se vuoi ignorare i valori di una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
   • Per Delimitatore di campo, scegli il carattere che separa le celle nel file CSV: Virgola, Tabulazione, Pipe o Personalizzato. Se scegli Personalizzato, inserisci il delimitatore nella casella Delimitatore di campo personalizzato. Il valore predefinito è Virgola.
   • Per Righe di intestazione da saltare, inserisci il numero di righe di intestazione da saltare nella parte superiore del file CSV. Il valore predefinito è 0.
   • Per Caratteri di fine riga con virgolette, seleziona Consenti caratteri di fine riga con virgolette per consentire le sezioni di dati tra virgolette che contengono caratteri di fine riga in un file CSV. Il valore predefinito è false.
   • Per Righe incomplete, seleziona Consenti righe incomplete per accettare le righe nei file CSV in cui mancano le colonne facoltative finali. I valori mancanti vengono considerati null. Se la casella non è selezionata, i record con colonne finali mancanti vengono trattati come record non validi e, se sono troppi, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false.
   • Per la crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Google-managed key, BigQuery cripta i dati at rest.
6. Fai clic su Crea tabella.

Nota :quando carichi dati in una tabella vuota utilizzando la consoleGoogle Cloud , non puoi aggiungere un'etichetta, una descrizione, una scadenza della tabella o una scadenza della partizione.

Dopo la creazione della tabella, puoi aggiornarne la scadenza, la descrizione e le etichette, ma non puoi aggiungere una scadenza della partizione dopo la creazione di una tabella utilizzando la console Google Cloud . Per saperne di più, consulta Gestire le tabelle.

SQL

Utilizza l'istruzione DDL LOAD DATA. Il seguente esempio carica un file CSV nella nuova tabella mytable:

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

   Vai a BigQuery

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

   LOAD DATA OVERWRITE mydataset.mytable
   (x INT64,y STRING)
   FROM FILES (
     format = 'CSV',
     uris = ['gs://bucket/path/file.csv']);

3. Fai clic su Esegui.

Per maggiori informazioni su come eseguire le query, consulta Eseguire una query interattiva.

bq

Utilizza il comando bq load, specifica CSV utilizzando il flag --source_format e includi un URI Cloud Storage. Puoi includere un singolo URI, un elenco di URI separati da virgole o un URI contenente un carattere jolly. Fornisci lo schema inline, in un file di definizione dello schema o utilizza il rilevamento automatico dello schema. Se non specifichi uno schema e --autodetect è false e la tabella di destinazione esiste, viene utilizzato lo schema della tabella di destinazione.

(Facoltativo) Fornisci il flag --location e imposta il valore sulla tua posizione.

Altri flag facoltativi includono:

• --allow_jagged_rows: se specificato, accetta le righe nei file CSV a cui mancano le colonne facoltative finali. I valori mancanti vengono trattati come valori null. Se la casella non è selezionata, i record con colonne finali mancanti vengono trattati come record non validi e, se sono presenti troppi record non validi, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false.
• --allow_quoted_newlines: se specificato, consente sezioni di dati tra virgolette che contengono caratteri di nuova riga in un file CSV. Il valore predefinito è false.
• --field_delimiter: il carattere che indica il limite tra le colonne nei dati. Sono consentiti sia \t che tab per i delimitatori di tabulazione. Il valore predefinito è ,.
• --null_marker: una stringa personalizzata facoltativa che rappresenta un valore NULL nei dati CSV.
• --skip_leading_rows: specifica il numero di righe di intestazione da saltare all'inizio del file CSV. Il valore predefinito è 0.
• --quote: Il carattere di virgolette da utilizzare per racchiudere i record. Il valore predefinito è ". Per indicare che non è presente alcun carattere di citazione, utilizza una stringa vuota.
• --max_bad_records: un numero intero che specifica il numero massimo di record non validi consentiti prima che l'intero job non vada a buon fine. Il valore predefinito è 0. Vengono restituiti al massimo cinque errori di qualsiasi tipo, indipendentemente dal valore di --max_bad_records.
• --ignore_unknown_values: se specificato, consente e ignora valori extra e non riconosciuti nei dati CSV o JSON.
• --time_zone: (Anteprima) Un fuso orario predefinito facoltativo che verrà applicato durante l'analisi dei valori timestamp che non hanno un fuso orario specifico nei dati CSV o JSON.
• --date_format: (Anteprima) Una stringa personalizzata facoltativa che definisce come vengono formattati i valori DATE nei dati CSV o JSON.
• --datetime_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori DATETIME nei dati CSV o JSON.
• --time_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori TIME nei dati CSV o JSON.
• --timestamp_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori TIMESTAMP nei dati CSV o JSON.
• --autodetect: se specificato, attiva il rilevamento automatico dello schema per i dati CSV e JSON.
• --time_partitioning_type: attiva il partizionamento basato sul tempo in una tabella e imposta il tipo di partizione. I valori possibili sono HOUR, DAY, MONTH e YEAR. Questo flag è facoltativo quando crei una tabella partizionata in base a una colonna DATE, DATETIME o TIMESTAMP. Il tipo di partizione predefinito per il partizionamento basato sul tempo è DAY. Non puoi modificare la specifica di partizionamento di una tabella esistente.
• --time_partitioning_expiration: un numero intero che specifica (in secondi) quando deve essere eliminata una partizione basata sul tempo. Il tempo di scadenza corrisponde alla data UTC della partizione più il valore intero.
• --time_partitioning_field: la colonna DATE o TIMESTAMP utilizzata per creare una tabella partizionata. Se il partizionamento basato sul tempo è abilitato senza questo valore, viene creata una tabella partizionata per data di importazione.
• --require_partition_filter: se attivata, questa opzione richiede agli utenti di includere una clausola WHERE che specifica le partizioni da interrogare. Se il filtro di partizionamento è obbligatorio, i costi potrebbero ridursi e le prestazioni potrebbero migliorare. Per maggiori informazioni, consulta la pagina Esecuzione di query sulle tabelle partizionate.
• --clustering_fields: un elenco separato da virgole di massimo quattro nomi di colonne utilizzati per creare una tabella in cluster.
• --destination_kms_key: la chiave Cloud KMS per la crittografia dei dati della tabella.

• --column_name_character_map: definisce l'ambito e la gestione dei caratteri nei nomi delle colonne, con la possibilità di attivare nomi delle colonne flessibili. Richiede l'opzione --autodetect per i file CSV. Per ulteriori informazioni, vedi load_option_list.

  Per ulteriori informazioni sul comando bq load, vedi:

  • Riferimento alla riga di comando

  Per ulteriori informazioni sulle tabelle partizionate, consulta:

  • Creazione di tabelle partizionate

  Per saperne di più sulle tabelle in cluster, consulta:

  • Creazione e utilizzo delle tabelle in cluster

  Per ulteriori informazioni sulla crittografia delle tabelle, vedi:

  • Protezione dei dati con le chiavi Cloud KMS

Per caricare i dati CSV in BigQuery, inserisci il seguente comando:

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

Dove:

• 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 CSV.
• dataset è un set di dati esistente.
• table è il nome della tabella in cui stai caricando i dati.
• path_to_source è un URI Cloud Storage completo o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.
• schema è uno schema valido. Lo schema può essere un file JSON locale oppure può essere digitato inline come parte del comando. Puoi anche utilizzare il flag --autodetect anziché fornire una definizione dello schema.

Esempi:

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una tabella denominata mytable in mydataset. Lo schema è definito in un file di schema locale denominato myschema.json.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una tabella denominata mytable in mydataset. Lo schema è definito in un file di schema locale denominato myschema.json. Il file CSV include due righe di intestazione. Se --skip_leading_rows non è specificato, il comportamento predefinito è presupporre che il file non contenga intestazioni.

    bq load \
    --source_format=CSV \
    --skip_leading_rows=2
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una tabella partizionata per data di importazione'ora di importazione denominata mytable in mydataset. Lo schema è definito in un file schema locale denominato myschema.json.

    bq load \
    --source_format=CSV \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una nuova tabella partizionata denominata mytable in mydataset. La tabella è partizionata in base alla colonna mytimestamp. Lo schema è definito in un file di schema locale denominato myschema.json.

    bq load \
    --source_format=CSV \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una tabella denominata mytable in mydataset. Lo schema viene rilevato automaticamente.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

Il seguente comando carica i dati da gs://mybucket/mydata.csv in una tabella denominata mytable in mydataset. Lo schema è definito inline nel formato field:data_type,field:data_type.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

Nota: quando specifichi lo schema utilizzando lo strumento a riga di comando bq, non puoi includere un tipo RECORD (STRUCT), non puoi includere una descrizione del campo e non puoi specificare la modalità del campo. Tutte le modalità dei campi sono impostate su NULLABLE per impostazione predefinita. Per includere descrizioni, modalità e tipi RECORD, fornisci un file di schema JSON invece.

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

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata*.csv

Il seguente comando carica i dati da più file in gs://mybucket/ in una tabella denominata mytable in mydataset. Il comando include un elenco separato da virgole di URI di Cloud Storage con caratteri jolly. Lo schema è definito in un file di schema locale denominato myschema.json.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    "gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
    ./myschema.json

API

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

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

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

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

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

   • 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 è andato storto. Quando una richiesta non va a buon fine, non viene creata alcuna tabella e non vengono caricati dati.
   • Se status.errorResult è assente, il job è stato completato correttamente, anche se potrebbero essersi verificati alcuni errori non fatali, ad esempio problemi con l'importazione di alcune righe. Gli errori non irreversibili sono elencati nella proprietà status.errors dell'oggetto job restituito.

Note sull'API:

• I job di caricamento sono atomici e coerenti: se un job di caricamento non va a buon fine, nessuno dei dati è disponibile e se un job di caricamento va a buon fine, tutti i dati sono disponibili.

• Come best practice, genera un ID univoco e trasmettilo come jobReference.jobId quando chiami jobs.insert per creare un job di caricamento. Questo approccio è più resistente agli errori di rete perché il client può eseguire il polling o riprovare con l'ID job noto.

• La chiamata di jobs.insert su un determinato ID job è idempotente. Puoi riprovare tutte le volte che vuoi con lo stesso ID job e al massimo una di queste operazioni andrà a buon fine.

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery C#.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

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

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(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.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	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 di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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.CsvOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadCsvFromGcs() throws Exception {
    // 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.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadCsvFromGcs(datasetName, tableName, sourceUri, schema);
  }

  public static void loadCsvFromGcs(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV 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("CSV from GCS successfully added during load append job");
      } 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 di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // 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), metadata);

  // 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;
  }
}

PHP

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

Utilizza il metodo Client.load_table_from_uri() per caricare i dati da un file CSV in Cloud Storage. Fornisci una definizione dello schema esplicita impostando la proprietà LoadJobConfig.schema su un elenco di oggetti SchemaField.

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"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

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)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Ruby.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

require "google/cloud/bigquery"

def load_table_gcs_csv dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Caricamento di dati CSV in una tabella che utilizza il partizionamento temporale basato su colonne

Per caricare i dati CSV da Cloud Storage in una tabella BigQuery che utilizza il partizionamento basato su colonne:

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

import (
	"context"
	"fmt"
	"time"

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

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID 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-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	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 di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // 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), metadata);

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

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

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

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

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

Aggiungere o sovrascrivere una tabella con dati CSV

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

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

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

Opzione della console	Flag dello 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; se --[no]replace non è specificato, il valore predefinito è append	WRITE_APPEND	(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 qualsiasi 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 tratta l'aggiunta o la sovrascrittura di tabelle partizionate. Per informazioni sull'aggiunta e sulla sovrascrittura di tabelle partizionate, consulta: Aggiunta e sovrascrittura dei dati delltabella partizionatale partizionate.

Console

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
3. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
4. Nel riquadro Crea tabella, specifica i seguenti dettagli:
1. Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da. Poi, procedi nel seguente modo:
   1. Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage. Non puoi includere più URI nella Google Cloud console, ma i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nella stessa posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o sovrascrivere.
   2. Per Formato file, seleziona CSV.
Nota:è possibile modificare lo schema della tabella quando lo aggiungi o lo sovrascrivi. Per ulteriori informazioni sulle modifiche dello schema supportate durante un'operazione di caricamento, consulta Modifica degli schemi delle tabelle.
2. Nella sezione Destinazione, specifica i seguenti dettagli:
   1. Per Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
   2. Nel campo Table (Tabella), inserisci il nome della tabella che vuoi creare.
   3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
3. Nella sezione Schema, inserisci la definizione dello schema. Per attivare il rilevamento automatico di uno schema, seleziona Rilevamento automatico. Puoi inserire manualmente le informazioni sullo schema utilizzando uno dei seguenti metodi:
   • Opzione 1: fai clic su Modifica come testo e incolla lo schema sotto forma di array JSON. Quando utilizzi un array JSON, generi lo schema utilizzando lo stesso processo di creazione di un file di schema JSON. Per visualizzare lo schema di una tabella esistente in formato JSON, inserisci il seguente comando:

         bq show --format=prettyjson dataset.table
         

   • Opzione 2: fai clic su Aggiungi campo e inserisci lo schema della tabella. Specifica il nome, il tipo e la modalità di ogni campo.
   Nota:è possibile modificare lo schema della tabella quando la aggiungi o la sovrascrivi. Per ulteriori informazioni sulle modifiche dello schema supportate durante un'operazione di caricamento, consulta Modifica degli schemi delle tabelle.
4. (Facoltativo) Specifica le impostazioni di partizionamento e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster. Non puoi convertire una tabella in una tabella partizionata o in cluster aggiungendola o sovrascrivendola. La console Google Cloud non supporta l'aggiunta o la sovrascrittura di tabelle partizionate o in cluster in un job di caricamento.
5. Fai clic su Opzioni avanzate e segui questi passaggi:
   • In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi tabella.
   • Per Numero di errori consentiti, accetta il valore predefinito di 0 o inserisci il numero massimo di righe contenenti errori che possono essere ignorate. Se il numero di righe con errori supera questo valore, il job restituirà un messaggio invalid e avrà esito negativo. Questa opzione si applica solo ai file CSV e JSON.
   • Per Fuso orario, inserisci il fuso orario predefinito che verrà applicato durante l'analisi dei valori timestamp che non hanno un fuso orario specifico. Controlla qui per altri nomi di fusi orari validi. Se questo valore non è presente, i valori timestamp senza un fuso orario specifico vengono analizzati utilizzando il fuso orario UTC predefinito. (Anteprima).
   • Per Formato data, inserisci gli elementi di formato che definiscono come vengono formattati i valori DATE nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY). Se questo valore è presente, questo formato è l'unico formato DATE compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna DATE in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATE viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato datetime, inserisci gli elementi di formato che definiscono come vengono formattati i valori DATETIME nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato DATETIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna DATETIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATETIME viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato ora, inserisci gli elementi di formato che definiscono come vengono formattati i valori TIME nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato TIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIME viene analizzato con i formati predefiniti. (Anteprima).
   • Per Formato timestamp, inserisci gli elementi di formato che definiscono come vengono formattati i valori TIMESTAMP nei file di input. Questo campo prevede il formato degli stili SQL (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico TIMESTAMP compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIMESTAMP in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIMESTAMP viene analizzato con i formati predefiniti. (Anteprima).
   • Se vuoi ignorare i valori di una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
   • Per Delimitatore di campo, scegli il carattere che separa le celle nel file CSV: Virgola, Tabulazione, Pipe o Personalizzato. Se scegli Personalizzato, inserisci il delimitatore nella casella Delimitatore di campo personalizzato. Il valore predefinito è Virgola.
   • Per Righe di intestazione da saltare, inserisci il numero di righe di intestazione da saltare nella parte superiore del file CSV. Il valore predefinito è 0.
   • Per Caratteri di fine riga con virgolette, seleziona Consenti caratteri di fine riga con virgolette per consentire le sezioni di dati tra virgolette che contengono caratteri di fine riga in un file CSV. Il valore predefinito è false.
   • Per Righe incomplete, seleziona Consenti righe incomplete per accettare le righe nei file CSV in cui mancano le colonne facoltative finali. I valori mancanti vengono considerati null. Se la casella non è selezionata, i record con colonne finali mancanti vengono trattati come record non validi e, se sono troppi, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false.
   • Per la crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Google-managed key, BigQuery cripta i dati at rest.
6. Fai clic su Crea tabella.

SQL

Utilizza l'istruzione DDL LOAD DATA. Il seguente esempio aggiunge un file CSV alla tabella mytable:

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

   Vai a BigQuery

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

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

3. Fai clic su Esegui.

Per maggiori informazioni su come eseguire le query, consulta Eseguire una query interattiva.

bq

Utilizza il comando bq load, specifica CSV utilizzando il flag --source_format e includi un URI Cloud Storage. Puoi includere un singolo URI, un elenco di URI separati da virgole o un URI contenente un carattere jolly.

Fornisci lo schema inline, in un file di definizione dello schema o utilizza il rilevamento automatico dello schema. Se non specifichi uno schema e --autodetect è false e la tabella di destinazione esiste, viene utilizzato lo schema della tabella di destinazione.

Specifica il flag --replace per sovrascrivere la tabella. Utilizza il flag --noreplace per aggiungere dati alla tabella. Se non viene specificato alcun flag, il comportamento predefinito è l'aggiunta dei dati.

È possibile modificare lo schema della tabella quando la accodi o la sovrascrivi. Per ulteriori informazioni sulle modifiche allo schema supportate durante un'operazione di caricamento, consulta Modifica degli schemi delle tabelle.

(Facoltativo) Fornisci il flag --location e imposta il valore sulla tua posizione.

Altri flag facoltativi includono:

• --allow_jagged_rows: se specificato, accetta le righe nei file CSV a cui mancano le colonne facoltative finali. I valori mancanti vengono trattati come valori null. Se la casella non è selezionata, i record con colonne finali mancanti vengono trattati come record non validi e, se sono presenti troppi record non validi, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false.
• --allow_quoted_newlines: se specificato, consente sezioni di dati tra virgolette che contengono caratteri di nuova riga in un file CSV. Il valore predefinito è false.
• --field_delimiter: il carattere che indica il limite tra le colonne nei dati. Sono consentiti sia \t che tab per i delimitatori di tabulazione. Il valore predefinito è ,.
• --null_marker: una stringa personalizzata facoltativa che rappresenta un valore NULL nei dati CSV.
• --skip_leading_rows: specifica il numero di righe di intestazione da saltare all'inizio del file CSV. Il valore predefinito è 0.
• --quote: Il carattere di virgolette da utilizzare per racchiudere i record. Il valore predefinito è ". Per indicare che non è presente alcun carattere di citazione, utilizza una stringa vuota.
• --max_bad_records: un numero intero che specifica il numero massimo di record non validi consentiti prima che l'intero job non vada a buon fine. Il valore predefinito è 0. Vengono restituiti al massimo cinque errori di qualsiasi tipo, indipendentemente dal valore di --max_bad_records.
• --ignore_unknown_values: se specificato, consente e ignora valori extra e non riconosciuti nei dati CSV o JSON.
• --time_zone: (Anteprima) Un fuso orario predefinito facoltativo che verrà applicato durante l'analisi dei valori timestamp che non hanno un fuso orario specifico nei dati CSV o JSON.
• --date_format: (Anteprima) Una stringa personalizzata facoltativa che definisce come vengono formattati i valori DATE nei dati CSV o JSON.
• --datetime_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori DATETIME nei dati CSV o JSON.
• --time_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori TIME nei dati CSV o JSON.
• --timestamp_format: (Anteprima) Una stringa personalizzata facoltativa che definisce il formato dei valori TIMESTAMP nei dati CSV o JSON.
• --autodetect: se specificato, attiva il rilevamento automatico dello schema per i dati CSV e JSON.
• --destination_kms_key: la chiave Cloud KMS per la crittografia dei dati della tabella.

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

dove:

• location è la tua posizione. Il flag --location è facoltativo. Puoi impostare un valore predefinito per la posizione utilizzando il file.bigqueryrc.
• format è pari a CSV.
• dataset è un set di dati esistente.
• table è il nome della tabella in cui stai caricando i dati.
• path_to_source è un URI Cloud Storage completo o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.
• schema è uno schema valido. Lo schema può essere un file JSON locale oppure può essere digitato inline come parte del comando. Puoi anche utilizzare il flag --autodetect anziché fornire una definizione dello schema.

Esempi:

Il seguente comando carica i dati da gs://mybucket/mydata.csv e sovrascrive una tabella denominata mytable in mydataset. Lo schema è definito utilizzando il rilevamento automatico dello schema.

    bq load \
    --autodetect \
    --replace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

Il seguente comando carica i dati da gs://mybucket/mydata.csv e aggiunge i dati a una tabella denominata mytable in mydataset. Lo schema è definito utilizzando un file di schema JSON: myschema.json.

    bq load \
    --noreplace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

API

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

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

3. La proprietà source URIs deve essere completa, nel formato gs://bucket/object. Puoi includere più URI come elenco separato da virgole. Tieni presente che sono supportati anche i caratteri jolly.

4. Specifica il formato dei dati impostando la proprietà configuration.load.sourceFormat su CSV.

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

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

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

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(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.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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 di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare 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.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // 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.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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 configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job loadJob = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } 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 di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

Per sostituire le righe in una tabella esistente, imposta il valore writeDisposition nel parametro metadata su 'WRITE_TRUNCATE'.

// 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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCSTruncate() {
  /**
   * 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 = 'my_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // 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), metadata);
  // 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;
  }
}

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

Per sostituire le righe in una tabella esistente, imposta la proprietà LoadJobConfig.write_disposition sulla costante SourceFormat WRITE_TRUNCATE.

import six

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 = six.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.CSV,
    skip_leading_rows=1,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
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 di dati CSV partizionati in Hive

BigQuery supporta il caricamento dei dati CSV partizionati Hive archiviati in Cloud Storage e popolerà le colonne di partizionamento Hive come colonne nella tabella gestita BigQuery di destinazione. Per maggiori informazioni, consulta la pagina Caricamento di dati partizionati esternamente da Cloud Storage.

Dettagli sul caricamento dei dati CSV

Questa sezione descrive come BigQuery gestisce varie opzioni di formattazione CSV.

Codifica

BigQuery prevede che i dati CSV siano codificati in UTF-8. Se hai file CSV con altri tipi di codifica supportati, devi specificare esplicitamente la codifica in modo che BigQuery possa convertire correttamente i dati in UTF-8.

BigQuery supporta i seguenti tipi di codifica per i file CSV:

• UTF-8
• ISO-8859-1
• UTF-16BE (UTF-16 Big Endian)
• UTF-16LE (UTF-16 Little Endian)
• UTF-32BE (UTF-32 Big Endian)
• UTF-32LE (UTF-32 Little Endian)

Se non specifichi una codifica o se specifichi la codifica UTF-8 quando il file CSV non è codificato in UTF-8, BigQuery tenta di convertire i dati in UTF-8. In genere, se il file CSV è codificato in ISO-8859-1, i dati verranno caricati correttamente, ma potrebbero non corrispondere esattamente a quanto previsto. Se il file CSV è codificato in UTF-16BE, UTF-16LE, UTF-32BE o UTF-32LE, il caricamento potrebbe non riuscire. Per evitare errori imprevisti, specifica la codifica corretta utilizzando il flag --encoding.

Nota:se il file CSV è codificato in UTF-16BE, UTF-16LE, UTF-32BE o UTF-32LE e il flag --allow_quoted_newlines è impostato su true, le dimensioni massime del file CSV sono di 1 GB.

Nota:per impostazione predefinita, se il file CSV contiene il carattere ASCII 0 (NULL), non puoi caricare i dati in BigQuery. Se vuoi consentire l'utilizzo di 0 ASCII e di altri caratteri di controllo ASCII, imposta --preserve_ascii_control_characters=true nei tuoi job di caricamento.

Se BigQuery non riesce a convertire un carattere diverso dal carattere ASCII 0, BigQuery lo converte nel carattere di sostituzione Unicode standard: �.

Delimitatori di campo

I delimitatori nei file CSV possono essere qualsiasi carattere a singolo byte. Se il file di origine utilizza la codifica ISO-8859-1, qualsiasi carattere può essere un delimitatore. Se il file di origine utilizza la codifica UTF-8, qualsiasi carattere nell'intervallo decimale 1-127 (U+0001-U+007F) può essere utilizzato senza modifiche. Puoi inserire un carattere ISO-8859-1 al di fuori di questo intervallo come delimitatore e BigQuery lo interpreterà correttamente. Tuttavia, se utilizzi un carattere multibyte come delimitatore, alcuni byte verranno interpretati in modo errato come parte del valore del campo.

In generale, è buona norma utilizzare un delimitatore standard, ad esempio una tabulazione, una barra verticale o una virgola. Il valore predefinito è una virgola.

Tipi di dati

Boolean. BigQuery può analizzare una qualsiasi delle seguenti coppie per i dati booleani: 1 o 0, true o false, t o f, yes o no oppure y o n (tutte senza distinzione tra maiuscole e minuscole). Il rilevamento automatico dello schema rileva automaticamente tutti questi valori tranne 0 e 1.

Byte. Le colonne di tipo BYTES devono essere codificate come Base64.

Data. Le colonne con tipi DATE devono essere nel formato YYYY-MM-DD.

Data/ora. Le colonne con tipi DATETIME devono essere nel formato YYYY-MM-DD HH:MM:SS[.SSSSSS].

Area geografica. Le colonne con tipi GEOGRAFIA devono contenere stringhe in uno dei seguenti formati:

• Well-Known Text (WKT)
• Well-known binary (WKB)
• GeoJSON

Se utilizzi WKB, il valore deve essere codificato in esadecimale.

Il seguente elenco mostra esempi di dati validi:

• WKT: POINT(1 2)
• GeoJSON: { "type": "Point", "coordinates": [1, 2] }
• WKB con codifica esadecimale: 0101000000feffffffffffef3f0000000000000040

Prima di caricare i dati GEOGRAPHY, leggi anche Caricamento di dati geospaziali.

Intervallo. Le colonne di tipo INTERVAL devono essere nel formato Y-M D H:M:S[.F], dove:

• Y = Year (anno). L'intervallo supportato è 0-10.000.
• M = mese. L'intervallo supportato è 1-12.
• G = giorno. L'intervallo supportato è 1-[ultimo giorno del mese indicato].
• H = ora.
• M = minuto.
• S = secondo.
• [.F] = Frazioni di secondo fino a sei cifre, con precisione al microsecondo.

Puoi indicare un valore negativo anteponendo un trattino (-).

Il seguente elenco mostra esempi di dati validi:

• 10-6 0 0:0:0
• 0-0 -5 0:0:0
• 0-0 0 0:0:1.25

Per caricare i dati INTERVAL, devi utilizzare il comando bq load e il flag --schema per specificare uno schema. Non puoi caricare dati INTERVAL utilizzando la console.

JSON. Le virgolette vengono sottoposte a escape utilizzando la sequenza di due caratteri "". Per ulteriori informazioni, consulta un esempio di caricamento di dati JSON da un file CSV.

Ora. Le colonne di tipo TIME devono essere nel formato HH:MM:SS[.SSSSSS].

Timestamp. BigQuery accetta vari formati timestamp. Il timestamp deve includere una parte di data e una parte di ora.

• La parte della data può essere formattata come YYYY-MM-DD o YYYY/MM/DD.

• La parte del timestamp deve essere formattata come HH:MM[:SS[.SSSSSS]] (i secondi e le frazioni di secondi sono facoltativi).

• Data e ora devono essere separate da uno spazio o dalla lettera "T".

• Facoltativamente, la data e l'ora possono essere seguite da un offset UTC o dall'indicatore di zona UTC (Z). Per ulteriori informazioni, consulta la sezione Fusi orari.

Ad esempio, i seguenti sono valori timestamp validi:

• 2018-08-19 12:11
• 2018-08-19 12:11:35
• 2018-08-19 12:11:35.22
• 2018/08/19 12:11
• 2018-07-05 12:54:00 UTC
• 2018-08-19 07:11:35.220 -05:00
• 2018-08-19T12:11:35.220Z

Se fornisci uno schema, BigQuery accetta anche l'ora dell'epoca Unix per i valori timestamp. Tuttavia, il rilevamento automatico dello schema non rileva questo caso e tratta il valore come tipo numerico o stringa.

Esempi di valori di timestamp Unix epoch:

• 1534680695
• 1,534680695e12

INTERVALLO. Rappresentati nei file CSV nel formato [LOWER_BOUND, UPPER_BOUND), dove LOWER_BOUND e UPPER_BOUND sono stringhe DATE, DATETIME o TIMESTAMP valide. NULL e UNBOUNDED rappresentano valori di inizio o fine illimitati.

Nota: poiché il formato CSV dell'intervallo contiene una virgola, se il delimitatore CSV è una virgola, deve essere racchiuso tra virgolette doppie affinché il file CSV sia valido.

Di seguito sono riportati esempi di valori CSV per RANGE<DATE>:

• "[2020-01-01, 2021-01-01)"
• "[UNBOUNDED, 2021-01-01)"
• "[2020-03-01, NULL)"
• "[UNBOUNDED, UNBOUNDED)"

Rilevamento automatico dello schema

Questa sezione descrive il comportamento del rilevamento automatico dello schema durante il caricamento dei file CSV.

Delimitatore CSV

BigQuery rileva i seguenti delimitatori:

• virgola ( , )
• barra verticale ( | )
• tabulazione ( \t)

Intestazione CSV

BigQuery deduce le intestazioni confrontando la prima riga del file con le altre righe del file. Se la prima riga contiene solo stringhe e le altre righe contengono altri tipi di dati, BigQuery presuppone che la prima riga sia una riga di intestazione. BigQuery assegna i nomi delle colonne in base ai nomi dei campi nella riga di intestazione. I nomi potrebbero essere modificati per rispettare le regole di denominazione per le colonne in BigQuery. Ad esempio, gli spazi verranno sostituiti con trattini bassi.

In caso contrario, BigQuery presuppone che la prima riga sia una riga di dati e assegna nomi di colonne generici come string_field_1. Tieni presente che, dopo la creazione di una tabella, i nomi delle colonne non possono essere aggiornati nello schema, anche se puoi modificare i nomi manualmente dopo la creazione della tabella. Un'altra opzione è fornire uno schema esplicito anziché utilizzare il rilevamento automatico.

Potresti avere un file CSV con una riga di intestazione, in cui tutti i campi di dati sono stringhe. In questo caso, BigQuery non rileverà automaticamente che la prima riga è un'intestazione. Utilizza l'opzione --skip_leading_rows per saltare la riga di intestazione. In caso contrario, l'intestazione verrà importata come dati. In questo caso, valuta anche la possibilità di fornire uno schema esplicito, in modo da poter assegnare i nomi delle colonne.

Nuovi caratteri di fine riga tra virgolette nel file CSV

BigQuery rileva i caratteri di nuova riga tra virgolette all'interno di un campo CSV e non interpreta il carattere di nuova riga tra virgolette come limite di riga.

Risolvere gli errori di analisi

Se si verifica un problema durante l'analisi dei file CSV, la risorsa errors del job di caricamento viene compilata con i dettagli dell'errore.

In genere, questi errori identificano l'inizio della riga problematica con un offset di byte. Per i file non compressi, puoi utilizzare gcloud storage con l'argomento --recursive per accedere alla riga pertinente.

Ad esempio, esegui il comando bq load e ricevi un errore:

bq load
    --skip_leading_rows=1 \
    --source_format=CSV \
    mydataset.mytable \
    gs://my-bucket/mytable.csv \
    'Number:INTEGER,Name:STRING,TookOffice:STRING,LeftOffice:STRING,Party:STRING'

L'errore nell'output è simile al seguente:

Waiting on bqjob_r5268069f5f49c9bf_0000018632e903d7_1 ... (0s)
Current status: DONE
BigQuery error in load operation: Error processing job
'myproject:bqjob_r5268069f5f49c9bf_0000018632e903d7_1': Error while reading
data, error message: Error detected while parsing row starting at position: 1405.
Error: Data between close quote character (") and field separator.
File: gs://my-bucket/mytable.csv
Failure details:
- gs://my-bucket/mytable.csv: Error while reading data,
error message: Error detected while parsing row starting at
position: 1405. Error: Data between close quote character (") and
field separator. File: gs://my-bucket/mytable.csv
- Error while reading data, error message: CSV processing encountered
too many errors, giving up. Rows: 22; errors: 1; max bad: 0; error
percent: 0

In base all'errore precedente, nel file è presente un errore di formato. Per visualizzare i contenuti del file, esegui il comando gcloud storage cat:

gcloud storage cat 1405-1505 gs://my-bucket/mytable.csv --recursive

L'output è simile al seguente:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican
18,Ulysses S. Grant,"March 4, 1869",
...

In base all'output del file, il problema è una virgoletta fuori posto in "April 15, "1865.

File CSV compressi

Il debug degli errori di analisi è più difficile per i file CSV compressi, poiché l'offset di byte segnalato si riferisce alla posizione nel file non compresso. Il seguente comando gcloud storage cat trasmette il file in streaming da Cloud Storage, lo decomprime, identifica l'offset di byte appropriato e stampa la riga con l'errore di formato:

gcloud storage cat gs://my-bucket/mytable.csv.gz | gunzip - | tail -c +1406 | head -n 1

L'output è simile al seguente:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican

Opzioni CSV

Per modificare il modo in cui BigQuery analizza i dati CSV, specifica opzioni aggiuntive nella console, nello strumento a riga di comando bq o nell'API. Google Cloud

Per ulteriori informazioni sul formato CSV, consulta RFC 4180.

Opzione CSV	Opzione della console	Flag dello strumento bq	Proprietà API BigQuery	Descrizione
Delimitatore di campo	Delimitatore di campo: virgola, Tab, pipe, personalizzato	-F o --field_delimiter	fieldDelimiter (Java, Python)	(Facoltativo) Il separatore per i campi in un file CSV. Il separatore può essere qualsiasi carattere a singolo byte ISO-8859-1. BigQuery converte la stringa nella codifica ISO-8859-1 e utilizza il primo byte della stringa codificata per dividere i dati nel loro stato binario non elaborato. BigQuery supporta anche la sequenza di escape "\t" per specificare un separatore di tabulazione. Il valore predefinito è una virgola (`,`).
Righe di intestazione	Righe di intestazione da saltare	--skip_leading_rows	skipLeadingRows (Java, Python)	(Facoltativo) Un numero intero che indica il numero di righe di intestazione nei dati di origine.
Numero di record non validi consentiti	Numero di errori consentiti	--max_bad_records	maxBadRecords (Java, Python)	(Facoltativo) Il numero massimo di record non validi che BigQuery può ignorare durante l'esecuzione del job. Se il numero di record non validi supera questo valore, nel risultato del job viene restituito un errore non valido. Il valore predefinito è 0, il che richiede che tutti i record siano validi.
Caratteri di nuova riga	Consenti caratteri di fine riga con virgolette	--allow_quoted_newlines	allowQuotedNewlines (Java, Python)	(Facoltativo) Indica se consentire sezioni di dati tra virgolette che contengono caratteri di nuova riga in un file CSV. Il valore predefinito è false.
Valori nulli personalizzati	Nessuno	--null_marker	nullMarker (Java, Python)	(Facoltativo) Specifica una stringa che rappresenta un valore nullo in un file CSV. Ad esempio, se specifichi "\N", BigQuery interpreta "\N" come valore nullo durante il caricamento di un file CSV. Il valore predefinito è la stringa vuota. Se imposti questa proprietà su un valore personalizzato, BigQuery genera un errore se è presente una stringa vuota per tutti i tipi di dati, ad eccezione di STRING e BYTE. Per le colonne STRING e BYTE, BigQuery interpreta la stringa vuota come valore vuoto.
Colonne facoltative finali	Consenti righe incomplete	--allow_jagged_rows	allowJaggedRows (Java, Python)	(Facoltativo) Accetta le righe che non hanno le colonne finali facoltative. I valori mancanti vengono considerati null. Se false, i record con colonne finali mancanti vengono trattati come record non validi e, se sono presenti troppi record non validi, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false. Valido solo per i file CSV, ignorato per gli altri formati.
Valori sconosciuti	Ignora valori sconosciuti	--ignore_unknown_values	ignoreUnknownValues (Java, Python)	(Facoltativo) Indica se BigQuery deve consentire valori aggiuntivi non rappresentati nello schema della tabella. Se il valore è vero, i valori extra vengono ignorati. Se il valore è false, i record con colonne aggiuntive vengono trattati come record non validi e, se il numero di record non validi è troppo elevato, nel risultato del job viene restituito un errore non valido. Il valore predefinito è false. La proprietà sourceFormat determina cosa BigQuery considera un valore extra: CSV: colonne finali JSON: valori denominati che non corrispondono ad alcun nome di colonna
Citazione	Carattere virgolette: virgolette doppie, virgolette singole, nessuno, personalizzato	--quote	quote (Java, Python)	(Facoltativo) Il valore utilizzato per citare le sezioni di dati in un file CSV. BigQuery converte la stringa nella codifica ISO-8859-1 e poi utilizza il primo byte della stringa codificata per dividere i dati nel loro stato binario non elaborato. Il valore predefinito è una doppia virgoletta (""). Se i tuoi dati non contengono sezioni tra virgolette, imposta il valore della proprietà su una stringa vuota. Se i tuoi dati contengono caratteri di nuova riga tra virgolette, devi impostare anche la proprietà allowQuotedNewlines su true. Per includere il carattere di virgolette specifico all'interno di un valore tra virgolette, anteponi un carattere di virgolette corrispondente aggiuntivo. Ad esempio, se vuoi eseguire l'escape del carattere predefinito ' " ', utilizza ' "" '.
Codifica	Nessuno	-E o --encoding	encoding (Java, Python)	(Facoltativo) La codifica dei caratteri dei dati. I valori supportati sono UTF-8, ISO-8859-1, UTF-16BE, UTF-16LE, UTF-32BE o UTF-32LE. Il valore predefinito è UTF-8. BigQuery decodifica i dati dopo che i dati binari non elaborati sono stati suddivisi utilizzando i valori delle proprietà quote e fieldDelimiter.
Carattere di controllo ASCII	Nessuno	--preserve_ascii_control_characters	Nessuno	(Facoltativo) Se vuoi consentire ASCII 0 e altri caratteri di controllo ASCII, imposta --preserve_ascii_control_characters su true per i tuoi job di caricamento.
Fuso orario	Fuso orario	--time_zone	Nessuno	(Anteprima) (facoltativo) Fuso orario predefinito che verrà applicato durante l'analisi dei valori timestamp che non hanno un fuso orario specifico. Controlla i nomi dei fusi orari validi. Se questo valore non è presente, i valori timestamp senza un fuso orario specifico vengono analizzati utilizzando il fuso orario UTC predefinito.
Formato data	Formato data	--date_format	Nessuno	(Anteprima) (facoltativo) Elementi di formato che definiscono come vengono formattati i valori DATE nei file di input (ad esempio, MM/DD/YYYY). Se questo valore è presente, questo formato è l'unico formato DATE compatibile. La rilevamento automatico dello schema determinerà anche il tipo di colonna DATE in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATE viene analizzato con i formati predefiniti.
Formato data/ora	Formato data/ora	--datetime_format	Nessuno	(Anteprima) (facoltativo) Elementi di formato che definiscono come vengono formattati i valori DATETIME nei file di input (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato DATETIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna DATETIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo DATETIME viene analizzato con i formati predefiniti.
Formato ora	Formato ora	--time_format	Nessuno	(Anteprima) (facoltativo) Elementi di formato che definiscono come vengono formattati i valori TIME nei file di input (ad esempio, HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato TIME compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIME in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIME viene analizzato con i formati predefiniti.
Formato del timestamp	Formato del timestamp	--timestamp_format	Nessuno	(Anteprima) (facoltativo) Elementi di formato che definiscono come vengono formattati i valori TIMESTAMP nei file di input (ad esempio, MM/DD/YYYY HH24:MI:SS.FF3). Se questo valore è presente, questo formato è l'unico formato TIMESTAMP compatibile. Il rilevamento automatico dello schema determinerà anche il tipo di colonna TIMESTAMP in base a questo formato anziché a quello esistente. Se questo valore non è presente, il campo TIMESTAMP viene analizzato con i formati predefiniti.