Caricamento dei dati ORC da Cloud Storage

Questa pagina fornisce una panoramica del caricamento dei dati ORC da Cloud Storage in BigQuery.

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

Quando carichi dati ORC da Cloud Storage, puoi caricarli in una nuova tabella o partizione oppure puoi aggiungere o sovrascrivere una tabella o 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 dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa località a livello di una o più regioni del bucket Cloud Storage.

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

Limitazioni

Quando carichi dati in BigQuery da un bucket Cloud Storage, devi rispettare le seguenti limitazioni:

• Se la località del set di dati è impostata su un valore diverso da US, il bucket Cloud Storage deve trovarsi nella stessa regione o all'interno della stessa multiregione 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 di Cloud Storage. Se includi un numero di generazione nell'URI Cloud Storage, il job di caricamento non va a buon fine.

Prima di iniziare

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

Autorizzazioni obbligatorie

Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati in tabelle e partizioni BigQuery. Se stai caricando i dati da Cloud Storage, devi avere anche le autorizzazioni IAM per accedere al bucket che contiene i tuoi 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 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, consulta Autorizzazioni e ruoli predefiniti.

Autorizzazioni per caricare i dati da Cloud Storage

Per ottenere le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage, chiedi all'amministratore di concederti il ruolo IAM Amministratore Storage (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 le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:

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 essere in grado di 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 ORC

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

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

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

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

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

Quando BigQuery rileva lo schema, alcuni tipi di dati ORC vengono convertiti in tipi di dati BigQuery per renderli compatibili con la sintassi di GoogleSQL. Tutti i campi nello schema rilevato sono NULLABLE. Per ulteriori informazioni, consulta Conversioni ORC.

Quando carichi più file ORC con schemi diversi, campi identici (con lo stesso nome e lo stesso livello nidificato) specificati in più schemi devono essere mappati allo stesso tipo di dati BigQuery convertito in ogni definizione di schema.

Per fornire uno schema 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.orc".

Compressione ORC

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

• Zlib
• Snappy
• LZO
• LZ4

I dati nei file ORC non rimangono compressi dopo essere stati caricati su BigQuery. L'archiviazione dei dati è riportata in byte logici o byte fisici, a seconda del modello di fatturazione dell'archiviazione del set di dati. Per ottenere informazioni sull'utilizzo dello spazio di archiviazione, esegui una query sulla vista INFORMATION_SCHEMA.TABLE_STORAGE.

Caricamento dei dati ORC in una nuova tabella

Puoi caricare i dati ORC in una nuova tabella in questo modo:

• Utilizzo della console Google Cloud
• Utilizzo del comando bq load dello strumento a riga di comando bq
• Chiamata al metodo API jobs.insert e configurazione di un job load
• Utilizzo delle librerie client

Per caricare i dati ORC 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, quindi 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 esegui le seguenti operazioni:
   1. Seleziona un file dal bucket Cloud Storage o 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 contenente la tabella da creare, aggiungere o sovrascrivere.
   2. In Formato file, seleziona ORC.
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 che vuoi 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 in file ORC.
4. (Facoltativo) Specifica le impostazioni di partizione e cluster. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo delle tabelle in cluster.
5. Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
   • In Preferenza di scrittura, lascia selezionata l'opzione Scrivi se vuoto. Questa opzione consente di creare una nuova tabella in cui caricare i dati.
   • Se in una riga vuoi ignorare i valori 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.

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

Dopo aver creato la tabella, puoi aggiornarne la scadenza, la descrizione e le etichette, ma non puoi aggiungere una scadenza per la partizione dopo aver creato una tabella utilizzando la console Google Cloud. Per ulteriori informazioni, consulta Gestione delle tabelle.

SQL

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

3. Fai clic su Esegui.

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

bq

