Esporta i dati della tabella

Questa pagina descrive come esportare o estrarre dati dalle tabelle BigQuery in Cloud Storage.

Dopo aver caricato i dati in BigQuery, puoi esportarli in diversi formati. BigQuery può esportare fino a 1 GB di dati in un singolo file. Se esporti più di 1 GB di dati, devi esportare i tuoi dati in più file. Quando esporti i dati in più file, le dimensioni dei file variano.

Puoi utilizzare un servizio come Dataflow per leggere i dati da BigQuery anziché esportarli manualmente. Per ulteriori informazioni sull'utilizzo di Dataflow per leggere e scrivere in BigQuery, consulta la pagina relativa a BigQuery I/O nella documentazione di Apache Beam.

Puoi anche esportare i risultati di una query utilizzando l'istruzione EXPORT DATA.

Limitazioni all'esportazione

Quando esporti dati da BigQuery, tieni presente quanto segue:

• Non puoi esportare i dati della tabella in un file locale, in Fogli Google o in Google Drive. L'unica località di esportazione supportata è Cloud Storage. Per informazioni sul salvataggio dei risultati delle query, consulta la sezione Scaricare e salvare i risultati delle query.
• Puoi esportare fino a 1 GB di dati della tabella in un singolo file. Se esporti più di 1 GB di dati, utilizza un carattere jolly per esportare i dati in più file. Quando esporti i dati in più file, le dimensioni dei file variano. Per limitare le dimensioni del file esportato, puoi eseguire il partizionamento dei dati ed esportare ogni partizione.
• Non è garantito che le dimensioni del file generate quando si utilizza l'istruzione EXPORT DATA.
• Il numero di file generati da un job di esportazione può variare.
• Non puoi esportare dati ripetuti e nidificati in formato CSV. I dati nidificati e ripetuti sono supportati per le esportazioni Avro, JSON e Parquet.
• Quando esporti i dati in formato JSON, i tipi di dati INT64 (intero) vengono codificati come stringhe JSON per preservare la precisione a 64 bit quando i dati vengono letti da altri sistemi.
• Non puoi esportare i dati da più tabelle in un singolo job di esportazione.
• Non puoi scegliere un tipo di compressione diverso da GZIP quando esporti i dati utilizzando la console Google Cloud.
• Quando esporti i dati in un bucket Cloud Storage configurato con un criterio di conservazione, BigQuery potrebbe non riuscire a scrivere i file nel bucket. Ti consigliamo di ridurre il criterio di conservazione per la durata dei job di esportazione.
• Quando esporti una tabella in formato JSON, i simboli <, > e & vengono convertiti utilizzando la notazione Unicode \uNNNN, dove N è una cifra esadecimale. Ad esempio, profit&loss diventa profit\u0026loss. Questa conversione Unicode viene eseguita per evitare vulnerabilità di sicurezza.
• L'ordine dei dati delle tabelle esportate non è garantito a meno che non utilizzi l'istruzione EXPORT DATA e specifichi una clausola ORDER BY nella query_statement.

Prima di iniziare

Concedi i ruoli Identity and Access Management (IAM) che conferiscono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento.

Autorizzazioni obbligatorie

Per eseguire le attività in questo documento, devi disporre delle seguenti autorizzazioni.

Autorizzazioni per esportare i dati da una tabella BigQuery

Per esportare i dati da una tabella BigQuery, devi disporre dell'autorizzazione IAM bigquery.tables.export.

Ciascuno dei seguenti ruoli IAM predefiniti include l'autorizzazione bigquery.tables.export:

• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

Autorizzazioni per eseguire un job di esportazione

Per eseguire un job di esportazione, devi disporre dell'autorizzazione IAM bigquery.jobs.create.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per eseguire un job di esportazione:

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

Autorizzazioni per scrivere i dati nel bucket Cloud Storage

Per scrivere i dati in un bucket Cloud Storage esistente, devi disporre delle seguenti autorizzazioni IAM:

