Como carregar dados em lote

Carregue dados no BigQuery do Cloud Storage ou de um arquivo local como operação em lote. Os dados de origem podem estar em qualquer um destes formatos:

  • Avro
  • Valores separados por vírgula (CSV)
  • JSON (delimitado por nova linha)
  • ORC
  • Parquet
  • Exportações do Firestore armazenadas no Cloud Storage.

Você também pode usar o serviço de transferência de dados do BigQuery para configurar cargas recorrentes do Cloud Storage para o BigQuery.

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do BigQuery em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do BigQuery

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedem aos usuários as permissões necessárias para executar cada tarefa neste documento e crie um conjunto de dados para armazenamento.

Permissões necessárias

Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
  • bigquery.user (inclui a permissão bigquery.jobs.create)
  • bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

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

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar os dados.

Como carregar dados do Cloud Storage

O BigQuery é compatível com o carregamento de dados de qualquer uma das classes de armazenamento do Cloud Storage a seguir:

  • Standard
  • Nearline
  • Coldline
  • Archive

Para saber como carregar dados no BigQuery, consulte a página do seu formato de dados:

Para saber como configurar um carregamento recorrente do Cloud Storage para o BigQuery, consulte Transferências do Cloud Storage.

Considerações sobre o local

Quando você carrega dados do Cloud Storage usando uma tabela externa do BigLake ou que não seja BigLake, os dados carregados precisam ser colocados no mesmo local do conjunto de dados do BigQuery.

  • É possível carregar dados de um bucket do Cloud Storage localizado em qualquer local se o conjunto de dados do BigQuery estiver localizado na multirregião US."

  • Bucket multirregional: se o bucket do Cloud Storage que você quer carregar estiver localizado em um bucket multirregional, o conjunto de dados do BigQuery poderá estar no mesmo bucket multirregional ou qualquer região única que esteja incluída no mesmo bucket multirregional. Por exemplo, se o bucket do Cloud Storage estiver na região EU, o conjunto de dados do BigQuery poderá estar na multirregião EU ou em qualquer região única em EU.

  • Bucket birregional: se o bucket do Cloud Storage que você quer carregar estiver localizado em um bucket birregional, o conjunto de dados do BigQuery poderá estar localizado em regiões incluídas no bucket birregional ou em uma multirregião que inclui a região birregional. Por exemplo, se o bucket do Cloud Storage estiver localizado na região EUR4, seu conjunto de dados do BigQuery poderá estar localizado na Finlândia (europe-north1) em uma região única, nos Países Baixos (europe-west4) uma região única ou na multirregião EU.

    Para mais informações, consulte Criar um bucket birregional

  • Bucket de região única: se o bucket do Cloud Storage que você quer carregar estiver em uma única região, o conjunto de dados do BigQuery poderá estar na mesma região única ou no multirregional que inclui a região única. Por exemplo, se o bucket do Cloud Storage estiver na região da Finlândia (europe-north1), o conjunto de dados do BigQuery poderá estar na Finlândia ou na multirregião EU.

  • Uma exceção é que, se o conjunto de dados do BigQuery estiver localizado na região asia-northeast1, o bucket do Cloud Storage poderá estar localizado na multirregião EU.

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

Não é possível alterar o local de um conjunto de dados após a criação, mas é possível fazer uma cópia dele ou movê-lo manualmente. Veja mais informações em:

Como recuperar o URI do Cloud Storage

Para carregar dados de uma fonte do Cloud Storage, é preciso fornecer o URI dele.

O caminho do recurso do Cloud Storage contém o nome do bucket e o objeto (nome do arquivo). Por exemplo, se o bucket do Cloud Storage se chamar mybucket e o arquivo de dados for denominado myfile.csv, o caminho de recurso será gs://mybucket/myfile.csv.

O BigQuery não oferece suporte a caminhos de recursos do Cloud Storage que incluam 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.

Para recuperar o caminho do recurso do Cloud Storage:

  1. Abra o Console do Cloud Storage.

    Console do Cloud Storage

  2. Procure a localização do objeto (arquivo) que contém os dados de origem.

  3. Clique no nome do objeto.

    A página Detalhes do objeto é aberta.

  4. Copie o valor fornecido no campo gsutil URI, que começa com gs://.

Nas exportações do Google Datastore, só é possível especificar um URI, que precisa terminar com .backup_info ou .export_metadata.

