Exportar dados de tabelas para o Cloud Storage

Nesta página, você verá como exportar ou extrair dados de tabelas do BigQuery para o Cloud Storage.

Depois de carregar os dados no BigQuery, eles podem ser exportados em diferentes formatos. O BigQuery pode exportar até 1 GB de dados para um único arquivo. Se você estiver exportando mais de 1 GB de dados, será preciso exportá-los para vários arquivos. Ao fazer isso, o tamanho dos arquivos será variado.

É possível usar um serviço como o Dataflow para ler dados no BigQuery, em vez de exportá-los manualmente. Para mais informações sobre como usar o Dataflow para ler e gravar no BigQuery, consulte E/S do BigQuery (em inglês) na documentação do Apache Beam.

Também é possível exportar os resultados de uma consulta usando a instrução EXPORT DATA. Use EXPORT DATA OPTIONS para exportar visualizações para o Cloud Storage.

Limitações de exportação

Ao exportar dados do BigQuery, observe os itens a seguir:

• Não é possível exportar dados de tabela para um arquivo local, o Planilhas Google ou o Google Drive. O único local de exportação aceito é o Cloud Storage. Para mais informações sobre como salvar resultados de consulta, acesse Como fazer o download de resultados de consulta e salvá-los.
• É possível exportar até 1 GB de dados da tabela para um único arquivo. Se você estiver exportando mais de 1 GB de dados, use um caractere curinga para exportar os dados para vários arquivos. Ao exportar dados para vários arquivos, o tamanho dos arquivos varia. Para limitar o tamanho do arquivo exportado, é possível particionar seus dados e exportar cada partição.
• O tamanho do arquivo gerado ao usar a instrução EXPORT DATA não é garantido.
• O número de arquivos gerados por um job de exportação pode variar.
• Não é possível exportar dados aninhados e repetidos no formato CSV. Os dados aninhados e repetidos são compatíveis com as exportações para Avro, JSON e Parquet.
• Quando você exporta dados no formato JSON, os tipos de dados INT64 (números inteiros) 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 é possível exportar dados de várias tabelas em um único job de exportação.
• Só é possível escolher o tipo de compactação GZIP ao exportar dados usando o console do Google Cloud.
• Ao exportar dados para um bucket do Cloud Storage configurado com uma política de retenção, o BigQuery pode não gravar os arquivos no bucket. Configure o período de armazenamento para que seja mais longo que a duração dos jobs de exportação.
• Quando você exporta uma tabela no formato JSON, os símbolos <, > e & são convertidos usando a notação unicode \uNNNN, em que N é um dígito hexadecimal. Por exemplo, profit&loss torna-se profit\u0026loss. Essa conversão para unicode é feita para evitar vulnerabilidades de segurança.
• A ordem dos dados da tabela exportada não é garantida, a menos que você use a instrução EXPORT DATA e especifique uma cláusula ORDER BY no query_statement.
• O BigQuery não é compatível com caminhos de recursos do Cloud Storage que contêm várias barras consecutivas após a barra dupla inicial. Os nomes de objeto do Cloud Storage podem conter vários caracteres de barra ("/") consecutivos. No entanto, o BigQuery os converte em uma única barra. Por exemplo, o caminho de recurso a seguir, ainda que válido no Cloud Storage, não funciona no BigQuery: gs://bucket/my//object//name.
• Os dados novos carregados no BigQuery enquanto um job de exportação estiver em execução não serão incluídos nesse job. Você precisa criar um novo job de exportação para exportar os novos dados.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

Para executar as tarefas neste documento, você precisa das seguintes permissões.

Permissões para exportar dados de uma tabela do BigQuery

Para exportar dados de uma tabela do BigQuery, você precisa da permissão do IAM bigquery.tables.export.

Cada um dos seguintes papéis predefinidos do IAM inclui a permissão bigquery.tables.export:

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

Permissões para executar um job de exportação

Para executar um job de exportação, é preciso ter a permissão bigquery.jobs.create do IAM.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para executar um job de exportação:

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

Permissões para gravar os dados no bucket do Cloud Storage

Para gravar os dados em um bucket atual do Cloud Storage, você precisa das seguintes permissões do IAM:

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

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para gravar os dados em um bucket atual do Cloud Storage:

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

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Considerações sobre o local

Colocar os buckets do Cloud Storage para exportar dados:

• Se o conjunto de dados do BigQuery estiver na multirregião EU, o bucket do Cloud Storage que contém os dados exportados precisará estar na mesma multirregião ou em um local contido na multirregião. Por exemplo, se o conjunto de dados do BigQuery estiver na multirregião EU, o bucket do Cloud Storage poderá estar localizado na região Bélgica europe-west1, que está na UE.

  Se seu conjunto de dados estiver na multirregião US, será possível exportar dados para um bucket do Cloud Storage em qualquer local.

• Se o conjunto de dados estiver em uma região, o bucket do Cloud Storage precisará estar na mesma região. Por exemplo, se o conjunto de dados estiver na região asia-northeast1 de Tóquio, o bucket do Cloud Storage não poderá estar na multirregião ASIA.

Desenvolver um plano de gerenciamento de dados:

• Se você escolher um recurso de armazenamento regional, como um conjunto de dados do BigQuery ou um bucket do Cloud Storage, será necessário desenvolver um plano para gerenciar geograficamente seus dados.

Para mais informações sobre locais do Cloud Storage, consulte Locais de buckets na respectiva documentação.

Mover dados do BigQuery entre locais

Não é possível alterar o local de um conjunto de dados após a criação, mas tem como fazer uma cópia dele. Não é possível mover um conjunto de dados de um local para outro, mas é possível mover (recriar) manualmente um conjunto de dados.

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

O BigQuery é compatível com os seguintes formatos de dados e tipos de compactação para dados exportados.

Formato de dados	Tipos de compactação compatíveis	Detalhes
CSV	GZIP	É possível controlar o delimitador CSV nos dados exportados usando a sinalização --field_delimiter da ferramenta de linha de comando bq ou a propriedade de job de extração configuration.extract.fieldDelimiter. Dados aninhados e repetidos não são compatíveis.
JSON	GZIP	Dados aninhados e repetidos são compatíveis.
Avro	DEFLATE, SNAPPY	GZIP não é aceito para exportações do Avro. Dados aninhados e repetidos são compatíveis. Consulte os detalhes da exportação do Avro.
Parquet	SNAPPY, GZIP, ZSTD	Dados aninhados e repetidos são compatíveis. Consulte os Detalhes da exportação do Parquet.

Exportar dados

Para exportar dados de tabela:

• Use o console do Google Cloud
• use o comando bq extract na ferramenta de linha de comando bq;
• envie um job extract com a API ou as bibliotecas cliente.

exportar dados da tabela

Para exportar dados de uma tabela do BigQuery, siga estas etapas:

Console

1. Abra a página do BigQuery no console do Google Cloud.

   Acesse a página do BigQuery

2. No painel Explorer, expanda o projeto e o conjunto de dados e 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 tabela para o Google Cloud Storage, siga estas instruções:

   • Em Selecionar local do Google Cloud Storage, procure o bucket, a pasta ou o arquivo para o qual quer exportar os dados.
   • Em Formato de exportação, escolha o formato dos dados exportados: CSV, JSON (delimitado por nova linha), Avro ou Parquet.
   • Para Compactação, selecione um formato de compactação ou None para não fazer compactação.
   • Clique em Exportar para exportar a tabela.

Para verificar o andamento do job, procure um job de exportação no Histórico de jobs, na parte superior da navegação.

Para exportar visualizações para o Cloud Storage, use a instrução EXPORT DATA OPTIONS.

SQL

Use a instrução EXPORT DATA. No exemplo a seguir, exportamos os campos selecionados de uma tabela chamada mydataset.table1.

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instruçã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, acesse Executar uma consulta interativa.

bq

Use o comando bq extract com a sinalização --destination_format.

Opcional: forneça a sinalização --location e defina o valor do local.

Estas são outras sinalizações opcionais:

• --compression: o tipo de compactação a ser usado para arquivos exportados.
• --field_delimiter: o caractere que indica o limite entre as colunas no arquivo de saída para exportações de CSV. \t e tab são permitidos como delimitadores de tabulação.
• --print_header: quando especificado, esse objeto 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

Em que:

• location é o nome do local. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
• format é o formato dos dados exportados: CSV, NEWLINE_DELIMITED_JSON, AVRO ou PARQUET.
• compression_type é um tipo de compactação compatível com o formato dos dados. Consulte Exportar formatos e tipos de compactação.
• delimiter é o caractere que indica o limite entre as colunas nas exportações de CSV. \t e tab são nomes aceitos para a tabulação.
• boolean é true ou false. Quando definido como true, as linhas de cabeçalho serão impressas nos dados exportados se o formato de dados for compatível com cabeçalhos. O valor padrão é true.
• project_id é o ID do projeto;
• dataset é o nome do conjunto de dados de origem;
• table é a tabela que você está exportando; Se você usar um decorador de partição, precisará colocar o caminho da tabela entre aspas simples ou usar o caractere $.
• bucket é o nome do bucket do Cloud Storage para o qual você está exportando os dados. O conjunto de dados do BigQuery e o bucket do Cloud Storage precisam estar no mesmo local.
• filename.ext é o nome e a extensão do arquivo de dados exportado. Exporte para vários arquivos com um caractere curinga.