• storage.objects.create
• storage.objects.delete

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per la scrittura dei dati in un bucket Cloud Storage esistente:

• roles/storage.objectAdmin
• roles/storage.admin

Per ulteriori informazioni sulle autorizzazioni e sui ruoli IAM in BigQuery, consulta Autorizzazioni e ruoli predefiniti.

Considerazioni sulla località

Coordina i bucket Cloud Storage per l'esportazione dei dati:

• Se il set di dati BigQuery si trova in più regioni, EU il bucket Cloud Storage che contiene i dati esportati deve trovarsi nella stessa o in una località contenuta all'interno di quest'ultima. Ad esempio, se il set di dati BigQuery si trova nell'area geografica a più regioni EU, il bucket Cloud Storage può trovarsi nell'area geografica europe-west1 in Belgio, all'interno dell'UE.

  Se il tuo set di dati si trova nella regione con più regioni US, puoi esportare i dati in un bucket Cloud Storage in qualsiasi località.

• Se il set di dati si trova in una regione, il bucket Cloud Storage deve essere nella stessa regione. Ad esempio, se il set di dati si trova nella regione asia-northeast1 di Tokyo, il bucket Cloud Storage non può trovarsi nella regione con più regioni ASIA.

Sviluppa un piano di gestione dei dati:

• Se scegli una risorsa di archiviazione a livello di area geografica, come un set di dati BigQuery o un bucket Cloud Storage, sviluppa un piano per la gestione geografica dei dati.

Per ulteriori informazioni sulle località di Cloud Storage, consulta Località dei bucket nella documentazione di Cloud Storage.

Spostare i dati BigQuery tra località

Non puoi modificare la posizione di un set di dati dopo averlo creato, ma puoi crearne una copia. Non puoi spostare un set di dati da una posizione all'altra, ma puoi spostare (ricreare) manualmente un set di dati.

Esporta formati e tipi di compressione

BigQuery supporta i seguenti formati di dati e tipi di compressione per i dati esportati.

Formato dei dati	Tipi di compressione supportati	Dettagli
CSV	GZIP	Puoi controllare il delimitatore CSV nei tuoi dati esportati utilizzando il --field_delimiter bq flag dello strumento a riga di comando o la configuration.extract.fieldDelimiter proprietà del job di estrazione. I dati nidificati e ripetuti non sono supportati.
JSON	GZIP	Sono supportati dati nidificati e ripetuti.
Avro	DEFLATE, SNAPPY (DEFLATE)	GZIP non è supportato per le esportazioni Avro. Sono supportati dati nidificati e ripetuti. Consulta i dettagli dell'esportazione in Avro.
Parquet	SNAPPY, GZIP, ZSTD	Sono supportati dati nidificati e ripetuti. Vedi Dettagli dell'esportazione del gruppo.

Esportazione dei dati archiviati in BigQuery

Per esportare i dati della tabella:

• Utilizzo della console Google Cloud
• Utilizzare il comando bq extract nello strumento a riga di comando bq.
• Invio di un job extract tramite l'API o le librerie client

Esportazione dei dati delle tabelle

Per esportare i dati da una tabella BigQuery:

Console

1. Apri la pagina BigQuery nella console Google Cloud.

   Vai alla pagina BigQuery

2. Nel riquadro Explorer, espandi il progetto e il set di dati, poi seleziona la tabella.

3. Nel riquadro dei dettagli, fai clic su Esporta e seleziona Esporta in Cloud Storage.

4. Nella finestra di dialogo Esporta tabella in Google Cloud Storage:

   • In Seleziona il percorso di Google Cloud Storage, cerca il bucket, la cartella o il file in cui vuoi esportare i dati.
   • In Formato di esportazione, scegli il formato per i dati esportati: CSV, JSON (Newline Delimited), Avro o Parquet.
   • Per Compressione, seleziona un formato di compressione oppure seleziona None per evitare compressione.
   • Fai clic su Esporta per esportare la tabella.

