Exporte dados de tabelas para o Cloud Storage

Esta página descreve como exportar ou extrair dados de tabelas do BigQuery para o Cloud Storage.

Depois de carregar os dados para o BigQuery, pode exportá-los em vários formatos. O BigQuery pode exportar até 1 GB de tamanho de dados lógicos para um único ficheiro. Se estiver a exportar mais de 1 GB de dados, tem de exportar os dados para vários ficheiros. Quando exporta os seus dados para vários ficheiros, o tamanho dos ficheiros varia.

Também pode exportar os resultados de uma consulta através da declaração EXPORT DATA. Pode usar EXPORT DATA OPTIONS para especificar o formato dos dados exportados.

Por último, pode usar um serviço como o Dataflow para ler dados do BigQuery em vez de os exportar do BigLake. Para mais informações sobre a utilização do Dataflow para ler e escrever no BigQuery, consulte a documentação de BigQuery I/O.

Limitações de exportação

Quando exporta dados do BigQuery, tenha em atenção o seguinte:

  • Não pode exportar dados de tabelas para um ficheiro local, para o Google Sheets nem para o Google Drive. A única localização de exportação suportada é o Cloud Storage. Para ver informações sobre como guardar resultados de consultas, consulte o artigo Transferir e guardar resultados de consultas.
  • Pode exportar até 1 GB de tamanho de dados da tabela lógica para um único ficheiro. Se estiver a exportar mais de 1 GB de dados, use um caráter universal para exportar os dados para vários ficheiros. Quando exporta dados para vários ficheiros, o tamanho dos ficheiros varia. Para limitar o tamanho do ficheiro exportado, pode dividir os dados e exportar cada divisão.
  • O tamanho do ficheiro gerado quando usa a declaração EXPORT DATA não é garantido.
  • O número de ficheiros gerados por uma tarefa de exportação pode variar.
  • Não pode exportar dados aninhados e repetidos no formato CSV. Os dados aninhados e repetidos são suportados para exportações de Avro, JSON e Parquet.
  • Quando exporta dados no formato JSON, os tipos de dados INT64 (número inteiro) são codificados como strings JSON para preservar a precisão de 64 bits quando os dados são lidos por outros sistemas.
  • Não pode exportar dados de várias tabelas numa única tarefa de exportação.
  • Não pode escolher um tipo de compressão diferente de GZIP quando exporta dados através da Google Cloud consola.
  • Quando exporta uma tabela no formato JSON, os símbolos <, > e & são convertidos através da notação Unicode \uNNNN, em que N é um dígito hexadecimal. Por exemplo, profit&loss torna-se profit\u0026loss. Esta conversão Unicode é feita para evitar vulnerabilidades de segurança.
  • A ordem dos dados da tabela exportados não é garantida, a menos que use a declaração EXPORT DATA e especifique uma cláusula ORDER BY no query_statement.
  • O BigQuery não suporta caminhos de recursos do Cloud Storage que incluam várias barras invertidas consecutivas após a barra invertida dupla inicial. Os nomes de objetos do Cloud Storage podem conter vários carateres de barra ("/") consecutivos. No entanto, o BigQuery converte várias barras invertidas consecutivas numa única barra invertida. Por exemplo, o seguinte caminho do recurso, embora seja válido no Cloud Storage, não funciona no BigQuery: gs://bucket/my//object//name.
  • Todos os novos dados carregados no BigQuery enquanto uma tarefa de exportação estiver em execução não são incluídos nessa tarefa de exportação. Tem de criar uma nova tarefa de exportação para exportar os novos dados.

Antes de começar

Conceda funções de gestão de identidade e de acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.

Autorizações necessárias

Para realizar as tarefas neste documento, precisa das seguintes autorizações.

Autorizações para exportar dados de uma tabela do BigQuery

Para exportar dados de uma tabela do BigQuery, precisa da autorização do bigquery.tables.export IAM.

Cada uma das seguintes funções de IAM predefinidas inclui a autorização bigquery.tables.export:

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