Compatibilidade com caracteres curinga para URIs do Cloud Storage

Se os dados estiverem separados em vários arquivos, use um caractere curinga (*) para selecionar vários arquivos. O uso do caractere curinga de asterisco precisa seguir estas regras:

  • O caractere curinga pode ser exibido dentro ou no final do nome do objeto.
  • Não é possível usar vários asteriscos. Por exemplo, o caminho gs://mybucket/fed-*/temp/*.csv é inválido.
  • Não é possível usar um asterisco com o nome do bucket.

Exemplos:

  • O exemplo a seguir mostra como selecionar todos os arquivos em todas as pastas que começam com o prefixo gs://mybucket/fed-samples/fed-sample:

    gs://mybucket/fed-samples/fed-sample*

  • O exemplo a seguir mostra como selecionar apenas arquivos com uma extensão .csv na pasta chamada fed-samples e em qualquer subpasta de fed-samples:

    gs://mybucket/fed-samples/*.csv

  • O exemplo a seguir mostra como selecionar arquivos com um padrão de nomenclatura de fed-sample*.csv na pasta chamada fed-samples. Este exemplo não seleciona arquivos em subpastas de fed-samples.

    gs://mybucket/fed-samples/fed-sample*.csv

Ao usar a ferramenta de linha de comando bq, talvez seja necessário evitar o asterisco em algumas plataformas.

Não é possível usar um caractere curinga de asterisco ao carregar dados de exportação do Datastore ou do Firestore pelo Cloud Storage.

Limitações

Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:

  • Se o local do conjunto de dados estiver definido como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados.
  • O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.
  • O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.

Dependendo do formato dos dados de origem do Cloud Storage, pode haver outras limitações. Veja mais informações aqui:

Como carregar dados de arquivos locais

É possível carregar dados de uma fonte legível (como sua máquina local) usando uma das seguintes opções:

  • Console do Google Cloud
  • o comando bq load da ferramenta de linha de comando bq
  • A API
  • As bibliotecas de cliente

Quando você carrega dados usando o console do Google Cloud ou a ferramenta de linha de comando bq, um job de carregamento é criado automaticamente.

Para carregar dados de uma fonte de dados local:

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 selecione um conjunto de dados.

  3. Expanda a opção Ações e clique em Abrir.

  4. No painel de detalhes, clique em Criar tabela .

  5. Na página Criar tabela, na seção Origem:

    • Em Criar tabela de, selecione Fazer upload.
    • Em Selecionar arquivo, clique em Procurar.
    • Encontre o arquivo e clique em Abrir. Observe que os caracteres curinga e as listas separadas por vírgulas não são compatíveis com arquivos locais.
    • Em Formato do arquivo, selecione (CSV), JSON (delimitado por nova linha), Avro, Parquet ou ORC.

  6. Na página Criar tabela, na seção Destino:

    • Em Projeto, escolha o projeto adequado.
    • Em Conjunto de dados, escolha o conjunto de dados adequado.
    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.
    • Verifique se o Tipo de tabela está definido como Tabela nativa.

  7. Na seção Esquema, insira a definição do esquema.

    • Em arquivos CSV e JSON, marque a opção Detectar automaticamente para ativar a detecção automática de esquema. As informações de esquema são autodescritas nos dados de origem para outros tipos de arquivos compatíveis.

    • Outra opção é inserir informações de esquema manualmente:

      • Clique em Editar como texto e insira o esquema da tabela como uma matriz JSON:

      • Use Adicionar campo para inserir manualmente o esquema.

  8. Selecione itens aplicáveis na seção Opções avançadas. Para informações sobre as opções disponíveis, consulte Opções de CSV e Opções de JSON.

  9. Opcional: em Opções avançadas, selecione a disposição de gravação:

    • Gravar apenas se a tabela estiver vazia: grave os dados somente se a tabela estiver vazia.
    • Anexar à tabela: anexa os dados no final da tabela. Essa configuração é a padrão.
    • Substituir tabela: apague todos os dados atuais na tabela antes de gravar os novos.

  10. Clique em Criar tabela.

bq

Use o comando bq load, especifique o source_format e inclua o caminho para o arquivo local.

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

Se você estiver carregando dados em um projeto diferente do projeto padrão, adicione o ID do projeto ao conjunto de dados usando o seguinte formato: PROJECT_ID:DATASET.