Utilizza il comando bq load, specifica ORC come 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 località.

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 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 in una tabella esistente.
• --time_partitioning_expiration: un numero intero che specifica (in secondi) quando deve essere eliminata una partizione basata sul tempo. La data di 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 è abilitato senza questo valore, viene creata una tabella partizionata per data di importazione.
• --require_partition_filter: se 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 sulle tabelle partizionate.
• --clustering_fields: un elenco separato da virgole di massimo quattro nomi di colonna utilizzato per creare una tabella in cluster.

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

  Per ulteriori informazioni sulle tabelle partizionate, consulta:

  • Creazione di tabelle partizionate

  Per ulteriori informazioni sulle tabelle in cluster, consulta:

  • Creazione e utilizzo delle tabelle in cluster

  Per saperne di più sulla crittografia delle tabelle, vedi:

  • Protezione dei dati con le chiavi Cloud KMS

Per caricare i dati ORC in BigQuery, inserisci questo comando:

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

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

Esempi:

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

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

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

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

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

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=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

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 Cloud Storage con caratteri jolly.

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

1. Crea un job load che punta 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 ORC impostando la proprietà sourceFormat su ORC.

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 è 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 di importazione di alcune righe. Gli errori non irreversibili sono elencati nella proprietà status.errors dell'oggetto job restituito.

Note dell'API:

• I job di caricamento sono atomici e coerenti. Se un job di caricamento ha esito negativo, nessuno dei dati è disponibile e, se un job di caricamento ha esito positivo, sono 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ù solido in caso di errore di rete perché il client può eseguire il polling o riprovare sull'ID job noto.

• La chiamata a jobs.insert per un determinato ID job è idempotente. Puoi riprovare tutte le volte che vuoi sullo stesso ID job e al massimo una di queste operazioni viene eseguita correttamente.

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        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.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            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}");
    }
}

Go

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