Autorizações para executar uma tarefa de exportação

Para executar uma tarefa de exportação, precisa da autorização de IAM bigquery.jobs.create.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para executar uma tarefa de exportação:

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

Autorizações para escrever os dados no contentor do Cloud Storage

Para escrever os dados num contentor do Cloud Storage existente, precisa das seguintes autorizações de IAM:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para escrever os dados num contentor do Cloud Storage existente:

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

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Formatos de exportação e tipos de compressão

O BigQuery suporta os seguintes formatos de dados e tipos de compressão para dados exportados.

Formato de dados Tipos de compressão suportados Detalhes
CSV GZIP

Pode controlar o delimitador CSV nos dados exportados através da flag da ferramenta de linha de comandos --field_delimiter ou da propriedade do trabalho de extração configuration.extract.fieldDelimiter.

Os dados aninhados e repetidos não são suportados.
JSON GZIP Os dados aninhados e repetidos são suportados.
Avro DEFLATE, SNAPPY

O GZIP não é suportado para exportações Avro.

Os dados aninhados e repetidos são suportados. Consulte os detalhes da exportação Avro.
Parquet SNAPPY, GZIP, ZSTD

Os dados aninhados e repetidos são suportados. Veja os detalhes da exportação Parquet.

Exportar dados

As secções seguintes mostram como exportar os dados das tabelas, os metadados das tabelas e os resultados das consultas para o Cloud Storage.

Exporte dados de tabelas

Pode exportar dados de tabelas das seguintes formas:

  • Usar a Google Cloud consola
  • Usar o comando bq extract na ferramenta de linhas de comando bq
  • Enviar uma tarefa extract através da API ou das bibliotecas cliente

Selecione uma das seguintes opções:

Consola

  1. Abra a página do BigQuery na Google Cloud consola.

    Aceda à página do BigQuery

  2. No painel Explorador, expanda o projeto e o conjunto de dados e, de seguida, selecione a tabela.

  3. No painel de detalhes, clique em Exportar e selecione Exportar para o Cloud Storage.

  4. Na caixa de diálogo Exportar para o Google Cloud Storage:

    • Para Localização do GCS, procure o contentor, a pasta ou o ficheiro onde quer exportar os dados.
    • Para Formato de exportação, escolha o formato dos dados exportados: CSV, JSON (delimitado por nova linha), Avro ou Parquet.
    • Em Compressão, selecione um formato de compressão ou selecione None para não comprimir.

  5. Clique em Guardar para exportar a tabela.

Para verificar o progresso da tarefa, expanda o painel Histórico de tarefas e procure a tarefa do tipo EXTRACT.

Para exportar vistas para o Cloud Storage, use a declaração EXPORT DATA OPTIONS.

SQL

Use a declaração EXPORT DATA. O exemplo seguinte exporta os campos selecionados de uma tabela denominada mydataset.table1:

  1. Na Google Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaração:

    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. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq extract com a flag --destination_format.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

Outras flags opcionais incluem:

  • --compression: o tipo de compressão a usar para ficheiros exportados.
  • --field_delimiter: o caráter que indica o limite entre colunas no ficheiro de saída para exportações CSV. São permitidos \t e tab para delimitadores de tabulações.
  • --print_header: quando especificado, imprime linhas de cabeçalho para formatos que têm cabeçalhos, como 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

Onde:

  • location é o nome da sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
  • format é o formato dos dados exportados: CSV, NEWLINE_DELIMITED_JSON, AVRO ou PARQUET.
  • compression_type é um tipo de compressão suportado para o seu formato de dados. Consulte os formatos de exportação e os tipos de compressão.
  • delimiter é o caráter que indica o limite entre colunas nas exportações CSV. \t e tab são nomes aceites para o separador.
  • boolean é true ou false. Quando definido como true, as linhas de cabeçalho são impressas nos dados exportados se o formato de dados suportar cabeçalhos. O valor predefinido é true.
  • project_id é o ID do seu projeto.
  • dataset é o nome do conjunto de dados de origem.
  • table é a tabela que está a exportar. Se usar um decorador de partições, tem de colocar o caminho da tabela entre aspas simples ou usar o caráter $.
  • bucket é o nome do contentor do Cloud Storage para o qual está a exportar os dados. O conjunto de dados do BigQuery e o contentor do Cloud Storage têm de estar na mesma localização.
  • filename.ext é o nome e a extensão do ficheiro de dados exportado. Pode exportar para vários ficheiros usando um caráter universal.