bq --location=LOCATION load \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Substitua:

  • LOCATION: seu local. A sinalização --location é opcional. Por exemplo, se você 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: CSV, AVRO, PARQUET, ORC, ou NEWLINE_DELIMITED_JSON.
  • project_id: o ID do projeto.
  • dataset: um conjunto de dados existente.
  • table: o nome da tabela em que você está carregando dados.
  • path_to_source: o caminho para o arquivo local.
  • schema: um esquema válido. É possível que ele seja um arquivo JSON local ou inserido in-line como parte do comando. Também é possível usar a sinalização --autodetect em vez de fornecer uma definição de esquema.

Além disso, é possível adicionar sinalizações para opções que permitem controlar como o BigQuery analisa seus dados. Por exemplo, use a sinalização --skip_leading_rows para ignorar linhas de cabeçalho em um arquivo CSV. Para mais informações, consulte Opções de CSV e Opções de JSON.

Por exemplo:

O comando a seguir carrega um arquivo JSON delimitado por nova linha (mydata.json) em uma tabela chamada mytable em mydataset em seu projeto padrão. O esquema é definido em um arquivo de esquema local denominado myschema.json.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

O comando a seguir carrega um arquivo CSV local (mydata.csv) em uma tabela chamada mytable em mydataset e em myotherproject. O esquema é definido in-line no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE.

    bq load \
    --source_format=CSV \
    myotherproject:mydataset.mytable \
    ./mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