Per verificare l'avanzamento del job, cerca un job Esporta nella parte superiore della navigazione per Cronologia job.

SQL

Utilizza l'istruzione EXPORT DATA. L'esempio seguente esporta i campi selezionati da una tabella denominata mydataset.table1:

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

   Vai a BigQuery

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

   EXPORT DATA
     OPTIONS (
       uri = 'gs://bucket/folder/*.csv',
       format = 'CSV',
       overwrite = true,
       header = true,
       field_delimiter = ';')
   AS (
     SELECT field1, field2
     FROM mydataset.table1
     ORDER BY field1
   );
   

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Esecuzione di query interattive.

bq

Utilizzare il comando bq extract con il flag --destination_format.

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

Altri flag facoltativi includono:

• --compression: il tipo di compressione da utilizzare per i file esportati.
• --field_delimiter: il carattere che indica il confine tra le colonne nel file di output per le esportazioni CSV. Sia \t sia tab sono consentiti per i delimitatori di scheda.
• --print_header: se specificato, stampa le righe di intestazione per i formati che hanno intestazioni come CSV.

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

Dove:

• location è il nome della tua località. 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 è il formato dei dati esportati: CSV, NEWLINE_DELIMITED_JSON, AVRO o PARQUET.
• compression_type è un tipo di compressione supportato per il tuo formato dei dati. Vedi Esportare formati e tipi di compressione.
• delimiter è il carattere che indica il confine tra le colonne nelle esportazioni CSV. \t e tab sono nomi accettati per la scheda.
• boolean è true o false. Se è impostata su true, le righe di intestazione vengono stampate sui dati esportati se il formato dei dati supporta le intestazioni. Il valore predefinito è true.
• project_id è l'ID progetto.
• dataset è il nome del set di dati di origine.
• table è la tabella che stai esportando.
• bucket è il nome del bucket Cloud Storage in cui stai esportando i dati. Il set di dati BigQuery e il bucket Cloud Storage devono essere nella stessa località.
• filename.ext è il nome e l'estensione del file di dati esportato. Puoi esportare i dati in più file utilizzando un carattere jolly.

Esempi:

Ad esempio, il seguente comando esporta mydataset.mytable in un file compresso con gzip denominato myfile.csv. myfile.csv è archiviato in un bucket Cloud Storage denominato example-bucket.

bq extract \
--compression GZIP \
'mydataset.mytable' \
gs://example-bucket/myfile.csv

Il formato di destinazione predefinito è CSV. Per esportare in formato JSON o Avro, utilizza il flag destination_format e impostalo su NEWLINE_DELIMITED_JSON o AVRO. Ad esempio:

bq extract \
--destination_format NEWLINE_DELIMITED_JSON \
'mydataset.mytable' \
gs://example-bucket/myfile.json

Il comando seguente esporta mydataset.mytable in un file Avro compresso con Snappy. Il nome del file è myfile.avro. myfile.avro viene esportato in un bucket Cloud Storage denominato example-bucket.

bq extract \
--destination_format AVRO \
--compression SNAPPY \
'mydataset.mytable' \
gs://example-bucket/myfile.avro

API

Per esportare i dati, crea un job extract e completa la configurazione del job.

