Esporta i dati delle tabelle in Cloud Storage

Puoi esportare i dati delle tabelle BigQuery in Cloud Storage in formato CSV, JSON, Avro o Parquet per il backup, l'archiviazione o l'elaborazione in altri strumenti. Dopo aver caricato i dati in BigQuery, puoi esportarli utilizzando la console Google Cloud , lo strumento a riga di comando bq, l'API, le librerie client o metodi di esportazione alternativi.

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 su Google Drive. L'unica località 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 logica 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 partizionare i dati ed esportare ogni partizione. Per ulteriori informazioni e suggerimenti sull'esportazione di tabelle di grandi dimensioni, consulta Considerazioni sull'esportazione di tabelle di grandi dimensioni.
  • Le dimensioni del file generato quando utilizzi l'istruzione EXPORT DATA non sono garantite.
  • Il numero di file generati da un job di estrazione 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 (numero intero) 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 singolo job di estrazione.
  • 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 esportata non è garantito, a meno che non utilizzi l'istruzione EXPORT DATA e specifichi una clausola ORDER BY in query_statement. Quando esporti in più file, la sequenza ordinata viene conservata a livello globale in tutti i file generati.
  • 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ù barre consecutive in una singola barra. 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 estrazione non verranno inclusi nel job di estrazione. Devi creare un nuovo job di estrazione per esportare i nuovi dati.
  • Il numero di generazione di Cloud Storage potrebbe cambiare una o più volte durante il processo di esportazione. Se esegui un job sul nuovo oggetto Cloud Storage immediatamente dopo l'esportazione, non specificare un numero di generazione.

Prima di iniziare

Concedi i ruoli di Identity and Access Management (IAM) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività 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 estrazione

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

Ognuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per eseguire un job di estrazione:

  • 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 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 il flag dello strumento a riga di comando bq --field_delimiter o la proprietà del job di estrazione configuration.extract.fieldDelimiter.

I dati nidificati e ripetuti non sono supportati.
JSON GZIP I dati nidificati e ripetuti sono supportati.
Avro DEFLATE, SNAPPY

GZIP non è supportato per le esportazioni Avro.

I dati nidificati e ripetuti sono supportati. Consulta i dettagli sull'esportazione Avro.
Parquet SNAPPY, GZIP, ZSTD

I dati nidificati e ripetuti sono supportati. Consulta i dettagli sull'esportazione in Parquet.

Esporta i dati

Le sezioni seguenti mostrano come esportare i dati delle tabelle, i metadati delle tabelle e i risultati delle query in Cloud Storage.

Esporta i dati della tabella

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

Seleziona una delle seguenti opzioni:

Console

  1. Apri la pagina BigQuery nella console Google Cloud .

    Vai alla pagina BigQuery

  2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

    Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

  3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati, quindi sul set di dati.

  4. Fai clic su Panoramica > Tabelle, quindi seleziona una tabella.

  5. Nel riquadro dei dettagli, fai clic su upload Esporta / sincronizza > Cloud Storage.

  6. Nella finestra di dialogo Esporta in Google Cloud Storage:

    • In Posizione GCS, 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 (delimitato da nuova riga), Avro o Parquet.
    • In Compressione, seleziona un formato di compressione o seleziona None per nessuna compressione.

  7. Fai clic su Salva per esportare la tabella.

Per controllare l'avanzamento del job, nel riquadro Explorer, fai clic su Cronologia dei job e cerca un job di tipo EXTRACT.

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

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 di 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 saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

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

(Facoltativo) Specifica 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. Per i delimitatori di tabulazione sono consentiti sia \t sia tab.
  • --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 formato dei dati. Consulta Formati di esportazione 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 impostato su true, le righe di intestazione vengono stampate nei 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. Se utilizzi un decoratore di partizione, devi racchiudere il percorso della tabella tra virgolette singole o eseguire l'escape del carattere $.
  • bucket è il nome del bucket Cloud Storage in cui stai esportando i dati. Il set di dati BigQuery e il bucket Cloud Storage devono trovarsi nella stessa località.
  • filename.ext è il nome e l'estensione del file di dati esportato. Puoi esportare in più file utilizzando un carattere jolly.

