Caricamento dei dati Parquet da Cloud Storage

Questa pagina fornisce una panoramica del caricamento dei dati Parquet da Cloud Storage a BigQuery.

Parquet è un formato di dati open source orientato a colonne ampiamente utilizzato nell'ecosistema Apache Hadoop.

Quando carichi dati Parquet da Cloud Storage, puoi caricarli in una nuova tabella o partizione oppure aggiungere o sovrascrivere una tabella o una partizione esistente. Quando i dati vengono caricati in BigQuery, vengono convertiti in formato a colonne per Condensatore (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à a singola regione o a più regioni del bucket Cloud Storage.

Per informazioni sul caricamento dei dati Parquet da un file locale, consulta Caricamento di dati da file locali.

Limitazioni

Sei soggetto alle seguenti 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 all'interno della stessa area multiregionale del set di dati.
  • BigQuery non garantisce la coerenza dei dati per le origini dati esterne. Le modifiche ai dati sottostanti durante l'esecuzione di una query possono causare comportamenti imprevisti.

  • 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 riesce.

  • Il caricamento dei dati Parquet segue la convenzione di denominazione delle colonne e non supporta i nomi flessibili delle colonne per impostazione predefinita. Per registrarti a questa anteprima, compila il modulo di registrazione.

  • Non puoi utilizzare un carattere jolly nell'URI Cloud Storage se uno dei file da caricare ha schemi diversi. Qualsiasi differenza nella posizione delle colonne viene considerata come uno schema diverso.

Requisiti del file di input

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

  • Mantieni le dimensioni delle righe fino a 50 MB o inferiori.
  • Se i dati di input contengono più di 100 colonne, valuta la possibilità di ridurre le dimensioni della pagina in modo che siano inferiori a quelle predefinite (1 * 1024 * 1024 byte). Ciò è particolarmente utile se utilizzi una compressione significativa.

Prima di iniziare

Concedi ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento e crea un set di dati per 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 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 Storage Admin (roles/storage.admin) per il 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 visualizzare esattamente le autorizzazioni necessarie, 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 i ruoli personalizzati o altri ruoli predefiniti.

crea un set di dati

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

Schemi Parquet

Quando carichi i file Parquet in BigQuery, lo schema della tabella viene recuperato automaticamente dai dati di origine autodescrittivi. Quando BigQuery recupera lo schema dai dati di origine, viene utilizzato l'ultimo file in ordine alfabetico.

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

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

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

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

Quando carichi più file Parquet con schemi diversi, le colonne identiche specificate in più schemi devono avere la stessa modalità in ogni definizione dello schema.

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

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

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

Compressione Parquet

BigQuery supporta i seguenti codec di compressione per i contenuti dei file di Parquet:

  • GZip
  • LZO_1C
  • LZO_1X
  • LZ4_RAW
  • Snappy
  • ZSTD

Caricamento dei dati Parquet in una nuova tabella

Puoi caricare i dati Parquet in una nuova tabella in uno dei seguenti modi:

  • Nella console Google Cloud
  • Il comando bq load dello strumento a riga di comando bq
  • Il metodo API jobs.insert e la configurazione di un job load
  • Le librerie client

Per caricare i dati Parquet da Cloud Storage in una nuova tabella BigQuery:

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 segui questi passaggi:
      1. Seleziona un file dal bucket Cloud Storage oppure inserisci l'URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati che contiene la tabella da creare, aggiungere o sovrascrivere. seleziona il file di origine per creare una tabella BigQuery
      2. In Formato file, seleziona Parquet.
    2. Nella sezione Destinazione, specifica i seguenti dettagli:
      1. In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
      2. Nel campo Tabella, inserisci il nome della tabella da creare.
      3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
    3. Nella sezione Schema non è necessaria alcuna azione. Lo schema si descrive autonomamente nei file Parquet.
    4. (Facoltativo) Specifica le impostazioni di partizione e clustering. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
    5. Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
      • In Write preference (Preferenza di scrittura), lascia selezionata l'opzione Write if empty (Scrivi se vuoto). Questa opzione crea una nuova tabella e carica i dati al suo interno.
      • Se vuoi ignorare i valori in una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
      • 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.
    6. Fai clic su Crea tabella.

SQL

Utilizza l'istruzione DDL LOAD DATA. L'esempio seguente carica un file Parquet 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 = 'PARQUET',
  uris = ['gs://bucket/path/file.parquet']);

  3. Fai clic su Esegui.

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

bq

Utilizza il comando bq load, specifica PARQUET con 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 caratteri jolly.

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