Exemplos:

Por exemplo, o comando a seguir exporta mydataset.mytable para um arquivo gzip compactado chamado myfile.csv. myfile.csv é armazenado em um bucket do Cloud Storage chamado example-bucket.

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

O formato de destino padrão é CSV. Para exportar para JSON ou Avro, use a sinalização destination_format, que precisa ser definida como NEWLINE_DELIMITED_JSON ou AVRO. Por exemplo:

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

O comando a seguir exporta mydataset.mytable em um arquivo Avro, que é compactado usando o Snappy. O nome do arquivo é myfile.avro. myfile.avro é exportado para um bucket do Cloud Storage chamado example-bucket.

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

O comando a seguir exporta uma única partição de mydataset.my_partitioned_table para um arquivo 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 um job extract e preencha a configuração do job.

Observação: se você estiver exportando dados para o formato Parquet, pode ser mais rápido usar o Modelo do BigQuery Export para Parquet (via API BigQuery Storage) em vez de criar uma solução personalizada.

(Opcional) Especifique seu local na propriedade location, na seção jobReference do recurso do job.

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

2. Especifique a tabela de origem usando o 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) precisa ser totalmente qualificada no formato gs://bucket/filename.ext. Cada URI contém um caractere curinga "*" após o nome do bucket.

4. Defina a propriedade configuration.extract.destinationFormat para especificar o formato dos dados. Por exemplo, para exportar um arquivo JSON, defina essa propriedade com o valor NEWLINE_DELIMITED_JSON.

5. Para verificar o status do job, chame jobs.get(job_id) com o ID do job retornado pela solicitação inicial.

   • status.state = DONE indica que o job foi concluído.
   • Se a propriedade status.errorResult aparecer, isso indica que houve falha na solicitação, e o objeto incluirá informações que descrevem o erro.
   • Se status.errorResult não aparecer, o job foi concluído com sucesso, mesmo se houver erros não fatais. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

• Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId, ao chamar jobs.insert para criar um job. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.

• Chamar jobs.insert em um determinado ID de job é idempotente, ou seja, é possível repetir o processo quantas vezes quiser com o mesmo ID e, no máximo, uma das operações será bem-sucedida.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em C#.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Ruby.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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

Detalhes da exportação em Avro

No BigQuery, os dados formatados em Avro são expressos das seguintes maneiras:

• Os arquivos de exportação resultantes são de contêiner Avro.
• Cada linha do BigQuery é representada como um registro Avro. Os dados aninhados são representados por objetos de registro aninhados.
• Os campos REQUIRED são representados como tipos Avro correspondentes. Por exemplo, um tipo INTEGER do BigQuery é mapeado para um tipo Avro LONG.
• 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 tipo lógico timestamp-micros (anota um tipo Avro LONG) por padrão em Jobs de extração e em SQL de exportação de dados. Cuidado: é possível adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico para usar o tipo string na coluna de carimbo de data/hora. No entanto, em "Extract Jobs", ele sempre usa o tipo Avro lógico.
• Os tipos de dados DATE são representados como tipo lógico date (anota os tipos Avro INT) por padrão no SQL de exportação de dados, mas são representados como tipo string por padrão em jobs de extração. Observação: é possível adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a sinalização --use_avro_logical_types=True para ativar o tipo lógico em Jobs de extração.
• Por padrão, os tipos de dados TIME são representados como tipo lógico timestamp-micro (ele anota um tipo LONG da Avro) no SQL de dados de exportação, mas são representados como tipo string por padrão em jobs de extração. Observação: é possível adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a sinalização --use_avro_logical_types=True para ativar o tipo lógico em Jobs de extração.
• Os tipos de dados DATETIME são representados como tipos Avro STRING (um tipo de string com tipo lógico nomeado personalizado datetime) por padrão no Export Data SQL, mas são representados como string digite por padrão nos jobs de extração. Observação: é possível adicionar use_avro_logical_types=False a Export Data Options para desativar o tipo lógico ou usar a sinalização --use_avro_logical_types=True para ativar o tipo lógico em Jobs de extração.

