Esporta i dati delle tabelle in Cloud Storage

Questa pagina descrive come esportare o estrarre i 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 unico file. Se esporti più di 1 GB di dati, devi esportarli in più file. Quando esporti i dati in più file, le dimensioni dei file variano.

Puoi anche esportare i risultati di una query utilizzando l'istruzione EXPORT DATA. Puoi utilizzare EXPORT DATA OPTIONS per specificare il formato dei dati esportati.

Infine, puoi utilizzare un servizio come Dataflow per leggere i dati da BigQuery anziché esportarli da BigLake. Per ulteriori informazioni sull'utilizzo di Dataflow per leggere e scrivere in BigQuery, consulta la documentazione di BigQuery I/O.

Limitazioni per l'esportazione

Quando esporti i 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 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 della tabella in un unico 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 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. 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 (integer) vengono 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 unico job di esportazione.
• Non puoi scegliere un tipo di compressione diverso da GZIP quando esporti i dati utilizzando la console Google Cloud .
• 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 l'istruzione EXPORT DATA e specifichi una clausola ORDER BY in query_statement.
• BigQuery non supporta i percorsi delle risorse Cloud Storage che includono più barre consecutive dopo la doppia barra iniziale. I nomi degli oggetti Cloud Storage possono contenere più caratteri barra ("/") consecutivi. Tuttavia, BigQuery converte più slash consecutivi in un unico slash. Ad esempio, il seguente percorso della risorsa, sebbene valido in Cloud Storage, non funziona in BigQuery: gs://bucket/my//object//name.
• I nuovi dati caricati in BigQuery durante l'esecuzione di un job di esportazione non verranno inclusi in questo job. Per esportare i nuovi dati, devi creare un nuovo job di esportazione.

Prima di iniziare

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

Autorizzazioni obbligatorie

Per eseguire le attività descritte 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 scrivere i dati in un bucket Cloud Storage esistente:

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

Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Formati di esportazione e tipi di compressione

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

Esporta i dati

Puoi esportare i dati della tabella:

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

Esportare i dati delle tabelle

Per esportare i dati da una tabella BigQuery:

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

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

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

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

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

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

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
}

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());
    }
  }
}

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

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

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

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

Esporta i metadati della tabella

Per esportare i metadati della tabella dalle tabelle Iceberg, utilizza la seguente istruzione SQL:

EXPORT TABLE METADATA FROM `[[PROJECT_NAME.]DATASET_NAME.]TABLE_NAME`;

Sostituisci quanto segue:

• PROJECT_NAME: il nome del progetto per la tabella. Il valore predefinito è il progetto che esegue questa query.
• DATASET_NAME: il nome del set di dati per la tabella.
• TABLE_NAME: il nome della tabella.

I metadati esportati si trovano nella cartella STORAGE_URI/metadata, dove STORAGE_URI è la posizione di archiviazione della tabella impostata nelle opzioni.

Dettagli esportazione Avro

BigQuery esprime i dati formattati in Avro nei seguenti modi:

• I file di esportazione risultanti sono file contenitore Avro.
• Ogni riga BigQuery è rappresentata come un record Avro. I dati nidificati sono rappresentati da oggetti record nidificati.
• I campi REQUIRED sono rappresentati come i tipi Avro corrispondenti. Ad esempio, un tipo INTEGER 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.
• I tipi di dati TIMESTAMP sono rappresentati come tipo logico timestamp-micros (annotano un tipo Avro LONG) per impostazione predefinita sia nei job di estrazione sia in Export Data SQL. (Attenzione: puoi aggiungere use_avro_logical_types=False a Export Data Options per disattivare il tipo logico in modo che utilizzi il tipo string invece nella colonna del timestamp, ma nei job di estrazione utilizza sempre il tipo logico Avro.)
• I tipi di dati DATE sono rappresentati come tipo logico date (annotano i tipi Avro INT) per impostazione predefinita in Export Data 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 disattivare il tipo logico oppure utilizzare il flag --use_avro_logical_types=True per attivare il tipo logico nei job di estrazione.)
• I tipi di dati TIME sono rappresentati come tipo logico timestamp-micro (annotano i tipi Avro LONG) per impostazione predefinita in Export Data 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 disattivare il tipo logico o utilizzare il flag --use_avro_logical_types=True per attivare il tipo logico nei job di estrazione.)
• I tipi di dati DATETIME sono rappresentati come tipi Avro STRING (un tipo stringa con tipo logico denominato personalizzato datetime) per impostazione predefinita in Export Data 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 disattivare il tipo logico o utilizzare il flag --use_avro_logical_types=True per attivare il tipo logico nei job di estrazione.)
• I tipi RANGE non sono supportati nell'esportazione Avro.

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

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 Parquet:

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

Puoi utilizzare le seguenti soluzioni alternative per i tipi di DATETIME:

• Carica il file in una tabella di staging. Poi utilizza una query SQL per eseguire il cast del campo in un DATETIME e salva il risultato in una nuova tabella. Per saperne di più, consulta 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.