Altri flag facoltativi includono:

  • --time_partitioning_type: abilita il partizionamento basato sul tempo su 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 su una tabella esistente.
  • --time_partitioning_expiration: un numero intero che specifica (in secondi) quando deve essere eliminata una partizione basata sul tempo. La scadenza restituisce la 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 viene abilitato senza questo valore, viene creata unatabella partizionata per data di importazionee.
  • --require_partition_filter: quando abilitata, questa opzione richiede agli utenti di 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 maggiori informazioni, consulta Esecuzione di query su tabelle partizionate.
  • --clustering_fields: un elenco separato da virgole di massimo quattro nomi di colonna 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 l'opzione di abilitare i nomi flessibili delle colonne. Per maggiori informazioni, vedi load_option_list.

    Per saperne di più sulle tabelle partizionate, consulta:

    Per ulteriori informazioni sulle tabelle in cluster, consulta:

    Per ulteriori informazioni sulla crittografia delle tabelle, consulta:

Per caricare i dati Parquet 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 nell'area geografica di Tokyo, puoi impostare il valore del flag su asia-northeast1. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.
  • FORMAT: PARQUET.
  • 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 o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.

Esempi:

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

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

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

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

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.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

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.

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

API

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

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

  3. La proprietà source URIs deve essere completa, nel formato gs://BUCKET/OBJECT. Ogni URI può contenere un carattere jolly '*'.

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

  5. Per controllare lo stato del job, chiama jobs.get(JOB_ID*) sostituendo JOB_ID con 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 è andata a buon fine e l'oggetto include informazioni che descrivono l'errore. Quando una richiesta non va a buon fine, non viene creata alcuna tabella e non vengono caricati dati.
    • Se status.errorResult non è presente, il job è stato completato correttamente; anche se potrebbero essersi verificati alcuni errori non irreversibili, come problemi nell'importazione di alcune righe. Gli errori non irreversibili sono elencati nella proprietà status.errors dell'oggetto job restituito.

Note API:

  • I job di caricamento sono atomici e coerenti: se un job di caricamento non riesce, nessuno dei dati è disponibile 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 quando chiami jobs.insert per creare un job di caricamento. Questo approccio è più efficace per gli errori di rete perché il client può eseguire il polling o riprovare sull'ID job noto.

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

Go

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

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client. 

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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 nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    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();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .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 job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \n" + e.toString());
    }
  }
}