Nota: se esporti i dati nel formato Parquet, potrebbe essere più rapido utilizzare il modello di esportazione BigQuery in Parquet (tramite l'API BigQuery Storage) anziché scrivere una soluzione personalizzata.

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

1. Creare un job di estrazione che punta ai dati di origine BigQuery e alla destinazione Cloud Storage.

2. Specifica la tabella di origine utilizzando l'oggetto di configurazione sourceTable contenente l'ID progetto, l'ID set di dati e l'ID tabella.

3. La proprietà destination URI(s) deve essere completa e nel formato gs://bucket/filename.ext. Ogni URI può contenere un carattere jolly "*" e deve essere inserito dopo il nome del bucket.

4. Specifica il formato dei dati impostando la proprietà configuration.extract.destinationFormat. Ad esempio, per esportare un file JSON, imposta questa proprietà con il valore NEWLINE_DELIMITED_JSON.

5. Per controllare lo stato del job, chiama jobs.get(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 includerà informazioni che descrivono cosa non ha funzionato.
   • Se status.errorResult non è presente, il job è stato completato correttamente, anche se potrebbero essersi verificati alcuni errori non irreversibili. Gli errori non irreversibili sono elencati nella proprietà status.errors dell'oggetto job restituito.

Note API:

• Come best practice, genera un ID univoco e passalo come jobReference.jobId quando chiami jobs.insert per creare un job. 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; in altre parole, puoi riprovare tutte le volte che vuoi con lo stesso ID job e al massimo una di queste operazioni avrà esito positivo.

C#

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

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

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

public class BigQueryExtractTable
{
    public void ExtractTable(
        string projectId = "your-project-id",
        string bucketName = "your-bucket-name")
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Define a destination URI. Use a single wildcard URI if you think
        // your exported data will be larger than the 1 GB maximum value.
        string destinationUri = $"gs://{bucketName}/shakespeare-*.csv";
        BigQueryJob job = client.CreateExtractJob(
            projectId: "bigquery-public-data",
            datasetId: "samples",
            tableId: "shakespeare",
            destinationUri: destinationUri
        );
        job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        Console.Write($"Exported table to {destinationUri}.");
    }
}

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API GoBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as CSV.
func exportTableAsCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.FieldDelimiter = ","

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API JavaBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

import com.google.cloud.RetryOption;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import org.threeten.bp.Duration;

public class ExtractTableToCsv {

  public static void runExtractTableToCsv() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    String bucketName = "my-bucket";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html

    String dataFormat = "CSV";
    extractTableToCsv(projectId, datasetName, tableName, destinationUri, dataFormat);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToCsv(
      String projectId,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat) {
    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(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);

      Job job = table.extract(dataFormat, destinationUri);

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob =
          job.waitFor(
              RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
              RetryOption.totalTimeout(Duration.ofMinutes(3)));
      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 extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println(
          "Table export successful. Check in GCS bucket for the " + dataFormat + " file.");
    } 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 di configurazione di Node.js nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API Node.jsBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

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

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableToGCS() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as raw CSV.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
  };

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

  console.log(`Job ${job.id} created.`);

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

PHP

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API PHPBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $bigQuery = new BigQueryClient([
      'projectId' => $projectId,
    ]);
    $dataset = $bigQuery->dataset($datasetId);
    $table = $dataset->table($tableId);
    $destinationUri = "gs://{$bucketName}/{$tableId}.json";
    // Define the format to use. If the format is not specified, 'CSV' will be used.
    $format = 'NEWLINE_DELIMITED_JSON';
    // Create the extract job
    $extractConfig = $table->extract($destinationUri)->destinationFormat($format);
    // Run the job
    $job = $table->runJob($extractConfig);  // Waits for the job to complete
    printf('Exported %s to %s' . PHP_EOL, $table->id(), $destinationUri);
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API PythonBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Ruby

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API RubyBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

require "google/cloud/bigquery"

def extract_table bucket_name = "my-bucket",
                  dataset_id  = "my_dataset_id",
                  table_id    = "my_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table    table_id

  # Define a destination URI. Use a single wildcard URI if you think
  # your exported data will be larger than the 1 GB maximum value.
  destination_uri = "gs://#{bucket_name}/output-*.csv"

  extract_job = table.extract_job destination_uri do |config|
    # Location must match that of the source table.
    config.location = "US"
  end
  extract_job.wait_until_done! # Waits for the job to complete

  puts "Exported #{table.id} to #{destination_uri}"
end

Dettagli esportazione Avro

BigQuery esprime i dati in formato Avro nei seguenti modi:

• I file di esportazione generati sono file contenitore Avro.
• Ogni riga BigQuery è rappresentata da un record Avro. I dati nidificati sono rappresentati da oggetti di record nidificati.
• I campi REQUIRED sono rappresentati dai tipi Avro corrispondenti. Ad esempio, un tipo INTEGER di BigQuery viene mappato a un tipo LONG Avro.
• I campi NULLABLE sono rappresentati come un'unione Avro del tipo corrispondente e "null".
• I campi REPEATED sono rappresentati come array Avro.
• Per impostazione predefinita, i tipi di dati TIMESTAMP sono rappresentati come tipo logico timestamp-micros (annota un tipo Avro LONG) sia nei job di estrazione che nell'esportazione dei dati SQL. (Attenzione: puoi aggiungere use_avro_logical_types=False a Export Data Options per disabilitare il tipo logico in modo che utilizzi il tipo string invece nella colonna timestamp, ma in Estrai job utilizza sempre il tipo logico Avro.)
• Per impostazione predefinita, i tipi di dati DATE sono rappresentati come tipo logico date (annota un tipo di Avro INT) in Esporta dati SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. (Nota: puoi aggiungere use_avro_logical_types=False a Export Data Options per disabilitare il tipo logico o utilizzare il flag --use_avro_logical_types=True per abilitare il tipo logico nei job di estrazione.)
• I tipi di dati TIME sono rappresentati per impostazione predefinita come tipo logico timestamp-micro (annota un tipo Avro LONG) in Esporta dati SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. Nota: puoi aggiungere use_avro_logical_types=False a Export Data Options per disabilitare il tipo logico o utilizzare il flag --use_avro_logical_types=True per abilitare il tipo logico nei job di estrazione.
• Per impostazione predefinita, i tipi di dati DATETIME sono rappresentati come tipi Avro STRING (un tipo di stringa con tipo logico denominato datetime) in Esporta dati SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. Nota: puoi aggiungere use_avro_logical_types=False a Export Data Options per disabilitare il tipo logico o utilizzare il flag --use_avro_logical_types=True per abilitare il tipo logico nei job di estrazione.

L'esportazione dei dati Avro non supporta i nomi di colonne flessibili.

Nota: la codifica del tipo di stringa segue la specifica RFC 3339 di Internet Engineering Task Force.

I tipi di dati con parametri NUMERIC(P[, S]) e BIGNUMERIC(P[, S]) trasferiti trasferiscono i relativi parametri di precisione e tipo di scala al tipo logico decimale Avro.

Attenzione:

• Se esporti un tipo di DATETIME in Avro, non puoi caricare il file Avro direttamente nello stesso schema della tabella, perché il valore STRING convertito non corrisponde allo schema. Come soluzione alternativa, carica il file in una tabella temporanea. Utilizza quindi una query SQL per trasmettere il campo a un tipo DATETIME e salvare il risultato in una nuova tabella. Per ulteriori informazioni, consulta la sezione Modificare il tipo di dati di una colonna .
• Una volta specificata, l'opzione di esportazione dei dati use_avro_logical_types e l'estrazione del flag Job --use_avro_logical_types vengono applicate a tutti i tipi logici contemporaneamente.

Il formato Avro non può essere utilizzato in combinazione con la compressione GZIP. Per comprimere i dati Avro, utilizza lo strumento a riga di comando bq o l'API e specifica uno dei tipi di compressione supportati per i dati Avro: DEFLATE o SNAPPY.

Dettagli esportazione Parquet

BigQuery converte i tipi di dati GoogleSQL nei seguenti tipi di dati di Parquet:

Tipo di dati BigQuery	Tipo primitivo del Parquet	Tipo logico Parquet
Numero intero	INT64	NONE
Numerico	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 38, scale = 9)
Numerico(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
Numerica grande	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 76, scale = 38)
BigNumc(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
Virgola mobile	FLOAT	NONE
Booleano	BOOLEAN	NONE
Stringa	BYTE_ARRAY	STRING (UTF8)
Byte	BYTE_ARRAY	NONE
Data	INT32	DATE
Data/ora	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Ora	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
Timestamp	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

Lo schema Parquet rappresenta i dati nidificati come gruppo e i record ripetuti come gruppi ripetuti. Per ulteriori informazioni sull'utilizzo di dati nidificati e ripetuti in BigQuery, consulta Specificare le colonne nidificate e ripetute.

Attenzione: se esporti un tipo DATETIME in Parquet, non puoi caricare nuovamente il file di Parquet nello stesso schema di tabella, perché il valore convertito non corrisponderà allo schema.

Puoi utilizzare le seguenti soluzioni alternative per i tipi DATETIME:

• Caricare il file in una tabella temporanea. quindi usa una query SQL per trasmettere il campo a un DATETIME e salvare il risultato in una nuova tabella. Per ulteriori informazioni, consulta la sezione Modificare il tipo di dati di una colonna.
• Fornisci uno schema per la tabella utilizzando il flag --schema nel job di caricamento. Definisci la colonna data/ora come col:DATETIME.

Esportazione dei dati in uno o più file

La proprietà destinationUris indica una o più posizioni e nomi file in cui BigQuery deve esportare i file.

BigQuery supporta un singolo operatore con carattere jolly (*) in ogni URI. Il carattere jolly può apparire ovunque nell'URI, tranne che come parte del nome del bucket. L'uso dell'operatore carattere jolly indica a BigQuery di creare più file sottoposti a durezza in base al pattern fornito. L'operatore carattere jolly viene sostituito con un numero (che inizia da 0), con spaziatura a sinistra di 12 cifre. Ad esempio, un URI con un carattere jolly alla fine del nome file creerebbe file con l'aggiunta di 000000000000 al primo file, l'aggiunta di 000000000001 al secondo file e così via.

La seguente tabella descrive diverse opzioni per la proprietà destinationUris:

destinationUris opzioni
URI singolo	Utilizza un singolo URI se stai esportando dati di tabelle di massimo 1 GB. Questa è il caso d'uso più comune, in quanto i dati esportati sono generalmente inferiori al valore massimo di 1 GB. Definizione della proprietà: ['gs://my-bucket/file-name.json'] Crea: gs://my-bucket/file-name.json
URI singolo carattere jolly	Utilizza un singolo URI con carattere jolly se ritieni che i dati esportati siano superiori al valore massimo di 1 GB. BigQuery esegue lo sharding dei tuoi dati in più file in base al pattern fornito. Le dimensioni dei file esportati variano. Se utilizzi un carattere jolly in un componente URI diverso dal nome file, assicurati che il componente del percorso non esista prima di esportare i dati. Definizione della proprietà: ['gs://my-bucket/file-name-*.json'] Crea: gs://my-bucket/file-name-000000000000.json gs://my-bucket/file-name-000000000001.json gs://my-bucket/file-name-000000000002.json ...

Limitare le dimensioni del file esportato

Quando esporti più di 1 GB di dati in una singola esportazione, devi utilizzare un carattere jolly per esportare i dati in più file e le dimensioni dei file variano. Se devi limitare le dimensioni massime di ogni file esportato, un'opzione è eseguire il partizionamento casuale dei dati ed esportare ogni partizione in un file:

1. Stabilisci il numero di partizioni di cui hai bisogno, che equivale alla dimensione totale dei tuoi dati diviso per le dimensioni del file esportate desiderate. Ad esempio, se hai 8000 MB di dati e vuoi che ogni file esportato abbia una dimensione di circa 20 MB, sono necessarie 400 partizioni.

2. Crea una nuova tabella partizionata e sottoposta a cluster da una nuova colonna generata casualmente chiamata export_id. L'esempio seguente mostra come creare un nuovo elemento processed_table da una tabella esistente denominata source_table, che richiede le partizioni n per raggiungere le dimensioni del file desiderate:

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );
   