O comando a seguir carrega um arquivo CSV local (mydata.csv) em uma tabela chamada mytable em mydataset em seu projeto padrão. O esquema é definido por meio da detecção automática de esquema.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    ./mydata.csv

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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, use a classe de opções de atualização referente ao formato apropriado da classe base JobCreationOptions em vez de UploadCsvOptions.


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina a propriedade DataFormat de NewReaderSource com o formato apropriado.

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

	job, err := loader.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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina as FormatOptions com o formato apropriado.

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina o parâmetro metadata da função load com o formato apropriado.

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function loadLocalFile() {
  // Imports a local file into a table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const filename = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

  console.log(`Job ${job.id} completed.`);

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

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina sourceFormat com o formato apropriado.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';
// $tableId    = 'The BigQuery table ID';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina a propriedade LoadJobConfig.source_format com o formato apropriado.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

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.

O código a seguir demonstra como carregar um arquivo CSV local em uma nova Tabela do BigQuery. Para carregar um arquivo local de outro formato, defina o parâmetro format do método Table#load_job com o formato apropriado.

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows into #{table.id}"
end

Limitações

O carregamento de dados a partir de uma fonte de dados local está sujeito às seguintes limitações:

  • Os caracteres curinga e as listas separadas por vírgulas não são compatíveis com o carregamento de arquivos de uma fonte de dados local. Os arquivos precisam ser carregados individualmente.
  • Ao usar o console do Google Cloud, os arquivos carregados de uma fonte de dados local não podem exceder 100 MB. Para arquivos maiores, carregue o arquivo do Cloud Storage.

Como carregar dados compactados e descompactados

Para os formatos Avro, Parquet e ORC, o BigQuery permite carregar arquivos em que os dados foram compactados usando um codec compatível. No entanto, o BigQuery não é compatível com carregamento de arquivos nesses formatos que foram compactados, por exemplo, usando o utilitário gzip.

O formato binário Avro é o formato preferido para carregar dados compactados e não compactados. O carregamento de dados Avro é mais rápido porque eles podem ser lidos em paralelo mesmo quando os blocos de dados estão compactados. Para conferir uma lista de codecs de compactação compatíveis, consulte Compactação Avro.

O formato binário Parquet também é uma boa opção, porque a eficiente codificação por coluna do Parquet normalmente resulta em uma taxa de compactação melhor e em arquivos menores. Os arquivos Parquet também aproveitam as técnicas de compactação em que é possível carregar os arquivos em paralelo. Para conferir uma lista de codecs de compactação compatíveis, consulte Compactação Parquet.

O formato binário ORC oferece benefícios semelhantes aos do formato Parquet. O carregamento de dados nos arquivos ORC é rápido porque as faixas de dados podem ser lidas em paralelo. As linhas em cada faixa de dados são carregadas sequencialmente. Para otimizar o tempo de carregamento, use um tamanho de faixa de dados de aproximadamente 256 MB ou menos. Para conferir uma lista de codecs compatíveis, consulte Compactação ORC.

Para outros formatos de dados, como CSV e JSON, o carregamento de arquivos não compactados no BigQuery pode ser feito muito mais rápido do que o carregamento de arquivos compactados, porque os não compactados podem ser lidos em paralelo. Como os arquivos não compactados são maiores, usá-los pode causar limitações de largura de banda e custos mais elevados com o Google Cloud Storage para dados organizados no Google Cloud Storage antes do carregamento no BigQuery. Lembre-se de que a ordenação em linha não é garantida para arquivos compactados ou não compactados. É importante ponderar essas desvantagens, dependendo do caso de uso.

Em geral, se a largura de banda for limitada, compacte os arquivos CSV e JSON usando gzip antes de fazer o upload deles para o Cloud Storage. gzip é o único tipo de compactação de arquivos compatível com arquivos CSV e JSON ao carregar dados no BigQuery. Se a velocidade de carregamento for importante para o aplicativo e você tiver muita largura de banda para carregar seus dados, não compacte os arquivos.

Como anexar ou substituir uma tabela

É possível carregar mais dados para uma tabela de arquivos de origem ou anexando resultados de consultas. Se o esquema dos dados não corresponder ao da tabela ou partição de destino, você poderá substitui-lo ou atualizá-lo quando anexar à tabela.

Quando você atualiza o esquema anexando dados, o BigQuery permite:

  • adicionar novos campos;
  • relaxar os campos REQUIRED para NULLABLE.

Ao substituir uma tabela, o esquema é sempre alterado. Nesse processo, as atualizações de esquema não são restritas.

No console do Google Cloud, use a opção Preferência de gravação para especificar qual ação será executada ao carregar dados de um arquivo de origem ou de um resultado de consulta. A ferramenta de linha de comando bq e a API incluem as seguintes opções:

Opção do console flag da ferramenta bq Propriedade da API BigQuery Descrição
Gravar apenas se a tabela estiver vazia Nenhuma WRITE_EMPTY Grava dados apenas se a tabela estiver vazia.
Anexar à tabela --noreplace ou --replace=false; se --replace não for especificado, o padrão será anexado WRITE_APPEND (Padrão) Anexa os dados ao final da tabela.
Substituir tabela --replace ou --replace=true WRITE_TRUNCATE Apaga todos os dados da tabela antes de gravar os novos.

Política de cotas

Para informações sobre a política de cotas para carregamento de dados em lote, consulte Jobs de carregamento na página "Cotas e limites".

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

Preços

Atualmente, não há cobrança pelo carregamento de dados em lote no BigQuery. Para mais informações, consulte Preços de ingestão de dados do BigQuery.

Exemplo de caso de uso:

Suponha que haja um pipeline de processamento em lote durante a noite que precise ser concluído até um prazo fixo. Os dados precisam estar disponíveis até esse prazo para passarem por outro processo em lote a fim de gerar relatórios que serão enviados a um regulador. Esse caso de uso é comum em setores regulamentados, como o financeiro.

O carregamento de dados em lote com jobs é a abordagem correta para esse caso de uso, porque a latência não é um problema desde que o prazo seja cumprido. Verifique se os buckets do Cloud Storage atendem aos requisitos de local para carregar dados no conjunto de dados do BigQuery.

O resultado de um job de carga do BigQuery é atômico; ou todos os registros são inseridos ou nenhum deles. Como prática recomendada, ao inserir todos os dados em um único job de carregamento, crie uma nova tabela usando a disposição WRITE_TRUNCATE do recurso JobConfigurationLoad. Isso é importante ao repetir um job de carregamento com falha, já que o cliente pode não conseguir distinguir entre os jobs que falharam e a falha causada, por exemplo, na comunicação do estado de sucesso de volta ao cliente.

Partindo do princípio que os dados a serem ingeridos já foram copiados para o Cloud Storage, tentar novamente com espera exponencial é suficiente para resolver falhas de ingestão.

É recomendável que um job em lote noturno não atinja a cota padrão de 1.500 carregamentos por tabela por dia, mesmo com novas tentativas. Ao carregar dados gradualmente, a cota padrão é suficiente para executar um job de carregamento a cada cinco minutos e ainda tem espaço para, em média, pelo menos uma nova tentativa por job.