Node.js

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

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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 Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

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

  /**
   * 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: 'PARQUET',
    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 per la configurazione di PHP nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di BigQuery.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$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 per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.

Utilizza il metodo Client.load_table_from_uri() per avviare un job di caricamento da Cloud Storage. Per utilizzare Parquet, imposta la proprietà LoadJobConfig.source_format sulla stringa PARQUET e passa la configurazione del job come argomento job_config al metodo load_table_from_uri(). 
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.PARQUET,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

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))

Aggiunta o sovrascrittura di una tabella con dati Parquet

Puoi caricare ulteriori dati 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 l'azione da eseguire quando carichi i dati da un file di origine o da un risultato di una query.

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

Opzione console flag strumento bq Proprietà API BigQuery Descrizione
Scrivi se vuota Funzionalità 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 è Aggiungi 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 eventuali chiavi Cloud KMS.

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

Puoi aggiungere o sovrascrivere una tabella utilizzando uno dei seguenti elementi:

  • Nella console Google Cloud
  • Il comando bq load dello strumento a riga di comando bq
  • Il metodo API jobs.insert e la configurazione di un job load
  • Le librerie client

Per aggiungere o sovrascrivere una tabella con dati Parquet:

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 segui questi passaggi:
      1. Seleziona un file dal bucket Cloud Storage oppure inserisci l'URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati che contiene la tabella da creare, aggiungere o sovrascrivere. seleziona il file di origine per creare una tabella BigQuery
      2. In Formato file, seleziona Parquet.
    2. Nella sezione Destinazione, specifica i seguenti dettagli:
      1. In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
      2. Nel campo Tabella, inserisci il nome della tabella da creare.
      3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
    3. Nella sezione Schema non è necessaria alcuna azione. Lo schema si descrive autonomamente nei file Parquet.
    4. (Facoltativo) Specifica le impostazioni di partizione e clustering. Per saperne di più, consulta 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 ed esegui le seguenti operazioni:
      • In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi tabella.
      • Se vuoi ignorare i valori in una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
      • 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.
    6. Fai clic su Crea tabella.

SQL

Utilizza l'istruzione DDL LOAD DATA. Nell'esempio seguente, un file Parquet viene aggiunto 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 = 'PARQUET',
  uris = ['gs://bucket/path/file.parquet']);

  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 la tabella. Utilizza il flag --noreplace per aggiungere dati alla tabella. Se non viene specificato nessun flag, il valore predefinito è l'aggiunta di dati. Fornisci il flag --source_format e impostalo su PARQUET. Poiché gli schemi Parquet vengono recuperati automaticamente dai dati di origine autodescrittivi, non è necessario fornire una definizione dello schema.

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

Altri flag facoltativi includono:

  • --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

Sostituisci quanto segue:

  • location: la tua posizione. Il flag --location è facoltativo. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.
  • format: PARQUET.
  • 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 o un elenco di URI separati da virgole. Sono supportati anche i caratteri jolly.

Esempi:

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

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Per informazioni sull'aggiunta e la sovrascrittura delle tabelle partizionate mediante lo strumento a riga di comando bq, consulta Aggiungere e sovrascrivere i tabella partizionata partizionate.

API

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

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

  3. La proprietà source URIs deve essere completa, nel formato gs://BUCKET/OBJECT. Puoi includere più URI sotto forma di 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 PARQUET.

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

Go

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

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client. 

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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 per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    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();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // 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 job = 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 = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * 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: 'PARQUET',
    // 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;
  }
}

PHP

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

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->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 per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.

Per sostituire le righe in una tabella esistente, imposta la proprietà LoadJobConfig.write_disposition su WRITE_TRUNCATE. 
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.PARQUET,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
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 Parquet partizionati in hive

BigQuery supporta il caricamento di dati Parquet partizionati hive archiviati in Cloud Storage e compila le colonne di partizionamento hive come colonne nella tabella gestita da BigQuery di destinazione. Per maggiori informazioni, consulta Caricare dati partizionati esternamente.

Conversioni Parquet

Questa sezione descrive come BigQuery analizza i vari tipi di dati durante il caricamento dei dati Parquet.

Alcuni tipi di dati Parquet (come INT32, INT64, BYTE_ARRAY e FIXED_LEN_BYTE_ARRAY) possono essere convertiti in più tipi di dati BigQuery. Per assicurarti che BigQuery converta correttamente i tipi di dati Parquet, specifica il tipo di dati appropriato nel file Parquet.

Ad esempio, per convertire il tipo di dati Parquet INT32 nel tipo di dati BigQuery DATE, specifica quanto segue:

optional int32 date_col (DATE);

BigQuery converte i tipi di dati Parquet nei tipi di dati BigQuery descritti nelle sezioni seguenti.

Conversioni dei tipi

Tipo di Parquet Tipi logici del Parquet Tipo di dati BigQuery
BOOLEAN Nessuna BOOLEANO
INT32 Nessuno, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32) INT64
INT32 DECIMALE NUMERIC, BIGNUMERIC o STRING
INT32 DATE DATA
INT64 Nessuno, INTEGER (UINT_64, INT_64) INT64
INT64 DECIMALE NUMERIC, BIGNUMERIC o STRING
INT64 TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS) TIMESTAMP
INT64 TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS) TIMESTAMP
INT96 Nessuna TIMESTAMP
FLOAT Nessuna FLOAT64
DOUBLE Nessuna FLOAT64
BYTE_ARRAY Nessuna BYTES
BYTE_ARRAY STRING (UTF8) STRING
FIXED_LEN_BYTE_ARRAY DECIMALE NUMERIC, BIGNUMERIC o STRING
FIXED_LEN_BYTE_ARRAY Nessuna BYTES

I gruppi nidificati vengono convertiti in tipi STRUCT. Non sono supportate altre combinazioni di tipi Parquet e tipi convertiti.

Tipi logici non firmati

I tipi Parquet UINT_8, UINT_16, UINT_32 e UINT_64 non sono firmati. BigQuery tratterà i valori con questi tipi come non firmati durante il caricamento in una colonna INTEGER con firma di BigQuery. Nel caso di UINT_64, verrà restituito un errore se il valore non firmato supera il valore massimo di INTEGER pari a 9.223.372.036.854.775.807.

Tipo logico decimale

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

Tipo logico enum

Enum tipi logici possono essere convertiti in STRING o BYTES. Specifica il tipo di target convertito come segue:

Elenca tipo logico

Puoi attivare l'inferenza dello schema per i tipi logici Parquet LIST. BigQuery controlla se il nodo LIST è in formato standard o in uno dei formati descritti dalle regole di compatibilità con le versioni precedenti:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

In caso affermativo, il campo corrispondente per il nodo LIST nello schema convertito viene considerato come se il nodo avesse il seguente schema:

repeated <element-type> <name>

I nodi "list" ed "element" sono omessi.

Dati geospaziali

Puoi caricare file Parquet che contengono WKT, WKB con codifica esadecimale o GeoJSON in una colonna STRING oppure WKB in una colonna BYTE_ARRAY specificando uno schema BigQuery di tipo GEOGRAPHY. Consulta la sezione Caricamento di dati geospaziali.

Conversioni dei nomi di colonna

Il nome di una colonna può contenere lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_) e deve iniziare con una lettera o un trattino basso. Se utilizzi nomi di colonna flessibili, BigQuery supporta l'inizio di un nome di colonna con un numero. Presta attenzione quando inizi le colonne con un numero, poiché l'utilizzo di nomi di colonna flessibili con l'API BigQuery Storage Read o l'API BigQuery StorageWrite richiede una gestione speciale. Per ulteriori informazioni sul supporto dei nomi di colonna flessibili, consulta nomi di colonna flessibili.

I nomi delle colonne hanno una lunghezza massima di 300 caratteri. I nomi di colonna non possono utilizzare uno dei seguenti prefissi:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

Non sono consentiti nomi di colonna duplicati anche se l'uso delle maiuscole e delle minuscole è diverso. Ad esempio, una colonna denominata Column1 è considerata identica a una colonna denominata column1. Per scoprire di più sulle regole di denominazione delle colonne, consulta Nomi delle colonne nella documentazione di riferimento di GoogleSQL.

Se il nome di una tabella (ad esempio test) corrisponde ai nomi di una colonna (ad esempio test), l'espressione SELECT interpreta la colonna test come STRUCT contenente tutte le altre colonne della tabella. Per evitare il conflitto, utilizza uno dei seguenti metodi:

  • Evita di utilizzare lo stesso nome per una tabella e le sue colonne.

  • Assegna alla tabella un alias diverso. Ad esempio, la seguente query assegna un alias di tabella t alla tabella project1.dataset.test:

    SELECT test FROM project1.dataset.test AS t;

  • Includi il nome della tabella quando fai riferimento a una colonna. Ad esempio:

    SELECT test.test FROM project1.dataset.test;

Nomi delle colonne flessibili

Hai maggiore flessibilità nella scelta dei nomi nelle colonne, compreso l'accesso esteso a caratteri in lingue diverse dall'inglese e a simboli aggiuntivi.

I nomi delle colonne flessibili supportano i seguenti caratteri:

  • Qualsiasi lettera in qualsiasi lingua, rappresentata dall'espressione regolare Unicode \p{L}.
  • Qualsiasi carattere numerico in qualsiasi lingua, come rappresentato dall'espressione regolare Unicode \p{N}.
  • Qualsiasi carattere di punteggiatura del connettore, inclusi i trattini bassi, come rappresentato dall'espressione regolare Unicode \p{Pc}.
  • Un trattino o un trattino come rappresentato dall'espressione regolare Unicode \p{Pd}.
  • Qualsiasi marchio destinato ad accompagnare un altro carattere, come rappresentato dall'espressione regolare Unicode \p{M}. Ad esempio, accenti, dieresi o contenuti che includono riquadri.
  • I seguenti caratteri speciali:
    • Una e commerciale (&) rappresentata dall'espressione regolare Unicode \u0026.
    • Un segno di percentuale (%) come rappresentato dall'espressione regolare Unicode \u0025.
    • Un segno di uguale (=) come rappresentato dall'espressione regolare Unicode \u003D.
    • Un segno più (+) come rappresentato dall'espressione regolare Unicode \u002B.
    • I due punti (:) come rappresentati dall'espressione regolare Unicode \u003A.
    • Un apostrofo (') come rappresentato dall'espressione regolare Unicode \u0027.
    • Un segno di minore (<) come rappresentato dall'espressione regolare Unicode \u003C.
    • Un segno di maggiore (>) come rappresentato dall'espressione regolare Unicode \u003E.
    • Un segno numerico (#) come rappresentato dall'espressione regolare Unicode \u0023.
    • Una riga verticale (|) rappresentata dall'espressione regolare Unicode \u007c.
    • Spazio vuoto.

I nomi delle colonne flessibili non supportano i seguenti caratteri speciali:

  • Un punto esclamativo (!) come rappresentato dall'espressione regolare Unicode \u0021.
  • Una virgoletta (") come rappresentata dall'espressione regolare Unicode \u0022.
  • Un simbolo del dollaro ($) come rappresentato dall'espressione regolare Unicode \u0024.
  • Una parentesi aperta (() rappresentata dall'espressione regolare Unicode \u0028.
  • Una parentesi chiusa ()) rappresentata dall'espressione regolare Unicode \u0029.
  • Un asterisco (*) come rappresentato dall'espressione regolare Unicode \u002A.
  • Una virgola (,) come rappresentata dall'espressione regolare Unicode \u002C.
  • Un punto (.) come rappresentato dall'espressione regolare Unicode \u002E.
  • Una barra (/) rappresentata dall'espressione regolare Unicode \u002F.
  • Un punto e virgola (;) come rappresentato dall'espressione regolare Unicode \u003B.
  • Un punto interrogativo (?) come rappresentato dall'espressione regolare Unicode \u003F.
  • Una chiocciola (@) come rappresentata dall'espressione regolare Unicode \u0040.
  • Una parentesi quadra aperta ([) come rappresentata dall'espressione regolare Unicode \u005B.
  • Una barra rovesciata (\) come rappresentata dall'espressione regolare Unicode \u005C.
  • Una parentesi quadra chiusa (]) come rappresentata dall'espressione regolare Unicode \u005D.
  • Un accento circonflesso (^) come rappresentato dall'espressione regolare Unicode \u005E.
  • Un accento grave (`) come rappresentato dall'espressione regolare Unicode \u0060.
  • Una parentesi graffa aperta {{) come rappresentata dall'espressione regolare Unicode \u007B.
  • Una parentesi graffa chiusa (}) come rappresentata dall'espressione regolare Unicode \u007D.
  • Una tilde (~) rappresentata dall'espressione regolare Unicode \u007E.

Per ulteriori linee guida, consulta Nomi delle colonne.

I caratteri della colonna espansi sono supportati sia dall'API BigQuery Storage Read che dall'API BigQuery Storage Scrivi. Per utilizzare l'elenco espanso di caratteri Unicode con l'API BigQuery Storage Read, devi impostare un flag. Puoi utilizzare l'attributo displayName per recuperare il nome della colonna. L'esempio seguente mostra come impostare un flag con il client Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Per utilizzare l'elenco espanso di caratteri Unicode con l'API BigQuery StorageWrite, devi fornire lo schema con la notazione column_name, a meno che tu non stia utilizzando l'oggetto writer JsonStreamWriter. L'esempio seguente mostra come fornire lo schema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

In questo esempio, item_name_column e item_description_column sono nomi segnaposto che devono essere conformi alla convenzione di denominazione per il buffer di protocollo. Tieni presente che le annotazioni column_name hanno sempre la precedenza sui nomi dei segnaposto.

  • Il caricamento dei dati Parquet non supporta i nomi flessibili delle colonne per impostazione predefinita. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione all'anteprima, eventuali nomi di colonna non validi (ad esempio, regole di confronto dei nomi di colonna) restituiscono un errore. Per i progetti non registrati, la richiesta di caricamento sostituisce i caratteri non validi con trattini bassi, invece di restituire un errore.
  • Per impostazione predefinita, il caricamento dei dati CSV tramite il rilevamento automatico dello schema non supporta i nomi flessibili delle colonne. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione all'anteprima, eventuali nomi di colonna non validi (ad esempio, regole di confronto dei nomi di colonna) restituiscono un errore. Per i progetti non registrati, la richiesta di caricamento sostituisce i caratteri non validi con trattini bassi anziché restituire un errore.

Limitazioni

I nomi delle colonne flessibili non sono supportati con le tabelle esterne.

Non puoi caricare file Parquet contenenti colonne che hanno un punto (.) nel nome della colonna.

Se il nome di una colonna Parquet contiene altri caratteri (tranne il punto), questi vengono sostituiti con trattini bassi. Puoi aggiungere trattini bassi finali ai nomi delle colonne per evitare collisioni. Ad esempio, se un file Parquet contiene 2 colonne Column1 e column1, le colonne vengono caricate rispettivamente come Column1 e column1_.

Debug del file Parquet

Se i job di caricamento non riescono e generano errori nei dati, puoi utilizzare PyArrow per verificare se i file di dati di Parquet sono danneggiati. Se PyArrow non riesce a leggere i file, è probabile che vengano rifiutati dal job di caricamento BigQuery. L'esempio seguente mostra come leggere i contenuti di un file Parquet utilizzando PyArrow:

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Per ulteriori informazioni, consulta la documentazione di PyArrow.