Exemplos:

Por exemplo, o comando seguinte exporta mydataset.mytable para um ficheiro comprimido com gzip denominado myfile.csv. myfile.csv é armazenado num contentor do Cloud Storage denominado example-bucket.

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

O formato de destino predefinido é CSV. Para exportar para JSON ou Avro, use a flag destination_format e defina-a como NEWLINE_DELIMITED_JSON ou AVRO. Por exemplo:

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

O comando seguinte exporta mydataset.mytable para um ficheiro Avro comprimido com Snappy. O ficheiro tem o nome myfile.avro. myfile.avro é exportado para um contentor do Cloud Storage com o nome example-bucket.

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

O comando seguinte exporta uma única partição de mydataset.my_partitioned_table para um ficheiro CSV no Cloud Storage:

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

API

Para exportar dados, crie uma tarefa extract e preencha a configuração da tarefa.

(Opcional) Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

  1. Crie uma tarefa de extração que aponte para os dados de origem do BigQuery e o destino do Cloud Storage.

  2. Especifique a tabela de origem através do objeto de configuração sourceTable que contém o ID do projeto, o ID do conjunto de dados e o ID da tabela.

  3. A propriedade destination URI(s) tem de ser totalmente qualificada, no formato gs://bucket/filename.ext. Cada URI pode conter um caráter universal "*" e tem de aparecer depois do nome do contentor.

  4. Especifique o formato de dados definindo a propriedade configuration.extract.destinationFormat. Por exemplo, para exportar um ficheiro JSON, defina esta propriedade para o valor NEWLINE_DELIMITED_JSON.

  5. Para verificar o estado da tarefa, chame jobs.get(job_id) com o ID da tarefa devolvido pelo pedido inicial.

    • Se status.state = DONE, a tarefa foi concluída com êxito.
    • Se a propriedade status.errorResult estiver presente, o pedido falhou e esse objeto inclui informações que descrevem o que correu mal.
    • Se status.errorResult estiver ausente, a tarefa foi concluída com êxito, embora possam ter ocorrido alguns erros não fatais. Os erros não fatais são apresentados na propriedade status.errors do objeto de trabalho devolvido.

Notas da API:

  • Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId quando chamar jobs.insert para criar uma tarefa. Esta abordagem é mais robusta em caso de falha de rede, uma vez que o cliente pode sondar ou tentar novamente com o ID da tarefa conhecido.

  • A chamada de jobs.insert num determinado ID da tarefa é idempotente. Por outras palavras, pode tentar novamente quantas vezes quiser no mesmo ID da tarefa e, no máximo, uma dessas operações vai ter êxito.

C#

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 


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

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

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

# 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

Antes de experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Ruby BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Exporte metadados de tabelas

Para exportar metadados de tabelas de tabelas Iceberg, use a seguinte declaração SQL:

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

Substitua o seguinte:

  • PROJECT_NAME: o nome do projeto para a tabela. O valor é predefinido para o projeto que executa esta consulta.
  • DATASET_NAME: o nome do conjunto de dados para a tabela.
  • TABLE_NAME: o nome da tabela.

Os metadados exportados encontram-se na pasta STORAGE_URI/metadata, onde STORAGE_URI é a localização de armazenamento da tabela definida nas opções.

Exporte os resultados da consulta