Per eseguire l'autenticazione in 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"
)

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
func importORC(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	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

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.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 ORC data from Cloud Storage into a new BigQuery table
public class LoadOrcFromGCS {

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

  public static void loadOrcFromGCS(
      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();

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

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("ORC 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 disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

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

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

  /**
   * TODO(developer): Uncomment the following line 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: 'ORC',
    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 disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$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 disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta 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(source_format=bigquery.SourceFormat.ORC)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

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

Ruby

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.

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

require "google/cloud/bigquery"

def load_table_gcs_orc 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.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  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

Aggiungere o sovrascrivere una tabella con dati ORC

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

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

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

Opzione della console	flag dello 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) Accoda 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 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.

Puoi aggiungere o sovrascrivere una tabella in questo modo:

• Utilizzo della console Google Cloud
• Utilizzo del comando bq load dello strumento a riga di comando bq
• Chiamata al metodo API jobs.insert e configurazione di un job load
• Utilizzo delle librerie client

Nota: questa pagina non tratta l'aggiunta o la sovrascrittura di tabelle partizionate. Per informazioni su come aggiungere e sovrascrivere le tabelle partizionate, consulta: Aggiunta e sovrascrittura dei dati delle tabella partizionata partizionate.

Per aggiungere o sovrascrivere una tabella con dati ORC:

Console

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, quindi 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 esegui le seguenti operazioni:
   1. Seleziona un file dal bucket Cloud Storage o 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 contenente la tabella da creare, aggiungere o sovrascrivere.
   2. In Formato file, seleziona ORC.
Nota: puoi modificare lo schema della tabella quando la aggiungi o la sovrascrivi. Per ulteriori informazioni sulle modifiche allo schema supportate durante un'operazione di caricamento, consulta Modifica degli schemi delle tabelle.
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 che vuoi 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 in file ORC.
Nota: puoi modificare lo schema della tabella quando la aggiungi o la sovrascrivi. Per saperne di più sulle modifiche allo schema supportate durante un'operazione di caricamento, consulta la pagina relativa alla modifica degli schemi delle tabelle.
4. (Facoltativo) Specifica le impostazioni di partizione e cluster. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo delle 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 in una riga vuoi ignorare i valori 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 viene aggiunto un file ORC 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 = 'ORC',
     uris = ['gs://bucket/path/file.orc']);
   

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire le query, consulta 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 alcun flag, l'impostazione predefinita prevede l'aggiunta di dati. Fornisci il flag --source_format e impostalo su ORC. Poiché gli schemi ORC vengono recuperati automaticamente dai dati di origine autodescritti, non è necessario fornire una definizione dello schema.

Nota: puoi modificare lo schema della tabella quando la aggiungi 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 località.

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

Dove:

• location è la tua località. Il flag --location è facoltativo. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.
• format è pari a ORC.
• 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.

Esempi:

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

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Per informazioni su come aggiungere e sovrascrivere le tabelle partizionate utilizzando lo strumento a riga di comando bq, consulta l'articolo sull'aggiunta e sulla sovrascrittura dei dati delle tabella partizionata partizionate.

API

1. Crea un job load che punta 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 ORC.

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

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, 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}");
    }
}

Go

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

Per eseguire l'autenticazione in 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"
)

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importORCTruncate(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

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

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

Java

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

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

  public static void runLoadOrcFromGcsTruncate() {
    // 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.orc";
    loadOrcFromGcsTruncate(datasetName, tableName, sourceUri);
  }

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

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

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

Per eseguire l'autenticazione in 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 the 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.orc';

async function loadORCFromGCSTruncate() {
  /**
   * 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: 'ORC',
    // 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 di configurazione di PHP disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->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 disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in 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.ORC,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
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))

Ruby

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.

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

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate dataset_id = "your_dataset_id",
                                table_id   = "your_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  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

Carica dati ORC partizionati hive

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

Conversioni ORC

BigQuery converte i tipi di dati ORC nei seguenti tipi di dati BigQuery:

Tipi primitivi

Tipo di dati ORC	Tipo di dati BigQuery	Note
boolean	BOOLEANO
byte	INTEGER
corti	INTEGER
int	INTEGER
lunghi	INTEGER
float	FLOAT
double	FLOAT
string	STRING	Solo UTF-8
varchar	STRING	Solo UTF-8
caratteri	STRING	Solo UTF-8
file binario	BYTES
date	DATA	Un tentativo di convertire qualsiasi valore nei dati ORC che sia inferiore a -719162 giorni o superiore a 2932896 giorni restituisce un errore invalid date value. Se questo problema ti riguarda, contatta l'assistenza per richiedere la conversione dei valori non supportati al valore minimo BigQuery di 0001-01-01 o al valore massimo di 9999-12-31, a seconda dei casi.
timestamp	TIMESTAMP	ORC supporta la precisione in nanosecondi, ma BigQuery converte i valori inferiori al microsecondo in microsecondi quando i dati vengono letti. Un tentativo di convertire qualsiasi valore nei dati ORC che sia inferiore a -719162 giorni o superiore a 2932896 giorni restituisce un errore invalid date value. Se questo problema ti riguarda, contatta l'assistenza per richiedere la conversione dei valori non supportati al valore minimo di BigQuery di 0001-01-01 o al valore massimo di 9999-12-31, a seconda dei casi.
decimal	NUMERIC, BIGNUMERIC o STRING	Vedi Tipo decimale.

Tipo decimale

I tipi logici Decimal possono essere convertiti in 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:

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

Tipi complessi

Tipo di dati ORC	Tipo di dati BigQuery	Note
struct	RECORD	Tutti i campi sono NULLABLE. L'ordine dei campi viene ignorato. Il nome di un campo deve essere un nome di colonna valido.
map<K,V>	RECORD	Un campo ORC map<K,V> viene convertito in un RECORD ripetuto che contiene due campi: una chiave dello stesso tipo di dati di K e un valore dello stesso tipo di dati di V. Entrambi i campi sono NULLABLE.
list	campi ripetuti	Gli elenchi nidificati e gli elenchi di mappe non sono supportati.
unione	RECORD	Quando l'unione ha una sola variante, viene convertita in un campo NULLABLE. In caso contrario, un'unione viene convertita in un RECORD con un elenco di campi NULLABLE. I campi NULLABLE hanno suffissi come field_0, field_1 e così via. A uno solo di questi campi viene assegnato un valore durante la lettura dei dati.

Nomi delle colonne

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 del nome di una colonna con un numero. Presta attenzione quando avvii colonne con un numero, poiché l'utilizzo di nomi di colonna flessibili con l'API BigQuery Storage Read o l'API BigQuery Storage Write richiede una gestione speciale. Per ulteriori informazioni sul supporto dei nomi delle colonne flessibili, consulta i nomi delle colonne flessibili.

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

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

Non sono consentiti nomi di colonna duplicati anche se le maiuscole e le minuscole sono diverse. Ad esempio, una colonna denominata Column1 è considerata identica a una colonna denominata column1. Per ulteriori informazioni sulle regole di denominazione delle colonne, consulta Nomi delle colonne nel riferimento di GoogleSQL.

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

• Evita di utilizzare lo stesso nome per una tabella e le relative 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

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Hai maggiore flessibilità nella scelta dei nomi per le colonne, tra cui l'accesso esteso ai caratteri in lingue diverse dall'inglese e a simboli aggiuntivi.

I nomi di colonna flessibili supportano i seguenti caratteri:

• Qualsiasi lettera in qualsiasi lingua, come 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 rappresentati dall'espressione regolare Unicode \p{Pd}.
• Qualsiasi contrassegno destinato ad accompagnare un altro carattere come rappresentato dall'espressione regolare Unicode \p{M}. Ad esempio accenti, dieresi o riquadri di accompagnamento.
• I seguenti caratteri speciali:
  • La 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.
  • 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 di (>) come rappresentato dall'espressione regolare Unicode \u003E.
  • Un segno numerico (#) come rappresentato dall'espressione regolare Unicode \u0023.
  • Una linea verticale (|) come rappresentata dall'espressione regolare Unicode \u007c.
  • Spazio vuoto.

I nomi di colonna flessibili non supportano i seguenti caratteri speciali:

• Un punto esclamativo (!) come rappresentato dall'espressione regolare Unicode \u0021.
• Una virgoletta (") rappresentata dall'espressione regolare Unicode \u0022.
• Un simbolo del dollaro ($) come rappresentato dall'espressione regolare Unicode \u0024.
• Una parentesi aperta (() come rappresentata dall'espressione regolare Unicode \u0028.
• Una parentesi chiusa ()) come 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 (/) come 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.
• Un simbolo di chiocciola (@) come rappresentato 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 (~) come rappresentata dall'espressione regolare Unicode \u007E.

Per linee guida aggiuntive, consulta Nomi delle colonne.

I caratteri delle colonne espansi sono supportati sia dall'API BigQuery Storage Read che dall'API BigQuery Storage Write. 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 ampliato di caratteri Unicode con l'API BigQuery Storage Write, devi fornire lo schema con la notazione column_name, a meno che non utilizzi 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.

• Per impostazione predefinita, il caricamento dei dati Parquet non supporta i nomi di colonna flessibili. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione nell'anteprima, eventuali nomi di colonna non validi (ad esempio la 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.
• Il caricamento dei dati CSV utilizzando il rilevamento automatico dello schema non supporta i nomi di colonna flessibili per impostazione predefinita. Per registrarti a questa anteprima, compila il modulo di registrazione. Tieni presente che dopo la registrazione nell'anteprima, eventuali nomi di colonna non validi (ad esempio la 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.

I nomi di colonna flessibili non sono supportati con le tabelle esterne.

NULL valori

Tieni presente che per i job di caricamento, BigQuery ignora gli elementi NULL per il tipo composto list, perché altrimenti verrebbero convertiti in elementi NULL ARRAY che non possono rimanere in una tabella (per i dettagli, consulta Tipi di dati).

Per ulteriori informazioni sui tipi di dati ORC, consulta la Specifica ORCTM di Apache v1.