Il tipo logico GEOGRAPHY è rappresentato dai metadati GeoParquet aggiunti ai file esportati.

Esportazione di dati in uno o più file

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

BigQuery supporta un singolo operatore jolly (*) in ogni URI. Il carattere jolly può essere visualizzato in qualsiasi punto del componente del nome file. L'utilizzo dell'operatore jolly indica a BigQuery di creare più file suddivisi in shard in base al pattern fornito. L'operatore jolly viene sostituito con un numero (a partire da 0), con riempimento a sinistra fino a 12 cifre. Ad esempio, un URI con un carattere jolly alla fine del nome file creerebbe file con000000000000 aggiunto al primo file e 000000000001 aggiunto al secondo file, continuando con questo pattern.

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

gs://my-bucket/file-name.json

gs://my-bucket/file-name-000000000000.json
gs://my-bucket/file-name-000000000001.json
gs://my-bucket/file-name-000000000002.json
...

gs://my-bucket/000000000000
gs://my-bucket/000000000001
gs://my-bucket/000000000002
...

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 è partizionare i dati in modo casuale ed esportare ogni partizione in un file:

1. Determina il numero di partizioni necessarie, che è uguale alla dimensione totale dei dati divisa per la dimensione del file esportato scelta. Ad esempio, se hai 8000 MB di dati e vuoi che ogni file esportato sia di circa 20 MB, ti servono 400 partizioni.

2. Crea una nuova tabella partizionata e raggruppata in cluster in base a una nuova colonna generata casualmente denominata export_id. L'esempio seguente mostra come creare un nuovo processed_table da una tabella esistente denominata source_table che richiede n partizioni per raggiungere la dimensione del file scelta:

   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 nella seguente query:

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

Estrai tabella compressa

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
}

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());
    }
  }
}

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

# 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.

Supponiamo che tu stia trasmettendo in streaming i dati a Cloud Storage dai log degli endpoint in modo continuo. Uno snapshot giornaliero deve essere esportato in Cloud Storage per scopi di backup e archiviazione. La scelta migliore è un job di estrazione soggetto a determinate quote e limitazioni.

Invia un job di estrazione con l'API o le librerie client, passando un ID univoco come jobReference.jobId. I job di estrazione sono asincroni. Controlla lo stato del job utilizzando l'ID univoco del job utilizzato per crearlo. Il job è stato completato correttamente se status.status è DONE. Se è presente status.errorResult, il job non è riuscito e deve essere ritentato.

Elaborazione dei dati in batch

Supponiamo che un job batch notturno venga utilizzato per caricare i dati entro una scadenza fissa. Al termine di questo job di caricamento, una tabella con statistiche viene materializzata da una query come descritto nella sezione precedente. I dati di questa tabella vengono recuperati e compilati in un report PDF e inviati a un ente regolatore.

Poiché la quantità di dati da leggere è ridotta, utilizza l'API tabledata.list per recuperare tutte le righe della tabella in formato dizionario JSON. Se sono presenti più pagine di dati, i risultati hanno la proprietà pageToken impostata. Per recuperare la pagina successiva di risultati, effettua un'altra chiamata tabledata.list e includi il valore del token come parametro pageToken. Se la chiamata API non va a buon fine e genera un errore 5xx, riprova con backoff esponenziale. Non è possibile riprovare a risolvere la maggior parte degli errori 4xx. Per un migliore disaccoppiamento dell'esportazione BigQuery e della generazione di report, i risultati devono essere salvati su disco.

Criteri per le quote

Per informazioni sulle quote dei job di esportazione, vedi 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 total_bytes_processed che può essere utilizzato per monitorare l'utilizzo aggregato per garantire che rimanga al di sotto di 50 TiB al giorno. Per scoprire come eseguire query sulla visualizzazione INFORMATION_SCHEMA.JOBS per ottenere il valore total_bytes_processed, consulta lo schema INFORMATION_SCHEMA.JOBS.

Visualizzare 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 in un periodo di tempo specificato. Puoi confrontare l'utilizzo corrente con il limite di quota per determinare l'utilizzo della quota per un particolare tipo di job. La seguente query di esempio utilizza la vista 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-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Puoi configurare un criterio di avviso di Cloud Monitoring che fornisce una notifica del 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 delle query MQL, configura un avviso per monitorare i byte esportati al giorno, come mostrato 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 Logs Explorer per esaminare i log di un job di estrazione specifico e identificare i possibili errori. Il seguente filtro di Esplora log restituisce informazioni sui job di estrazione:

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 di archiviazione dei dati in Cloud Storage. Per maggiori informazioni, consulta Prezzi di Cloud Storage.

Sicurezza delle tabelle

Per controllare l'accesso alle tabelle in BigQuery, vedi Controllare l'accesso alle risorse con IAM.

Passaggi successivi

• Per scoprire 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 alla libreria client.