Pode exportar os resultados da consulta para o Cloud Storage na Google Cloud consola com os seguintes passos:

  1. Abra a página do BigQuery na Google Cloud consola.

    Aceda à página do BigQuery

  2. Clique em Consulta SQL.

  3. Introduza uma consulta GoogleSQL válida na área de texto do editor de consultas.

  4. Clique em Executar.

  5. Quando os resultados forem devolvidos, clique em Guardar resultados > Armazenamento na nuvem.

  6. Na caixa de diálogo Exportar para o Google Cloud Storage:

    • Para Localização do GCS, procure o contentor, a pasta ou o ficheiro onde quer exportar os dados.
    • Para Formato de exportação, escolha o formato dos dados exportados: CSV, JSON (delimitado por nova linha), Avro ou Parquet.
    • Em Compressão, selecione um formato de compressão ou selecione None para não comprimir.

  7. Clique em Guardar para exportar os resultados da consulta.

Para verificar o progresso da tarefa, expanda o painel Histórico de tarefas e procure a tarefa do tipo EXTRACT.

Detalhes da exportação Avro

O BigQuery expressa os dados formatados em Avro das seguintes formas:

  • Os ficheiros de exportação resultantes são ficheiros de contentores Avro.
  • Cada linha do BigQuery é representada como um registo Avro. Os dados aninhados são representados por objetos de registo aninhados.
  • Os campos REQUIRED são representados como os tipos Avro correspondentes. Por exemplo, um tipo INTEGER do BigQuery é mapeado para um tipo LONG do Avro.
  • Os campos NULLABLE são representados como uma união Avro do tipo correspondente e "nulo".
  • Os campos REPEATED são representados como matrizes Avro.
  • Os tipos de dados TIMESTAMP são representados como o tipo lógico timestamp-micros (anota um tipo LONG do Avro) por predefinição nas tarefas de extração e no SQL de exportação de dados. (Atenção: pode adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico, para que use o tipo string na coluna de data/hora. No entanto, nos trabalhos de extração, usa sempre o tipo lógico Avro.)
  • Os tipos de dados DATE são representados como o tipo lógico date (anota os tipos Avro) por predefinição no SQL de exportação de dados, mas são representados como o tipo string por predefinição em tarefas de extração.INT (Nota: pode adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a flag --use_avro_logical_types=True para ativar o tipo lógico em trabalhos de extração.)
  • Os tipos de dados TIME são representados como o tipo lógico timestamp-micro (anota os tipos LONG do Avro) por predefinição no SQL de exportação de dados, mas são representados como o tipo string por predefinição nos trabalhos de extração. (Nota: pode adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a flag --use_avro_logical_types=True para ativar o tipo lógico em trabalhos de extração.)
  • Os tipos de dados DATETIME são representados como tipos STRING (um tipo de string com o tipo lógico denominado personalizado datetime) por predefinição no SQL de exportação de dados, mas são representados como o tipo string por predefinição em tarefas de extração. (Nota: pode adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a flag --use_avro_logical_types=True para ativar o tipo lógico em tarefas de extração.)
  • Os tipos RANGE não são suportados na exportação Avro.

Os tipos de dados NUMERIC(P[, S]) e BIGNUMERIC(P[, S]) parametrizados transferem os respetivos parâmetros de precisão e tipo de escala para o tipo lógico decimal Avro.

Não é possível usar o formato Avro em combinação com a compressão GZIP. Para comprimir dados Avro, use a ferramenta de linhas de comando bq ou a API e especifique um dos tipos de compressão suportados para dados Avro: DEFLATE ou SNAPPY.

Detalhes da exportação Parquet

O BigQuery converte os tipos de dados GoogleSQL nos seguintes tipos de dados Parquet:

Tipo de dados do BigQuery Tipo primitivo Parquet Tipo lógico Parquet
Número inteiro INT64 NONE
Numérico 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)
Vírgula flutuante FLOAT NONE
Booleano BOOLEAN NONE
String BYTE_ARRAY STRING (UTF8)
Bytes BYTE_ARRAY NONE
Data INT32 DATE
Data/hora INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Hora INT64 TIME (isAdjustedToUTC = true, unit = MICROS)
Indicação de tempo INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Geografia BYTE_ARRAY GEOGRAPHY (edges = spherical)