Esempi:

Ad esempio, il seguente comando esporta mydataset.mytable in un file compresso 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 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 seguente comando esporta mydataset.mytable in un file Avro compresso utilizzando Snappy. Il file è denominato 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

Il seguente comando esporta una singola partizione di 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.

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

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

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

  3. La proprietà destination URI(s) deve essere un nome completo nel formato gs://bucket/filename.ext. Ogni URI può contenere un carattere jolly "*" che 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à 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 la proprietà status.errorResult è presente, la richiesta non è andata a buon fine e l'oggetto includerà informazioni che descrivono il problema.
    • 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 sull'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 in caso di errori di rete perché il client può eseguire il polling o riprovare con l'ID job noto.

  • La chiamata di jobs.insert su un determinato ID job è idempotente; in altre parole, puoi riprovare tutte le volte che vuoi sullo stesso ID job e al massimo una di queste operazioni andrà a buon fine.

C#

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

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Ruby nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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

Esporta i metadati della tabella

Per esportare i metadati delle tabelle 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.

Esporta i risultati della query

Puoi esportare i risultati delle query in Cloud Storage nella console Google Cloud con i seguenti passaggi:

  1. Apri la pagina BigQuery nella console Google Cloud .

    Vai alla pagina BigQuery

  2. Fai clic su Query SQL.

  3. Inserisci una query GoogleSQL valida nell'area di testo Editor di query.

  4. Fai clic su Esegui.

  5. Quando vengono restituiti i risultati, fai clic su Salva i risultati > Cloud Storage.

  6. Nella finestra di dialogo Esporta in Google Cloud Storage:

    • In Posizione GCS, 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 (delimitato da nuova riga), Avro o Parquet.
    • In Compressione, seleziona un formato di compressione o seleziona None per nessuna compressione.

  7. Fai clic su Salva per esportare i risultati della query.

Per controllare l'avanzamento del job, espandi il riquadro Cronologia dei job e cerca il job con il tipo EXTRACT.

Altri modi per esportare i dati

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.

Dettagli esportazione Avro

BigQuery esprime i dati in formato Avro nei seguenti modi:

  • I file di esportazione risultanti sono file container 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 di BigQuery viene mappato a un tipo LONG di 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 che 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 anziché la colonna timestamp, ma nei job di estrazione utilizza sempre il tipo logico Avro.)
  • I tipi di dati DATE sono rappresentati come tipo logico date (annotano un tipo 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 o 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 un tipo Avro LONG) per impostazione predefinita in Export Data SQL, ma sono rappresentati come tipo string per impostazione predefinita nei job di estrazione. use_avro_logical_types=FalseExport Data Options--use_avro_logical_types=True
  • I tipi di dati DATETIME sono rappresentati come tipi Avro STRING (un tipo di 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 del tipo di 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 dell'esportazione in 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)
Numeric(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)
JSON 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)
Area geografica BYTE_ARRAY GEOGRAPHY (edges = spherical)

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.

Quando esporti una colonna JSON nel formato Parquet, viene esportata come campo STRING. Per caricare nuovamente questo file Parquet in una colonna JSON in BigQuery, devi specificare lo schema nel job di caricamento (ad esempio utilizzando il flag --schema). Il rilevamento automatico dello schema con Parquet deduce la colonna come tipo STRING.

Puoi utilizzare le seguenti soluzioni alternative per i tipi DATETIME:

  • Carica il file in una tabella di gestione temporanea. Quindi 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 Modifica del 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 con i metadati GeoParquet aggiunti ai file esportati.

Esportazione dei dati in uno o più file

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