3. Per ogni numero i compreso tra 0 e n-1, esegui un'istruzione EXPORT DATA per la query seguente:

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;
   

Estrai la tabella compressa

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API GoBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as compressed CSV.
func exportTableAsCompressedCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsURI := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.Compression = bigquery.Gzip

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API JavaBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

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

// Sample to extract a compressed table
public class ExtractTableCompressed {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "MY_PROJECT_NAME";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    String compressed = "gzip";
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
    String dataFormat = "CSV";

    extractTableCompressed(
        projectName, datasetName, tableName, destinationUri, dataFormat, compressed);
  }

  public static void extractTableCompressed(
      String projectName,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat,
      String compressed) {
    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(projectName, datasetName, tableName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(tableId, destinationUri)
              .setCompression(compressed)
              .setFormat(dataFormat)
              .build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this 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 extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table extract compressed successful");
    } 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 di configurazione di Node.js nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API Node.jsBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

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

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableCompressed() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as a compressed file.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
    gzip: true,
  };

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

  console.log(`Job ${job.id} created.`);

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

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento per le API PythonBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Visualizza su GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv.gz")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table("shakespeare")
job_config = bigquery.job.ExtractJobConfig()
job_config.compression = bigquery.Compression.GZIP

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
    job_config=job_config,
)  # API request
extract_job.result()  # Waits for job to complete.

