Esporta i dati della tabella in Cloud Storage

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

Dopo aver caricato i tuoi dati BigQuery, puoi esportare i dati in diversi formati. BigQuery può esportare fino a 1 GB di dati in un un singolo file. Se esporti più di 1 GB di dati, devi esportare in più file. Quando esportare 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'uso di Dataflow per leggere e scrivere BigQuery, consulta BigQuery I/O nella documentazione di Apache Beam.

Puoi anche esportare i risultati di una query utilizzando EXPORT DATA l'Informativa. Puoi utilizzare EXPORT DATA OPTIONS per esportare le viste in Cloud Storage.

Limitazioni per l'esportazione

Quando esporti i dati da BigQuery, tieni presente quanto segue:

• Non puoi esportare i dati delle tabelle in un file locale, in Fogli Google o in Google Drive. L'unica posizione di esportazione supportata è Cloud Storage. Per informazioni sul salvataggio dei risultati delle query, consulta Download e salvataggio dei risultati delle query.
• Puoi esportare fino a 1 GB di dati di una tabella in un singolo file. Se esportare più di 1 GB di dati, utilizza un carattere jolly per esportare i dati in più file. Quando esporti i dati in più zone, file, le loro dimensioni variano. A limita le dimensioni del file esportato, puoi partizionare i dati ed esportare ogni partizione.
• Le dimensioni del file generato quando si utilizza l'istruzione EXPORT DATA non sono garantite.
• Il numero di file generati da un job di esportazione può variare.
• Non puoi esportare dati nidificati e ripetuti in formato CSV. Nidificati e ripetuti sono supportati per le esportazioni Avro, JSON e Parquet.
• Quando esporti i dati in JSON, INT64 i tipi di dati (numero intero) sono codificati come stringhe JSON per preservare la precisione a 64 bit quando i dati vengono letti da altri sistemi.
• Non puoi esportare 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 una conservazione , BigQuery potrebbe non riuscire a scrivere i file nel bucket. Configura il periodo di conservazione in modo che sia più lungo di 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 della tabella esportati non è garantito a meno che non utilizzi il metodo EXPORT DATA e specificare una clausola ORDER BY nell'istruzione query_statement.
• BigQuery non supporta i percorsi delle risorse di Cloud Storage che includono più barre consecutive dopo la doppia barra iniziale. I nomi degli oggetti Cloud Storage possono contenere più barre consecutive ("/"). Tuttavia, BigQuery converte più barre consecutive in una singola barra. Ad esempio, la seguente risorsa questo percorso, sebbene valido in Cloud Storage, non funziona in BigQuery: gs://bucket/my//object//name.
• Tutti i nuovi dati caricati in BigQuery durante un job di esportazione non saranno incluse nel job di esportazione. Devi creare un nuovo job di esportazione per esportare i nuovi dati.

Prima di iniziare

Concedi agli utenti i ruoli di Identity and Access Management (IAM) che offrono 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, è necessario Autorizzazione IAM bigquery.tables.export.

Ciascuno dei seguenti ruoli IAM predefiniti include 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 scrivere i dati in un bucket Cloud Storage esistente:

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

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

Considerazioni sulla località

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

• Se il set di dati BigQuery si trova nella località multiregionale EU, il bucket Cloud Storage contenenti i dati che esporti devono trovarsi nella stessa località multiregionale o in una località è contenuto all'interno di più regioni. Ad esempio, se il set di dati BigQuery è nella località multiregionale EU, il bucket Cloud Storage può trovarsi nella zona europe-west1 Regione del Belgio all'interno dell'UE.

  Se il set di dati si trova nella località multiregionale 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 trovarsi nella stessa regione. Per Ad esempio, se il set di dati si trova nella regione asia-northeast1 di Tokyo, i dati di Cloud Storage il bucket non può trovarsi nella località multiregionale ASIA.

Sviluppa un piano di gestione dei dati:

• Se scegli una risorsa di archiviazione regionale, ad esempio un set di dati BigQuery un bucket Cloud Storage, sviluppa un piano la gestione geografica dei tuoi dati.

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