BigQuery supporta un singolo operatore con caratteri jolly (*) in ogni URI. Il carattere jolly può essere visualizzato in qualsiasi punto del componente del nome file. L'utilizzo dell'operatore con caratteri jolly indica a BigQuery di creare più file con sharding in base al pattern fornito. L'operatore con caratteri jolly viene sostituito con un numero (a partire da 0), con spaziatura interna a sinistra di 12 cifre. Ad esempio, un URI con un carattere jolly alla fine del nome file creerebbe file con 000000000000 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:

Opzioni destinationUris
URI singolo

Utilizza un singolo URI se esporti dati della tabella di dimensioni pari o inferiori a 1 GB. Questa opzione è il caso d'uso più comune, poiché i dati esportati sono generalmente inferiori al valore massimo di 1 GB. Questa opzione non è supportata per l'istruzione EXPORT DATA; devi utilizzare un singolo URI con caratteri jolly.

Definizione della proprietà:

['gs://my-bucket/file-name.json']

Crea:

gs://my-bucket/file-name.json
URI con un singolo carattere jolly

È possibile utilizzare un singolo carattere jolly solo nel componente del nome file dell'URI.

Utilizza un singolo URI con caratteri jolly se ritieni che i dati esportati supereranno il valore massimo di 1 GB. BigQuery suddivide i dati in più file in base al pattern fornito. Le dimensioni dei file esportati variano. Se la query include una clausola "ORDER BY", il set di risultati ordinato a livello globale viene distribuito in sequenza tra i file generati.

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

['gs://my-bucket/*']

Crea:

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

Limita le dimensioni del file esportato

Quando esporti più di 1 GB di dati in un'unica 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 corrisponde 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, devi avere 400 partizioni.

  2. Crea una nuova tabella partizionata e raggruppata in cluster in base a una nuova colonna generata in modo casuale 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 ottenere le dimensioni del file scelte:

    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 sulla 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 di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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.

Supponiamo che tu stia trasmettendo dati in streaming a Cloud Storage dai log degli endpoint in modo continuo. Un'istantanea giornaliera deve essere esportata 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 job univoco utilizzato per creare il job. Il job è stato completato correttamente se status.status è DONE. Se è presente status.errorResult, il job non è riuscito e deve essere ripetuto.

Trattamento dati batch

Supponiamo che un job batch notturno venga utilizzato per caricare i dati entro una scadenza fissa. Al termine di questo job di caricamento, viene materializzata una tabella con le statistiche da una query, come descritto nella sezione precedente. I dati di questa tabella vengono recuperati e compilati in un report PDF, che viene poi inviato 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 è presente più di una pagina di dati, i risultati hanno la proprietà pageToken impostata. Per recuperare la pagina di risultati successiva, effettua un'altra chiamata tabledata.list e includi il valore del token come parametro pageToken. Se la chiamata API non va a buon fine con un errore 5xx, riprova con il backoff esponenziale. La maggior parte degli errori 4xx non può essere riprovata. Per un migliore disaccoppiamento di BigQuery Export e della generazione dei report, i risultati devono essere salvati su disco.

Criteri per le quote

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

L'utilizzo per i job di estrazione è disponibile in INFORMATION_SCHEMA. La voce del job nelle tabelle di sistema JOBS_BY_* per il job di estrazione contiene un valore total_bytes_processed che può essere utilizzato per monitorare l'utilizzo aggregato per garantire che rimanga inferiore a 50 TiB al giorno. Per scoprire come eseguire query sulla vista INFORMATION_SCHEMA.JOBS per ottenere il valore total_bytes_processed, consulta Schema INFORMATION_SCHEMA.JOBS.

Visualizza l'utilizzo attuale della quota