O esquema Parquet representa dados aninhados como um grupo e registos repetidos como grupos repetidos. Para mais informações sobre a utilização de dados aninhados e repetidos no BigQuery, consulte o artigo Especificar colunas aninhadas e repetidas.

Pode usar as seguintes soluções alternativas para os tipos DATETIME:

  • Carregue o ficheiro para uma tabela de preparação. Em seguida, use uma consulta SQL para converter o campo num tipo de dados DATETIME e guarde o resultado numa nova tabela. Para mais informações, consulte o artigo Alterar o tipo de dados de uma coluna.
  • Forneça um esquema para a tabela usando a flag --schema na tarefa de carregamento. Defina a coluna de data/hora como col:DATETIME.

O tipo lógico GEOGRAPHY é representado com metadados GeoParquet adicionados aos ficheiros exportados.

Exportar dados para um ou mais ficheiros

A propriedade destinationUris indica uma ou mais localizações e nomes de ficheiros para onde o BigQuery deve exportar os seus ficheiros.

O BigQuery suporta um único operador de carateres universais (*) em cada URI. O caráter universal pode aparecer em qualquer parte do componente do nome do ficheiro. A utilização do operador de carateres universais indica ao BigQuery que deve criar vários ficheiros fragmentados com base no padrão fornecido. O operador de carateres universais é substituído por um número (a começar em 0), com preenchimento à esquerda até 12 dígitos. Por exemplo, um URI com um caráter universal no final do nome do ficheiro criaria ficheiros com 000000000000 anexado ao primeiro ficheiro e 000000000001 anexado ao segundo ficheiro, continuando nesse padrão.

A tabela seguinte descreve várias opções possíveis para a propriedade destinationUris:

Opções de destinationUris
URI único

Use um único URI se estiver a exportar dados de tabelas com 1 GB ou menos. Esta opção é o exemplo de utilização mais comum, uma vez que os dados exportados são geralmente inferiores ao valor máximo de 1 GB. Esta opção não é suportada para a declaração EXPORT DATA; tem de usar um único URI com caráter universal.

Definição da propriedade:

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

Cria:

gs://my-bucket/file-name.json
URI com um único caráter universal

Só é possível usar um caráter universal no componente do nome do ficheiro do URI.

Use um URI com carateres universais único se considerar que os dados exportados vão ser superiores ao valor máximo de 1 GB. O BigQuery divide os seus dados em vários ficheiros com base no padrão fornecido. O tamanho dos ficheiros exportados varia.

Definição da propriedade:

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

Cria:

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

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

Cria:

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

Limite o tamanho do ficheiro exportado

Quando exporta mais de 1 GB de dados numa única exportação, tem de usar um caráter universal para exportar os dados para vários ficheiros, e o tamanho dos ficheiros varia. Se precisar de limitar o tamanho máximo de cada ficheiro exportado, uma opção é particionar aleatoriamente os dados e, em seguida, exportar cada partição para um ficheiro:

  1. Determine o número de partições de que precisa, que é igual ao tamanho total dos seus dados dividido pelo tamanho do ficheiro exportado escolhido. Por exemplo, se tiver 8000 MB de dados e quiser que cada ficheiro exportado tenha aproximadamente 20 MB, precisa de 400 partições.

  2. Crie uma nova tabela particionada e agrupada por uma nova coluna gerada aleatoriamente denominada export_id. O exemplo seguinte mostra como criar uma nova processed_table a partir de uma tabela existente denominada source_table que requer n partições para atingir o tamanho do ficheiro escolhido:

    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. Para cada número inteiro i entre 0 e n-1, execute uma declaração EXPORT DATA na seguinte consulta:

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

Extraia a tabela comprimida

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 

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

Exemplo de utilização

Este exemplo mostra como pode exportar dados para o Cloud Storage.

Suponhamos que está a fazer streaming de dados para o Cloud Storage a partir de registos de pontos finais de forma contínua. Um resumo diário deve ser exportado para o Cloud Storage para fins de cópia de segurança e arquivo. A melhor escolha é uma tarefa de extração sujeita a determinadas quotas e limitações.