Observação: a codificação do tipo de string segue a especificação RFC 3339 o Internet Engineering Task Force.

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

Cuidado:

• Se você exportar um tipo DATETIME para Avro, não será possível carregar o arquivo Avro diretamente no mesmo esquema da tabela porque o STRING convertido não corresponderá ao esquema. Como solução alternativa, carregue o arquivo em uma tabela de preparação. Em seguida, use uma consulta SQL para converter o campo em um tipo DATETIME e salve o resultado em uma nova tabela. Para mais informações, consulte Como alterar o tipo de dados de uma coluna.
• A opção de exportação de dados use_avro_logical_types e a sinalização do job de extração --use_avro_logical_types são aplicadas a todos os tipos lógicos ao mesmo tempo, conforme especificado.

O formato Avro não pode ser usado com a compactação GZIP. Para compactar dados Avro, use a ferramenta de linha de comando bq ou a API e especifique um dos tipos de compactação compatíveis com os dados Avro: DEFLATE ou SNAPPY.

Detalhes da exportação Parquet

O BigQuery converte tipos de dados do 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)
Ponto flutuante	FLOAT	NONE
Booleano	BOOLEAN	NONE
String	BYTE_ARRAY	STRING (UTF8)
Bytes	BYTE_ARRAY	NONE
Data	INT32	DATE
Datetime	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Hora	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
Carimbo de data/hora	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

O esquema Parquet representa os dados aninhados como um grupo e registros repetidos como grupos repetidos. Para mais informações sobre como usar dados aninhados e repetidos no BigQuery, consulte Como especificar colunas aninhadas e repetidas.

Cuidado: se você exportar um tipo DATETIME para o Parquet, não será possível carregar o arquivo Parquet diretamente no mesmo esquema da tabela porque o valor convertido não corresponderá ao esquema.

É possível usar as seguintes soluções alternativas para tipos DATETIME:

• Carregue o arquivo em uma tabela de preparação. Em seguida, use uma consulta SQL para converter o campo em um DATETIME. Depois disso, salve o resultado em uma nova tabela. Para mais informações, consulte Como alterar o tipo de dados de uma coluna.
• Forneça um esquema para a tabela usando a sinalização --schema no job de carregamento. Defina a coluna de data e hora como col:DATETIME.

Exportar dados para um ou mais arquivos

A propriedade destinationUris indica um ou mais locais e nomes de arquivos em que o BigQuery deve exportar seus arquivos.

O BigQuery aceita um único operador de caractere curinga (*) para cada URI. Esse caractere pode ser usado em qualquer posição do URI, exceto como parte do nome do bucket. O uso do operador de caractere curinga faz com que o BigQuery crie vários arquivos fragmentados com base no padrão fornecido. Ele é substituído por um número de 12 dígitos preenchido à esquerda, começando por 0. Por exemplo, um URI com um caractere curinga no fim do nome do arquivo gera arquivos com 000000000000 anexado ao primeiro arquivo, 000000000001 anexado ao segundo e assim por diante.

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

Opções de destinationUris
URI único	Use um único URI se você estiver exportando dados de tabela com 1 GB ou menos. Essa opção é o caso de uso mais comum, porque os dados exportados geralmente são menores que o valor máximo de 1 GB. Essa opção não é compatível com a instrução EXPORT DATA. Use um único URI com caractere curinga. Definição da propriedade: ['gs://my-bucket/file-name.json'] Gera: gs://my-bucket/file-name.json
URI com um único caractere curinga	Use um URI com um único caractere coringa para exportar dados maiores do que o valor máximo de 1 GB. Os dados são fragmentados pelo BigQuery entre vários arquivos com base no padrão fornecido. O tamanho dos arquivos exportados varia. Se você usar um curinga em um componente do URI diferente do nome do arquivo, verifique se o componente do caminho não existe antes de exportar os dados. Definição da propriedade: ['gs://my-bucket/file-name-*.json'] Gera: gs://my-bucket/file-name-000000000000.json gs://my-bucket/file-name-000000000001.json gs://my-bucket/file-name-000000000002.json ...

Limitar o tamanho do arquivo exportado

Ao exportar mais de 1 GB de dados em uma única exportação, é preciso usar um caractere curinga para exportar os dados para vários arquivos e o tamanho dos arquivos terá variações. Se você precisar limitar o tamanho máximo de cada arquivo exportado, uma opção será particionar aleatoriamente os dados e, em seguida, exportar cada partição para um arquivo:

1. Determine o número de partições necessárias, que é igual ao tamanho total dos dados dividido pelo tamanho de arquivo exportado desejado. Por exemplo, se você tiver 8.000 MB de dados e quiser que cada arquivo exportado tenha aproximadamente 20 MB, precisará de 400 partições.

2. Crie uma nova tabela particionada e em cluster por uma nova coluna gerada aleatoriamente chamada export_id. O exemplo a seguir mostra como criar um novo processed_table usando uma tabela existente chamada source_table, que exige partições n para atingir o tamanho de arquivo desejado:

   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 instrução EXPORT DATA na seguinte consulta:

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

Extrair tabela compactada

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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 caso de uso:

Este exemplo mostra como exportar dados para o Cloud Storage.

Suponha que você esteja fazendo streaming contínuo de dados para o Cloud Storage a partir de registros do endpoint. Um snapshot diário precisa ser exportado para o Cloud Storage para fins de backup e arquivamento. A melhor opção é um job de extração sujeito a determinadas cotas e limitações.

Envie um job de extração com a API ou as bibliotecas de cliente, transmitindo um ID exclusivo como jobReference.jobId. Os jobs de extração são assíncronos. Verifique o status do job com o ID exclusivo usado na criação dele. O job foi concluído com sucesso se status.status for DONE. Se aparecer status.errorResult, o job falhou e precisará ser repetido.

Processamento de dados em lote

Suponha que um job em lote noturno seja usado para carregar dados até um prazo determinado. Depois que esse job de carregamento for concluído, uma tabela com estatísticas será materializada em uma consulta, conforme descrito na seção anterior. Os dados dessa tabela são recuperados e compilados em um relatório PDF e enviados a um regulador.

Como a quantidade de dados que precisa ser lida é pequena, use a API tabledata.list para recuperar todas as linhas da tabela no formato de dicionário JSON. Se houver mais de uma página de dados, os resultados terão a propriedade pageToken definida. Para recuperar 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 de API falhar com um erro 5xx, tente novamente com espera exponencial. A maioria dos erros 4xx não pode ser repetida. Para uma melhor separação entre as exportações do BigQuery e a geração de relatórios, os resultados devem ser mantidos no disco.

Política de cotas

Para mais informações sobre cotas de jobs de exportação, consulte Exportar jobs na página "Cotas e limites".

O uso de jobs de exportação está disponível no INFORMATION_SCHEMA. A entrada do job nas tabelas do sistema JOBS_BY_* do job de exportação contém um valor de total_processed_bytes que pode ser usado para monitorar o uso agregado e garantir que permaneça abaixo de 50 TB por dia. Para saber como consultar a visualização INFORMATION_SCHEMA.JOBS para conseguir o valor total_processed_bytes, consulte Receber bytes processados por jobs de exportação.

Conferir o uso atual da cota

É possível conferir seu uso atual de jobs de consulta, carregamento, extração ou cópia executando uma consulta INFORMATION_SCHEMA para visualizar metadados sobre os jobs executados em um período especificado. É possível comparar seu uso atual com o limite de cota para determinar o uso de cota para um tipo específico de job. O exemplo de consulta a seguir usa a visualização INFORMATION_SCHEMA.JOBS para listar o número de jobs 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-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

É possível configurar uma política de alertas do Cloud Monitoring que fornece notificações do número de bytes exportados.

1. No Console do Google Cloud, acesse a página Monitoring.

   Acessar Monitoring

2. No painel de navegação, selecione Metrics explorer.

3. No editor de consultas do MQL, configure um alerta para monitorar os bytes exportados por dia, conforme mostrado no exemplo a seguir:

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

4. Para configurar o alerta, clique em Executar consulta.

Para mais informações, consulte Políticas de alertas com a MQL.

Solução de problemas

Para diagnosticar problemas com jobs de extração, use a Análise de registros. para revisar os registros de um job de extração específico e identificar possíveis erros. O filtro da Análise de registros a seguir retorna informações sobre jobs 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 saber mais sobre os preços de exportação de dados, consulte a página de preços do BigQuery.

Depois que os dados forem exportados, você será cobrado pelo armazenamento deles no Cloud Storage. Para mais informações, consulte Preços do Cloud Storage.

Segurança de tabelas

Para controlar o acesso a tabelas no BigQuery, consulte Introdução aos controles de acesso a tabelas.

A seguir

• Para saber mais, consulte Como usar o console do Google Cloud.
• Para saber mais sobre a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.
• Para aprender a criar um aplicativo usando as bibliotecas de cliente da API BigQuery, consulte o Guia de início rápido da biblioteca de cliente.