Puoi visualizzare l'utilizzo corrente 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 attuale con il limite della quota per determinare l'utilizzo della quota per un tipo di job specifico. 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 una policy di avviso di Cloud Monitoring che monitora il numero di byte esportati.

  1. Nella Google Cloud console, vai alla pagina  Avvisi:

    Vai ad Avvisi

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella pagina Avvisi, fai clic su Crea policy.

  3. In Modalità di configurazione della policy, seleziona Editor di codice (MQL o PromQL).

  4. Nell'editor di query PromQL, inserisci la seguente query:

    (
  sum by (project_id, quota_metric, location) (increase({"serviceruntime.googleapis.com/quota/rate/net_usage", monitored_resource="consumer_quota", service="bigquery.googleapis.com"}[1m]))
  /
  max by (project_id, quota_metric, location) ({"serviceruntime.googleapis.com/quota/limit", monitored_resource="consumer_quota", service="bigquery.googleapis.com", limit_name="ExtractBytesPerDay"})
) > 0.01

    Se l'opzione Esecuzione automatica non è attiva, fai clic su Esegui query.

  5. Configura il resto dell'avviso e fai clic su Crea policy.

Per i passaggi dettagliati sulla creazione di policy di avviso basate su PromQL, consulta Crea policy di avviso basate su PromQL (console).

Risoluzione dei problemi

Diagnostica e risolvi i problemi relativi ai job di estrazione.

Diagnostica i problemi utilizzando Esplora log

Per diagnosticare i problemi relativi ai job di estrazione, puoi utilizzare Esplora log per esaminare i log di un job di estrazione specifico e identificare 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")

Errore di superamento della quota di byte di estrazione al giorno

BigQuery restituisce questo errore quando l'estrazione supera il limite giornaliero predefinito di 50 TiB in un progetto. Per saperne di più sui limiti dei job di estrazione, consulta Job di estrazione.

Messaggio di errore

Your usage exceeded quota for ExtractBytesPerDay

Diagnosi

Se esporti una tabella di dimensioni superiori a 50 TiB, l'esportazione non va a buon fine perché supera il limite di estrazione. Se vuoi esportare i dati della tabella per partizioni di tabella specifiche, puoi utilizzare un decoratore di partizione per identificare le partizioni da esportare.

Se vuoi raccogliere gli utilizzi dei dati delle esportazioni degli ultimi giorni, puoi provare quanto segue:

  • Visualizza le quote per il tuo progetto con criteri di filtro come Name: Extract bytes per day o Metric: bigquery.googleapis.com/quota/extract/bytes, insieme al grafico Mostra utilizzo per vedere la tendenza di utilizzo nel corso di alcuni giorni.

  • In alternativa, puoi eseguire una query su INFORMATION_SCHEMA.JOBS_BY_PROJECT per visualizzare i byte totali estratti nell'arco di alcuni giorni. Ad esempio, la seguente query restituisce i byte totali giornalieri elaborati dai job EXTRACT negli ultimi sette giorni.

    SELECT
TIMESTAMP_TRUNC(creation_time, DAY) AS day,
SUM ( total_bytes_processed ) / POW(1024, 3) AS total_gibibytes_processed
FROM
`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE
creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
AND job_type = "EXTRACT"
GROUP BY 1
ORDER BY 2 DESC

  • Puoi quindi perfezionare ulteriormente i risultati identificando i job specifici che consumano più byte del previsto. L'esempio seguente restituisce i primi 100 job EXTRACT che consumano più di 100 GB elaborati negli ultimi sette giorni.

    SELECT
creation_time,
job_id,
total_bytes_processed/POW(1024, 3) AS total_gigabytes_processed
FROM
`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE
creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
AND job_type="EXTRACT"
AND total_bytes_processed > (POW(1024, 3) * 100)
ORDER BY
total_bytes_processed DESC
LIMIT 100

In alternativa, puoi utilizzare Esplora job con filtri come Bytes processed more than per filtrare i job con un'elevata elaborazione per un periodo di tempo specificato.

Risoluzione

Un metodo per risolvere questo errore di quota è creare una prenotazione di slot e assegnare il tuo progetto alla prenotazione con il tipo di prestazione PIPELINE. Questo metodo può bypassare il controllo del limite poiché utilizza le prenotazioni dedicate anziché un pool di slot condiviso senza costi. Se necessario, la prenotazione può essere eliminata se vuoi utilizzare un pool di slot condiviso in un secondo momento.