Envie uma tarefa de extração com a API ou as bibliotecas cliente, transmitindo um ID exclusivo como jobReference.jobId. As tarefas de extração são assíncronas. Verifique o estado da tarefa através do ID exclusivo da tarefa usado para criar a tarefa. O trabalho foi concluído com êxito se status.status for DONE. Se status.errorResult estiver presente, a tarefa falhou e tem de ser repetida.

Processamento de dados em lote

Suponhamos que é usado um trabalho em lote noturno para carregar dados até um prazo fixo. Após a conclusão desta tarefa de carregamento, é materializada uma tabela com estatísticas a partir de uma consulta, conforme descrito na secção anterior. Os dados desta tabela são obtidos e compilados num relatório PDF e enviados a um regulador.

Uma vez que a quantidade de dados que tem de ser lida é pequena, use a API tabledata.list para obter todas as linhas da tabela no formato de dicionário JSON. Se existir mais do que uma página de dados, os resultados têm a propriedade pageToken definida. Para obter a página seguinte de resultados, faça outra chamada tabledata.list e inclua o valor do token como o parâmetro pageToken. Se a chamada da API falhar com um erro 5xx, tente novamente com retirada exponencial. Não é possível repetir a maioria dos erros 4xx. Para uma melhor separação da exportação do BigQuery e da geração de relatórios, os resultados devem ser mantidos no disco.

Política de quotas

Para informações sobre as quotas de tarefas de exportação, consulte o artigo Tarefas de exportação na página Quotas e limites.

As estatísticas de utilização dos trabalhos de exportação estão disponíveis no INFORMATION_SCHEMA. A entrada da tarefa nas tabelas do sistema JOBS_BY_* para a tarefa de exportação contém um valor total_bytes_processed que pode ser usado para monitorizar a utilização agregada para garantir que permanece abaixo de 50 TiB por dia. Para saber como consultar a vista INFORMATION_SCHEMA.JOBS para obter o valor total_bytes_processed, consulte o INFORMATION_SCHEMA.JOBS esquema

Veja a utilização atual da quota

Pode ver a sua utilização atual de tarefas de consulta, carregamento, extração ou cópia executando uma consulta INFORMATION_SCHEMA para ver metadados sobre as tarefas executadas durante um período especificado. Pode comparar a sua utilização atual com o limite da quota para determinar a utilização da quota para um tipo específico de tarefa. A seguinte consulta de exemplo usa a vista INFORMATION_SCHEMA.JOBS para listar o número de tarefas de consulta, carregamento, extração e cópia por projeto:

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

Pode configurar uma política de alertas do Cloud Monitoring que monitoriza o número de bytes exportados.

  1. Na Google Cloud consola, aceda à página  Alertas:

    Aceder a Alertas

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na página Alertas, clique em Criar política.

  3. Em Modo de configuração de políticas, selecione Editor de código (MQL ou PromQL).

  4. No editor de consultas PromQL, introduza a seguinte consulta:

    (
  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 a opção Executar automaticamente não estiver ativada, clique em Executar consulta.

  5. Configure o resto do alerta e clique em Criar política.

Para ver passos detalhados sobre a criação de políticas de alerta baseadas em PromQL, consulte o artigo Crie políticas de alerta baseadas em PromQL (consola).

Resolução de problemas

Para diagnosticar problemas com tarefas de extração, pode usar o Explorador de registos para rever os registos de uma tarefa de extração específica e identificar possíveis erros. O filtro do Explorador de registos seguinte devolve informações sobre as suas tarefas de extração:

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

Preços

Para obter informações sobre os preços da exportação de dados, consulte a página Preços do BigQuery.

Depois de exportados, os dados são cobrados pelo respetivo armazenamento no Cloud Storage. Para mais informações, consulte os preços do Cloud Storage.

Segurança da mesa

Para controlar o acesso a tabelas no BigQuery, consulte o artigo Controle o acesso a recursos com a IAM.

O que se segue?