Spostare i dati BigQuery tra località

Non puoi modificare la località di un set di dati dopo averlo creato, ma puoi crea una copia del set di dati. Non puoi spostare un set di dati da una località a un'altra, ma puoi spostare (ricreare) manualmente un set di dati.

Formati di esportazione e tipi di compressione

BigQuery supporta i seguenti formati dei 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 dati esportati utilizzando --field_delimiter il flag dello strumento a riga di comando bq configuration.extract.fieldDelimiter estrarre la proprietà del job. I dati nidificati e ripetuti non sono supportati.
JSON	GZIP	Sono supportati i dati nidificati e ripetuti.
Avro	SFOGGIA, FACCINA SEMPLICE	GZIP non è supportato per le esportazioni Avro. Sono supportati i dati nidificati e ripetuti. Consulta Dettagli dell'esportazione Avro.
Parquet	SNAPPY, GZIP, ZSTD	Sono supportati i dati nidificati e ripetuti. Consulta Dettagli dell'esportazione del Parquet.

Esporta i dati

Puoi esportare i dati delle tabelle per:

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

Esporta i dati della tabella

Per esportare i dati da una tabella BigQuery:

Console

1. Apri la pagina BigQuery nella console Google Cloud.

   Vai alla pagina di BigQuery

2. Nel riquadro Explorer, espandi il progetto e il set di dati, quindi seleziona nella tabella.

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

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

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

Per controllare l'avanzamento del job, guarda vicino alla parte superiore della Navigazione per Cronologia dei job per un job di Esporta.

Per esportare le viste in Cloud Storage, utilizza l'istruzione EXPORT DATA OPTIONS.

SQL

Utilizza la EXPORT DATA. L'esempio seguente consente di esportare 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 le query, vedi Eseguire una query interattiva.

bq

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

(Facoltativo) Fornisci il flag --location e imposta il valore su 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 nel file di output per le esportazioni CSV. Sono consentiti sia \t sia tab per i delimitatori di tabulazione.
• --print_header: se specificato, stampa le righe di intestazione per i formati con 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 sede. Il flag --location è facoltativo. Ad esempio, se utilizzi BigQuery Regione di Tokyo, puoi impostare il valore del flag su asia-northeast1. Puoi Imposta un valore predefinito per la località utilizzando il file.bigqueryrc.
• format è il formato per i dati esportati: CSV, NEWLINE_DELIMITED_JSON, AVRO o PARQUET.
• compression_type è un tipo di compressione supportato per i tuoi dati formato. Consulta l'articolo Esportare formati e tipi di compressione.
• delimiter è il carattere che indica il confine tra nelle esportazioni CSV. \t e tab sono nomi accettati per la scheda.
• boolean è true o false. Se impostato su true, le righe di intestazione vengono stampati nei dati esportati se il formato dei dati supporta le intestazioni. La il valore predefinito è true.
• project_id è l'ID progetto.
• dataset è il nome del set di dati di origine.
• table è la tabella che stai esportando. Se utilizzi un decoratore della partizione, il percorso della tabella deve essere racchiuso tra virgolette singole oppure l'interpretazione letterale del carattere $.
• bucket è il nome del bucket Cloud Storage a cui sei esportando i dati. Il set di dati BigQuery e Il bucket Cloud Storage deve trovarsi nella stessa località.
• filename.ext è il nome e l'estensione dei dati esportati . Puoi eseguire l'esportazione in più file utilizzando un carattere jolly.

Esempi:

Ad esempio, il seguente comando esporta mydataset.mytable in un file gzip file compresso 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 eseguire l'esportazione in JSON o Avro, utilizza destination_format e impostato su NEWLINE_DELIMITED_JSON o AVRO. Ad esempio:

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

Il seguente comando esporta mydataset.mytable in un file Avro che è compressi usando Snappy. Il file è denominato myfile.avro. myfile.avro è esportato in un bucket Cloud Storage denominato example-bucket.

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

Il comando seguente esporta una singola partizione mydataset.my_partitioned_table in un file CSV in Cloud Storage:

bq extract \
--destination_format CSV \
'mydataset.my_partitioned_table$0' \
gs://example-bucket/single_partition.csv