Per approcci alternativi che consentono di esportare più di 50 TiB, consulta la sezione Note in Job di estrazione.

Impossibile esportare a causa di un errore dello schema nidificato

Questo errore si verifica quando tenti di esportare una tabella contenente campi nidificati o ripetuti, ad esempio tipi di dati STRUCT o ARRAY, in un formato file flat come CSV o JSON delimitato da riga nuova.

Messaggio di errore

Failed to export: Operation cannot be performed on a nested schema. Field: [COLUMN_NAME]

Questo errore si verifica perché i formati file flat come CSV non possono rappresentare dati gerarchici o con più valori. Le esportazioni di BigQuery richiedono di appiattire o trasformare questi dati complessi in una struttura tabulare prima che possano essere scritti in un formato di file flat. In questo caso, COLUMN_NAME si riferisce a una colonna con campi nidificati o ripetuti che devono essere appiattiti o trasformati prima che i dati possano essere esportati.

Risoluzione

A seconda dello schema di origine, esistono diversi metodi che puoi utilizzare per appiattire lo schema e prepararlo per l'esportazione.

L'esempio seguente mostra uno schema con campi STRUCT nidificati e una query che li appiattisce per l'esportazione. Nell'esempio, la query di esportazione non riesce a causa dei campi nidificati nella colonna user_details. Puoi utilizzare la correzione suggerita per semplificare la struttura del file in due colonne, user_details.name e user_details.email.

  -- Schema example:
  root
    ├── id (INTEGER)
    ├── user_details (RECORD / STRUCT, NULLABLE)
    │   ├── name (STRING)
    │   └── email (STRING)
    └── created_at (TIMESTAMP)

  -- Export query:
  SELECT * FROM my_dataset.my_table;

  -- Suggested fix:
  SELECT
      id,
      user_details.name AS user_name,
      user_details.email AS user_email,
      created_at
  FROM
      my_dataset.my_table;

L'esempio seguente mostra uno schema con campi ARRAY ripetuti e una query che li appiattisce per l'esportazione. Nell'esempio, la query di esportazione non va a buon fine a causa dei campi ripetuti nella colonna line_items. Puoi utilizzare la correzione suggerita che utilizza l'operatore UNNEST() per convertire gli elementi dell'array in singole righe.

  -- Schema example:
  root
    ├── order_id (STRING)
    ├── customer_name (STRING)
    └── line_items (REPEATED / ARRAY of RECORD/STRUCT, NULLABLE)
        ├── product_id (STRING)
        └── quantity (INTEGER)


  -- Export query:
  SELECT * FROM my_dataset.my_orders_table;

  -- Suggested fix:
  SELECT
      t.order_id,
      t.customer_name,
      item.product_id,
      item.quantity
  FROM
      my_dataset.my_orders_table AS t
  LEFT JOIN
      UNNEST(t.line_items) AS item
  ;

In alternativa, puoi utilizzare ARRAY_TO_STRING() se devi rappresentare un array, ad esempio un ARRAY<STRING>, come una singola colonna di stringhe nel file CSV.

ARRAY_TO_STRING() concatena tutti gli elementi dell'array degli interessi in una singola stringa, utilizzando una virgola come separatore. Questa trasformazione è utile quando la struttura esatta di ogni elemento dell'array non è fondamentale per l'esportazione.

  -- Schema example:
  root
    ├── user_id (STRING)
    └── interests (REPEATED / ARRAY of STRING, NULLABLE)

  -- Suggested fix:
  SELECT
      user_id,
      ARRAY_TO_STRING(interests, ', ') AS user_interests
  FROM
      my_dataset.my_users_table;

Prezzi

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

Una volta esportati i dati, ti verrà addebitato il costo per l'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, consulta Controlla l'accesso alle risorse con IAM.

Passaggi successivi