Criteri per le quote

Per informazioni sulle quote dei job di esportazione, consulta la pagina Esportazione dei job nella pagina Quote e limiti.

Visualizza l'utilizzo della quota attuale

Puoi visualizzare l'utilizzo attuale di query, caricamento, estrazione o copia di job eseguendo una query INFORMATION_SCHEMA per visualizzare i metadati sui job eseguiti in un periodo di tempo specificato. Puoi confrontare l'utilizzo attuale con il limite di quota per determinare l'utilizzo della quota per un particolare tipo di job. La seguente query di esempio utilizza la visualizzazione INFORMATION_SCHEMA.JOBS per elencare il numero di job di query, caricamento, estrazione e copia per progetto:

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Puoi configurare un criterio di avviso Cloud Monitoring che fornisce notifiche sul numero di byte esportati.

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

   Vai a Monitoring

2. Nel riquadro di navigazione, seleziona Metrics Explorer.

3. Nell'editor di query MQL, configura un avviso per monitorare i byte esportati al giorno, come nell'esempio seguente:

   fetch consumer_quota
     | filter resource.service == 'bigquery.googleapis.com'
     | { metric serviceruntime.googleapis.com/quota/rate/net_usage
         | align delta_gauge(1m)
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sum(value.net_usage)
       ; metric serviceruntime.googleapis.com/quota/limit
         | filter metric.limit_name == 'ExtractBytesPerDay'
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sliding(1m), max(val()) }
     | ratio
     | every 1m
     | condition gt(val(), 0.01 '1')
   

4. Per configurare l'avviso, fai clic su Esegui query.

Per ulteriori informazioni, vedi Criteri di avviso con MQL .

Prezzi

Non è previsto alcun costo per esportare i dati da BigQuery. Se utilizzi l'istruzione EXPORT DATA, ti sarà addebitato un costo per la query SELECT. Per ulteriori informazioni sui prezzi di BigQuery, consulta la pagina Prezzi.

Una volta esportati i dati, ti sono addebitati i costi per l'archiviazione dei dati in Cloud Storage. Per ulteriori informazioni sui prezzi di Cloud Storage, consulta la pagina Prezzi di Cloud Storage.

Sicurezza delle tabelle

Per controllare l'accesso alle tabelle in BigQuery, consulta Introduzione ai controlli di accesso alle tabelle.

Passaggi successivi

• Per scoprire di più sulla console Google Cloud, consulta Utilizzo della console Google Cloud.
• Per scoprire di più sullo strumento a riga di comando bq, consulta Utilizzo dello strumento a riga di comando bq.
• Per informazioni su come creare un'applicazione utilizzando le librerie client dell'API BigQuery, consulta la guida rapida alla libreria client.