API

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

Nota: se esporti dati nel formato Parquet, potrebbe essere più veloce per utilizzare Esportazione di BigQuery in Parquet (tramite l'API BigQuery Storage) anziché scrivere una soluzione personalizzata.

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

1. Crea un job di estrazione che punti all'origine BigQuery e la destinazione Cloud Storage.

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

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

4. Specifica il formato dei dati impostando il parametro configuration.extract.destinationFormat proprietà. Ad esempio, per esportare un file JSON, imposta questa proprietà sul 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 è riuscita. e l'oggetto includerà informazioni che descrivono cosa non ha funzionato.
   • Se il campo status.errorResult non è presente, il job è stato completato correttamente. anche se potrebbero essersi verificati alcuni errori non irreversibili. Errori non irreversibili sono elencate 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 è più efficace per gli errori di rete perché il client può eseguire il polling o riprova sull'ID job noto.

• Chiamare jobs.insert su un determinato ID job è idempotente: in altre parole, puoi riprovare tutte le volte che vuoi per lo stesso ID job e al massimo una delle queste operazioni avranno esito positivo.

C#

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

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

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}.");
    }
}

Vai

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

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

import (
	"context"
	"fmt"

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

// 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 per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

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

import com.google.cloud.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 per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.

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

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

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 per la configurazione di PHP nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API PHP BigQuery documentazione di riferimento.

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

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 per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

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

# from google.cloud import bigquery
# 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 per la configurazione di Ruby nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Ruby BigQuery documentazione di riferimento.

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

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 formattati Avro nei seguenti modi:

• I file di esportazione risultanti sono file container Avro.
• Ogni riga di BigQuery è rappresentata come un record Avro. Nidificati sono rappresentati da oggetti di record nidificati.
• I campi REQUIRED sono rappresentati come tipi di Avro corrispondenti. Per Ad esempio, un tipo di BigQuery INTEGER viene mappato a un tipo Avro LONG.
• I campi NULLABLE sono rappresentati come un'unione Avro del tipo corrispondente e "null".
• I campi REPEATED sono rappresentati come array Avro.
• TIMESTAMP tipi di dati sono rappresentati come logici timestamp-micros (Annota un tipo LONG Avro) per impostazione predefinita sia nei job di estrazione che Esporta i 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 del timestamp, ma in Extract Jobs utilizza sempre tipo logico).
• DATE tipi di dati sono rappresentati come tipo logico date (aggiunge un'annotazione Avro INT) per impostazione predefinita in Esporta dati SQL, ma sono rappresentati come tipo string per impostazione predefinita in Estrai job. Nota: puoi aggiungere use_avro_logical_types=False a Export Data Options per disabilitare il tipo logico oppure usa il flag --use_avro_logical_types=True per abilitare il tipo logico in Estrai job.)
• TIME tipi di dati sono rappresentati come tipo logico timestamp-micro (it annota i tipi LONG di Avro) per impostazione predefinita in Export Data SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. Nota: puoi aggiungere Da use_avro_logical_types=False a Export Data Options per disattivare la logica o utilizza il flag --use_avro_logical_types=True per abilitare il tipo logico in Estrai job).
• DATETIME tipi di dati sono rappresentati come tipi di dati Avro STRING (un tipo di stringa) con tipo logico con nome personalizzato datetime) per impostazione predefinita in Esporta dati SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. Nota: puoi aggiungere Da use_avro_logical_types=False a Export Data Options per disattivare la logica o utilizza il flag --use_avro_logical_types=True per abilitare il tipo logico Estrai i job).

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

Trasferimento dei tipi di dati NUMERIC(P[, S]) e BIGNUMERIC(P[, S]) con parametri i loro parametri di precisione e scala al tipo logico decimale Avro.

Attenzione:

• Se esporti un tipo DATETIME in Avro, non puoi caricare l'Avro direttamente nello stesso schema della tabella, perché il valore STRING convertito non corrisponderà allo schema. Come soluzione alternativa, carica il file in una tabella temporanea. Quindi usa una query SQL per trasmettere il campo a un tipo DATETIME e salva il risultato in una nuova tabella. Per ulteriori informazioni, vedi Modifica del tipo di dati di una colonna .
• Opzione di esportazione dati use_avro_logical_types e flag di estrazione del job --use_avro_logical_types e applicate contemporaneamente a tutti i tipi logici,

Il formato Avro non può essere utilizzato in combinazione con la compressione GZIP. Per comprimere Per i dati Avro, usa 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 Parquet:

Tipo di dati BigQuery	Tipo primitivo 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)
BigNumeric	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 76, scale = 38)
BigNumeric(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 e gruppi ripetuti. Per ulteriori informazioni sull'utilizzo di dati nidificati e ripetuti in per BigQuery, consulta Specifica delle colonne nidificate e ripetute.

Attenzione: se esporti un tipo DATETIME in Parquet, non puoi caricare il del file Parquet direttamente nello stesso schema della tabella, perché lo schema convertito non corrisponderà allo schema.

Puoi utilizzare le seguenti soluzioni alternative per i tipi DATETIME:

• Carica il file in una tabella temporanea. Poi usa una query SQL per trasmettere il campo a DATETIME e salva il risultato in una nuova tabella. Per ulteriori informazioni, vedi 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 di dati in uno o più file

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

BigQuery supporta un singolo operatore di caratteri jolly (*) in ogni URI. La Il carattere jolly può essere visualizzato in qualsiasi punto dell'URI, ad eccezione del nome del bucket. Utilizzo l'operatore con caratteri jolly indica a BigQuery di creare più i file con sharding basso in base al pattern fornito. L'operatore carattere jolly viene sostituito con un numero (a partire da 0), riempito a sinistra fino a 12 cifre. Ad esempio, un URI con un carattere jolly alla fine del nome file creerebbe file con 000000000000 aggiunto al primo file, 000000000001 aggiunto al secondo file, e così via attiva.

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

Opzioni per destinationUris
URI singolo	Utilizza un singolo URI se esporti dati della tabella di 1 GB o meno risorse. Questa opzione è il caso d'uso più comune, in quanto i dati esportati sono generalmente inferiore al valore massimo di 1 GB. Questa opzione non è supportato per EXPORT DATA; devi utilizzare una singola l'URI con caratteri jolly. Definizione della proprietà: ['gs://my-bucket/file-name.json'] Crea: gs://my-bucket/file-name.json
URI con carattere jolly singolo	Utilizza un singolo URI con caratteri jolly se ritieni che i dati esportati verranno superiore al valore massimo di 1 GB. BigQuery esegue lo sharding in più file in base al pattern fornito. Le dimensioni i file esportati varieranno. Se utilizzi un carattere jolly in un componente URI diverso dal nome file, assicurati che il percorso non esiste prima dell'esportazione dei 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 una carattere jolly per esportare i dati in più file e le relative dimensioni varia. Se devi limitare la dimensione massima di ciascun file esportato, un'opzione consiste nel partizionare i dati in modo casuale e quindi esportare ogni partizione in un file:

1. Determina il numero di partizioni necessarie, che equivale al totale dimensione dei dati divisa per la dimensione del file esportato che vuoi ottenere. Ad esempio: se hai 8000 MB di dati e vuoi che ogni file esportato venga di circa 20 MB, quindi ti servono 400 partizioni.

2. Crea una nuova tabella partizionata e raggruppata in base a un nuovo colonna generata denominata export_id. L'esempio seguente mostra come crea un nuovo processed_table da una tabella esistente denominata source_table che richiede n partizioni per ottenere la dimensione di file desiderata:

   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 intero i compreso tra 0 e n-1, esegui un'istruzione EXPORT DATA per la seguente query:

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

Estrai tabella compressa

Go

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

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

import (
	"context"
	"fmt"

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

// 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 per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.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 per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.

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

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

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 per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

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

# from google.cloud import bigquery
# 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.

Caso d'uso di esempio

Questo esempio mostra come esportare i dati in Cloud Storage.

Supponi di inviare un flusso di dati a Cloud Storage dai log degli endpoint senza interruzioni. Uno snapshot giornaliero deve essere esportato in Cloud Storage per scopi di backup e archiviazione. La scelta migliore è estrazione job soggetto a determinati quotas e limitazioni.

Invia un job di estrazione con API o librerie client, passando un ID univoco come jobReference.jobId. I job di estrazione sono asincrone. Controllare lo stato del lavoro utilizzando l'ID job univoco usato per creare il job. Il job è stato completato se status.status è DONE. Se è presente status.errorResult, il job non è riuscito e deve essere riprovato.

Elaborazione dei dati in batch

Supponiamo che venga utilizzato un job batch notturno per caricare i dati entro una scadenza fissa. Al termine del job di caricamento, viene materializzata una tabella con le statistiche come descritto nella sezione precedente. I dati di questa tabella sono recuperate e compilate in un report in PDF e inviate a un ente regolatore.

Poiché la quantità di dati da leggere è ridotta, utilizza la tabledata.list per recuperare tutte le righe della tabella nel formato dizionario JSON. Se c'è più di una pagina di dati, i risultati hanno la proprietà pageToken per iniziare. Per recuperare la pagina successiva di risultati, effettua un'altra chiamata a tabledata.list e Includi il valore del token come parametro pageToken. Se la chiamata API non va a buon fine con un 5xx errore, e riprova con il backoff esponenziale. La maggior parte degli errori 4xx non può essere annullata. Per un migliore disaccoppiamento di BigQuery Export e la generazione di report, i risultati devono essere resi permanenti su disco.

Criteri per le quote

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

L'utilizzo per i job di esportazione è disponibile in INFORMATION_SCHEMA. La voce del job nelle tabelle di sistema JOBS_BY_* per il job di esportazione contiene un valore Valore total_processed_bytes che può essere utilizzato per monitorare l'utilizzo aggregato per garantire che rimanga al di sotto di 50 TB al giorno. Per scoprire come eseguire query sul INFORMATION_SCHEMA.JOBS visualizzazione per ottenere il valore total_processed_bytes, vedi Ottieni byte elaborati dai job di esportazione

Visualizza l'utilizzo attuale della quota

Puoi visualizzare l'utilizzo attuale dei job di query, caricamento, estrazione o copia eseguendo una query INFORMATION_SCHEMA per visualizzare i metadati relativi ai job eseguiti su un specificato per il periodo di tempo. Puoi confrontare il tuo utilizzo attuale con la quota per determinare l'utilizzo della quota per un particolare tipo di job. Le seguenti query di esempio utilizza la vista INFORMATION_SCHEMA.JOBS per elencare il numero esegui query, carica, estrai e copia i job in base al 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 di Cloud Monitoring che avvisa il numero di byte esportati.

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

   Vai a Monitoring

2. Nel riquadro di navigazione, seleziona Esplora metriche.

3. Nell'editor di query MQL, configura un avviso per monitorare i byte esportati al giorno, come illustrato 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 maggiori informazioni, consulta Criteri di avviso con MQL.

Risoluzione dei problemi

Per diagnosticare i problemi relativi ai job di estrazione, puoi utilizzare Esplora log per esaminare i log per uno specifico job di estrazione e identificare possibili errori. Il seguente filtro di Esplora log restituisce informazioni sul tuo di estrazione dei job:

resource.type="bigquery_resource"
protoPayload.methodName="jobservice.insert"
(protoPayload.serviceData.jobInsertRequest.resource.jobConfiguration.query.query=~"EXPORT" OR
protoPayload.serviceData.jobCompletedEvent.eventName="extract_job_completed" OR
protoPayload.serviceData.jobCompletedEvent.job.jobConfiguration.query.query=~"EXPORT")

Prezzi

Per informazioni sui prezzi dell'esportazione dei dati, consulta la pagina Prezzi di BigQuery.

Una volta esportati i dati, ti viene addebitato il costo per l'archiviazione dei dati di archiviazione ideale in Cloud Storage. Per ulteriori informazioni, consulta i prezzi di Cloud Storage.

Sicurezza dei tavoli

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

Passaggi successivi

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