Como carregar dados CSV do Cloud Storage

Como carregar arquivos CSV do Cloud Storage

Ao carregar dados CSV do Cloud Storage, você pode anexá-los ou substituir uma tabela ou partição existente. Também é possível carregá-los em uma nova tabela ou partição. Quando os dados são carregados no BigQuery, eles são convertidos para o Capacitor (em inglês), o formato de armazenamento em colunas do BigQuery.

Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que contém a tabela precisa estar na mesma região ou multirregião que o bucket do Cloud Storage.

Para saber mais sobre como carregar dados CSV de um arquivo local, consulte Como carregar dados ao BigQuery de uma fonte de dados local.

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

Limitações

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

• Se a localização do conjunto de dados estiver definida como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar no mesmo local 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á.

Ao carregar arquivos CSV no BigQuery, observe estas observações:

• Os arquivos CSV não são compatíveis com dados aninhados ou repetidos.
• Remova os caracteres de marca de ordem de byte (BOM). Eles podem causar problemas inesperados.
• Se você usa a compactação gzip, o BigQuery não consegue ler os dados em paralelo. O carregamento de dados CSV compactados no BigQuery é mais lento do que os não compactados. Consulte Como carregar dados compactados e descompactados.
• Não é possível incluir arquivos compactados e descompactados no mesmo job de carga.
• O tamanho máximo de um arquivo gzip é de 4 GB.
• Ao carregar dados CSV ou JSON, os valores nas colunas DATE precisam usar o traço (-) e a data precisa estar no seguinte formato: YYYY-MM-DD (ano-mês-dia).
• Ao carregar dados JSON ou CSV, os valores nas colunas TIMESTAMP precisam usar um traço (-) para a parte da data do carimbo de data/hora, e a data precisa estar no seguinte formato: YYYY-MM-DD (ano-mês-dia). A parte hh:mm:ss (hora-minuto-segundo) do carimbo de data/hora precisa usar um separador de dois pontos (:).

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 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 carregar dados de um bucket do Cloud Storage, você precisa das seguintes permissões do IAM:

• storage.objects.get
• storage.objects.list (obrigatório se você estiver usando um caractere curinga de URI)

O papel predefinido do IAM roles/storage.objectViewer inclui todas as permissões necessárias para carregar dados de um bucket do Cloud Storage.

Como carregar dados CSV em uma tabela

É possível carregar dados CSV do Cloud Storage em uma nova tabela do BigQuery com um destes métodos:

• Como usar o console do Google Cloud
• Use o comando bq load da ferramenta de linha de comando bq.
• Chame o método da API jobs.insert e configure um job load.
• usando as bibliotecas de cliente.

Para carregar os dados CSV do Cloud Storage em uma nova tabela do BigQuery:

Console

---

Para orientações passo a passo sobre esta tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientações

---

As seções a seguir guiam você pelas mesmas etapas que você encontra clicando em Orientações.

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato de arquivo, selecione CSV.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, insira a definição do esquema. Para ativar a detecção automática de um esquema, selecione Detecção automática. É possível inserir as informações do esquema manualmente usando um dos seguintes métodos:
   • Opção 1: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON. É possível visualizar o esquema de uma tabela existente no formato JSON inserindo o seguinte comando:

         bq show --format=prettyjson dataset.table
         

   • Opção 2: clique em Adicionar campo e insira o esquema da tabela. Especifique o Nome, o Tipo e o Modo de cada campo.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
   • Em Número de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará. Essa opção se refere apenas a arquivos CSV e JSON.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Personalizado. Se você escolher Personalizado, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
   • Em Linhas de cabeçalho a serem ignoradas, insira o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
   • Em Novas linhas com consulta, marque Permitir novas linhas com consulta para permitir seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é false.
   • Em Linhas dentadas, marque Permitir linhas dentadas para aceitar linhas em arquivos CSV em que as colunas opcionais no final estejam faltando. Os valores ausentes são tratados como nulos. Se a opção não for marcada, os registros com ausência de colunas posteriores serão tratados como registros corrompidos e, se houver muitos desses registros, será retornado um erro inválido no resultado do job. O valor padrão é false.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

Observação: ao carregar dados em uma tabela vazia usando o console do Google Cloud, não será possível adicionar um identificador, uma descrição ou uma validade de tabela ou de partição.

Após a criação da tabela, é possível atualizar a validade, a descrição e os identificadores dela. No entanto, não é possível adicionar uma validade de partição depois de criar uma tabela com o console do Google Cloud. Para mais informações, consulte Como gerenciar tabelas.

bq

Use o comando bq load, especifique CSV usando a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga. Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática de esquemas. Se você não especificar um esquema, e --autodetect for false e a tabela de destino existir, o esquema da tabela de destino será usado.

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

Estas são outras sinalizações opcionais:

• --allow_jagged_rows: quando especificada, aceita linhas em arquivos CSV que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é false.
• --allow_quoted_newlines: quando especificada, permite seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é false.
• --field_delimiter: o caractere que indica o limite entre colunas nos dados. \t e tab são permitidos como delimitadores de tabulação. O valor padrão é ,.
• --null_marker: uma string personalizada opcional que representa um valor NULL nos dados CSV.
• --skip_leading_rows: especifica o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
• --quote: o caractere de aspas a ser usado antes e depois dos registros. O valor padrão é ". Para indicar nenhum caractere de aspas, use uma string vazia.
• --max_bad_records: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
• --ignore_unknown_values: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
• --autodetect: quando especificada, ativa a detecção automática de esquemas em dados CSV e JSON.
• --time_partitioning_type: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição padrão para o particionamento baseado em tempo é DAY. Não é possível alterar a especificação de particionamento em uma tabela existente.
• --time_partitioning_expiration: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.
• --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se o particionamento baseado em tempo for ativado sem esse valor, será criada uma tabela particionada por tempo de processamento.
• --require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que especifica as partições a serem consultadas. A exigência de um filtro de particionamento pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas.
• --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.

• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

  Para mais informações sobre o comando bq load, consulte:

  • Referência de linha de comando

  Para mais informações sobre tabelas particionadas, consulte:

  • Como criar tabelas particionadas

  Para mais informações sobre tabelas em cluster, consulte:

  • Como criar e usar tabelas em cluster

  Para mais informações sobre a criptografia de tabelas, consulte:

  • Como proteger dados com chaves do Cloud KMS

Para carregar dados CSV no BigQuery, insira o comando a seguir:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source \
schema

Em que:

• location é o local. A sinalização --location é opcional. Por exemplo, se você estiver usando 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.
• dataset é um conjunto de dados atual;
• table é o nome da tabela em que você carregará dados;
• path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.
• schema é um esquema válido. Ele pode ser 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.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela chamada mytable em mydataset. O esquema é definido em um arquivo de esquema local chamado myschema.json.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela chamada mytable em mydataset. O esquema é definido em um arquivo de esquema local chamado myschema.json. O arquivo CSV inclui duas linhas de cabeçalho. Se --skip_leading_rows não for especificado, o comportamento padrão será supor que o arquivo não contenha cabeçalhos.

    bq load \
    --source_format=CSV \
    --skip_leading_rows=2
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela particionada por tempo de ingestão chamada mytable em mydataset. O esquema é definido em um arquivo de esquema local chamado myschema.json.

    bq load \
    --source_format=CSV \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela particionada denominada mytable em mydataset. A tabela é particionada na coluna mytimestamp. O esquema é definido em um arquivo de esquema local chamado myschema.json.

    bq load \
    --source_format=CSV \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela chamada mytable em mydataset. O esquema é detectado automaticamente.

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

O comando a seguir carrega dados de gs://mybucket/mydata.csv em uma tabela chamada mytable em mydataset. O esquema é definido in-line no formato field:data_type,field:data_type.

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

Observação: quando você especifica o esquema usando a ferramenta de linha de comando bq, não é possível incluir um tipo RECORD (STRUCT), não é possível incluir uma descrição de campo nem especificar o modo de campo. Todos os modos de campo assumem NULLABLE como padrão. Para incluir descrições de campos, modos e tipos RECORD, forneça um arquivo de esquema JSON.

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O URI do Cloud Storage usa um caractere curinga. O esquema é detectado automaticamente.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata*.csv

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O comando inclui uma lista separada por vírgulas de URIs do Cloud Storage com caracteres curinga. O esquema é definido em um arquivo de esquema local chamado myschema.json.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    "gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
    ./myschema.json

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

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

3. A propriedade source URIs precisa ser totalmente qualificada no formato gs://bucket/object. Cada URI pode conter um caractere curinga "*".

4. Defina a propriedade sourceFormat como CSV para especificar o formato de dados CSV.

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

   • status.state = DONE indica que o job foi concluído.
   • A propriedade status.errorResult mostra que houve falha na solicitação e o objeto incluirá informações que descrevem o erro. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados.
   • A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que haja alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

• Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.

• Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job de carregamento. 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 do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID do job 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#.

Ver no GitHub Feedback

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

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"

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

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(projectID, datasetID, tableID 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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.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.

Ver no GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load CSV data from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcs {

  public static void runLoadCsvFromGcs() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadCsvFromGcs(datasetName, tableName, sourceUri, schema);
  }

  public static void loadCsvFromGcs(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("CSV from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \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 Node.js.

Ver no GitHub Feedback

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  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 PHP.

Ver no GitHub Feedback

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';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('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 para 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.

Use o método Client.load_table_from_uri() para carregar dados de um arquivo CSV no Cloud Storage. Forneça uma definição de esquema explícita. Para isso, defina a propriedade LoadJobConfig.schema para uma lista de objetos SchemaField (links em inglês).

Ver no GitHub Feedback

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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Antes de testar esta amostra, siga as instruções de configuração para 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 Ruby.

Ver no GitHub Feedback

require "google/cloud/bigquery"

def load_table_gcs_csv dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

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

Como carregar dados CSV em uma tabela que usa o particionamento de tempo baseado em colunas

Para carregar dados CSV do Cloud Storage em uma tabela do BigQuery que usa o particionamento de tempo baseado em colunas, faça o seguinte:

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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"time"

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

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID 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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.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.

Ver no GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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(datasetName, tableName);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \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 Node.js.

Ver no GitHub Feedback

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_new_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);
}

Python

Antes de testar esta amostra, siga as instruções de configuração para 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.

Ver no GitHub Feedback

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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Wait for the job to complete.

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

Como anexar ou substituir uma tabela com dados CSV

Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.

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.

Você tem as seguintes opções ao carregar mais dados em uma tabela:

Opção do console	Sinalização da ferramenta bq	Propriedade da API BigQuery	Descrição
Gravar apenas se a tabela estiver vazia	Incompatível	WRITE_EMPTY	Grava dados apenas se a tabela estiver vazia.
Anexar à tabela	--noreplace ou --replace=false; se --[no]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. Essa ação também exclui o esquema da tabela e remove qualquer chave do Cloud KMS.

Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.

É possível anexar ou substituir uma tabela:

• Como usar o console do Google Cloud
• Use o comando bq load da ferramenta de linha de comando bq.
• Chame o método da API jobs.insert e configure um job load.
• Como usar bibliotecas de cliente

Observação: nesta página, não é abordado como anexar ou substituir tabelas particionadas. Para informações sobre esse assunto, consulte Como anexar e substituir dados de tabelas particionadas.

Console

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato de arquivo, selecione CSV.
Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, insira a definição do esquema. Para ativar a detecção automática de um esquema, selecione Detecção automática. É possível inserir as informações do esquema manualmente usando um dos seguintes métodos:
   • Opção 1: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON. É possível visualizar o esquema de uma tabela existente no formato JSON inserindo o seguinte comando:

         bq show --format=prettyjson dataset.table
         

   • Opção 2: clique em Adicionar campo e insira o esquema da tabela. Especifique o Nome, o Tipo e o Modo de cada campo.
   Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster. Não é possível anexar ou substituir uma tabela para convertê-la em uma particionada ou em cluster. O console do Cloud não é compatível com anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
   • Em Número de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará. Essa opção se refere apenas a arquivos CSV e JSON.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Personalizado. Se você escolher Personalizado, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
   • Em Linhas de cabeçalho a serem ignoradas, insira o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
   • Em Novas linhas com consulta, marque Permitir novas linhas com consulta para permitir seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é false.
   • Em Linhas dentadas, marque Permitir linhas dentadas para aceitar linhas em arquivos CSV em que as colunas opcionais no final estejam faltando. Os valores ausentes são tratados como nulos. Se a opção não for marcada, os registros com ausência de colunas posteriores serão tratados como registros corrompidos e, se houver muitos desses registros, será retornado um erro inválido no resultado do job. O valor padrão é false.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

bq

Use o comando bq load, especifique CSV usando a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.

Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática do esquema. Se você não especificar um esquema, e --autodetect for false e a tabela de destino existir, o esquema da tabela de destino será usado.

Especifique a sinalização --replace para substituir a tabela. Use a sinalização --noreplace para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados.

É possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carga, consulte Como modificar esquemas de tabela.

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

Estas são outras sinalizações opcionais:

• --allow_jagged_rows: quando especificada, aceita linhas em arquivos CSV que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se a opção não for marcada, os registros com colunas posteriores ausentes serão tratados como registros corrompidos e, se houver muitos registros dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é false.
• --allow_quoted_newlines: quando especificada, permite seções de dados entre aspas que contêm caracteres de nova linha em um arquivo CSV. O valor padrão é false.
• --field_delimiter: o caractere que indica o limite entre colunas nos dados. \t e tab são permitidos como delimitadores de tabulação. O valor padrão é ,.
• --null_marker: uma string personalizada opcional que representa um valor NULL nos dados CSV.
• --skip_leading_rows: especifica o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
• --quote: o caractere de aspas a ser usado antes e depois dos registros. O valor padrão é ". Para indicar nenhum caractere de aspas, use uma string vazia.
• --max_bad_records: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
• --ignore_unknown_values: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
• --autodetect: quando especificado, ativa a detecção automática de esquemas em dados CSV e JSON.
• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source \
schema

onde:

• location é o local. A sinalização --location é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
• format é CSV;
• dataset é um conjunto de dados atual;
• table é o nome da tabela em que você carregará dados;
• path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.
• schema é um esquema válido. Ele pode ser 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.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.csv e substitui uma tabela chamada mytable em mydataset. O esquema é definido por meio da detecção automática de esquemas.

    bq load \
    --autodetect \
    --replace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

O seguinte comando carrega dados de gs://mybucket/mydata.csv e anexa dados a uma tabela chamada mytable em mydataset. O esquema é definido por um arquivo de esquema JSON – myschema.json.

    bq load \
    --noreplace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

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

3. A propriedade source URIs precisa ser totalmente qualificada no formato gs://bucket/object. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são compatíveis.

4. Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como CSV.

5. Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

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.

Ver no GitHub Feedback

import (
	"context"
	"fmt"

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

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(projectID, datasetID, tableID 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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.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.

Ver no GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a CSV file from GCS
public class LoadCsvFromGcsTruncate {

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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(datasetName, tableName);

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job loadJob = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \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 Node.js.

Para substituir as linhas de uma tabela atual, defina o valor writeDisposition no parâmetro metadata como 'WRITE_TRUNCATE'.

Ver no GitHub Feedback

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  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;
  }
}

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

Ver no GitHub Feedback

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';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('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 para 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 substituir linhas em uma tabela, defina a propriedade LoadJobConfig.write_disposition como a constante WRITE_TRUNCATE do SourceFormat (links em inglês).

Ver no GitHub Feedback

import six

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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = six.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.CSV,
    skip_leading_rows=1,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Como carregar dados CSV particionados do Hive

Com o BigQuery, é possível carregar dados CSV particionados do Hive que estejam armazenados no Cloud Storage. A ferramenta preenche as colunas particionadas do Hive como colunas na tabela de destino gerenciada pelo BigQuery. Para mais informações, consulte Como carregar dados particionados externamente do Cloud Storage.

Detalhes do carregamento de dados CSV

Nesta seção, descrevemos como o BigQuery lida com várias opções de formatação CSV.

Codificação

Para o BigQuery, é necessário que os dados CSV estejam codificados em UTF-8. Se você tiver arquivos CSV com dados codificados no formato ISO-8859-1 (também conhecido como Latin-1), especifique explicitamente a codificação para que o BigQuery possa converter adequadamente os dados para UTF-8.

Se você não especificar uma codificação ou especificar a codificação UTF-8 quando o arquivo CSV não estiver codificado em UTF-8, o BigQuery tentará converter os dados em UTF-8. Geralmente, seus dados são carregados com sucesso, mas podem não corresponder byte por byte àquilo que você espera. Para evitar isso, especifique a codificação correta usando a sinalização --encoding.

Observação: por padrão, se o arquivo CSV contiver o caractere ASCII 0 (NULL), não será possível carregar os dados no BigQuery. Para permitir o ASCII 0 e outros caracteres de controle ASCII, defina --preserve_ascii_control_characters=true para os jobs de carregamento.

Se o BigQuery não conseguir converter um caractere diferente do caractere ASCII 0, o BigQuery converterá o caractere para o caractere de substituição Unicode padrão: �.

Delimitadores de campos

Em arquivos CSV, os delimitadores podem ser qualquer caractere de um byte. Se o arquivo de origem usar a codificação ISO-8859-1, qualquer caractere poderá ser um delimitador. Se o arquivo de origem usar a codificação UTF-8, qualquer caractere no intervalo decimal de 1-127 (U+0001-U+007F) poderá ser usado sem modificação. É possível inserir um caractere ISO-8859-1 fora desse intervalo como um delimitador, e o BigQuery o interpretará corretamente. No entanto, se você usar um caractere de vários bytes como delimitador, alguns dos bytes serão interpretados como parte do valor do campo.

Normalmente, é uma prática recomendada usar um delimitador padrão, como tabulação, barra vertical ou vírgula. O padrão é uma vírgula.

Tipos de dados

Boolean. O BigQuery pode analisar qualquer um dos seguintes pares de dados booleanos: 1 ou 0, true ou false, t ou f, yes ou no e y ou n (indiferente a maiúsculas). A detecção automática de esquema detecta qualquer um desses elementos automaticamente, exceto 0 e 1.

Bytes. As colunas com tipos BYTES precisam ser codificadas como Base64.

Date. As colunas com tipos DATE precisam estar no formato YYYY-MM-DD.

Datetime. As colunas com tipos DATETIME precisam estar no formato YYYY-MM-DD HH:MM:SS[.SSSSSS].

Geografia. Colunas com tipos GEOGRAPHY precisam conter strings em um dos seguintes formatos:

• Texto conhecido (WKT)
• Binário conhecido (WKB)
• GeoJSON

Se você usar WKB, o valor será codificado em hexadecimal.

A lista a seguir mostra exemplos de dados válidos:

• WKT: POINT(1 2)
• GeoJSON: { "type": "Point", "coordinates": [1, 2] }
• WKB codificado em hexadecimal: 0101000000feffffffffffef3f0000000000000040

Antes de carregar dados GEOGRAPHY, leia também Como carregar dados geoespaciais.

Interval. As colunas com tipos INTERVAL precisam estar no formato Y-M D H:M:S[.F], em que:

• Y = Ano. O intervalo aceito é de 0 a 10.000.
• M = Mês. O intervalo aceito é de 1 a 12.
• D = Dia. O intervalo aceito é de 1 a [último dia do mês indicado].
• H = Hora.
• M = Minuto.
• S: segundo
• [.F] = Frações de um segundo de até seis dígitos, com precisão de microssegundos.

É possível indicar um valor negativo adicionando um traço (-).

A lista a seguir mostra exemplos de dados válidos:

• 10-6 0 0:0:0
• 0-0 -5 0:0:0
• 0-0 0 0:0:1.25

Para carregar dados INTERVAL, use o comando bq load e use a sinalização --schema para especificar um esquema. Não é possível fazer upload de dados INTERVAL usando o console.

Horário. As colunas com tipos TIME precisam estar no formato HH:MM:SS[.SSSSSS].

Timestamp. O BigQuery aceita vários formatos de carimbo de data/hora. O carimbo de data/hora precisa incluir uma parte de data e de hora.

• A parte da data pode ser formatada como YYYY-MM-DD ou YYYY/MM/DD.

• A parte do carimbo de data/hora precisa ser formatada como HH:MM[:SS[.SSSSSS]] (segundos e frações de segundos são opcionais).

• A data e a hora precisam ser separadas por um espaço ou "T".

• Opcionalmente, a data e a hora podem ser seguidas por um deslocamento de UTC ou um regulador de fuso horário do UTC (Z). Para mais informações, consulte Fusos horários.

Por exemplo, qualquer um dos valores de carimbo de data/hora a seguir é válido:

• 2018-08-19 12:11
• 2018-08-19 12:11:35
• 2018-08-19 12:11:35.22
• 2018/08/19 12:11
• 2018-07-05 12:54:00 UTC
• 2018-08-19 07:11:35.220 -05:00
• 2018-08-19T12:11:35.220Z

Se você fornecer um esquema, o BigQuery também aceitará a era Unix para valores de carimbo de data/hora. No entanto, a detecção automática de esquema não detecta esse caso e trata o valor como um tipo numérico ou string.

Exemplos de valores de carimbo de data/hora da era Unix:

• 1534680695
• 1.534680695e11

Detecção automática de esquema

Esta seção descreve o comportamento da detecção automática de esquema ao carregar arquivos CSV.

Delimitador CSV

O BigQuery detecta os seguintes delimitadores:

• vírgula (,)
• barra vertical (|)
• Tabulação (\t)

Cabeçalho CSV

No BigQuery, os cabeçalhos são inferidos pela comparação da primeira linha do arquivo com outras linhas no conjunto de dados. Se houver apenas strings na primeira linha e nas outras linhas houver outros tipos de dados, o BigQuery presumirá que a primeira linha é de cabeçalho. Nesse caso, o BigQuery atribui nomes de coluna com base nos nomes dos campos da linha do cabeçalho. Os nomes podem ser modificados para atender às regras de nomenclatura de colunas no BigQuery. Por exemplo, os espaços serão substituídos por sublinhados.

Caso contrário, o BigQuery considera que a primeira linha é de dados e atribui nomes de coluna genéricos, como string_field_1. Depois que uma tabela é criada, não é possível atualizar os nomes das colunas no esquema, mas é possível alterá-los manualmente. Outra opção é fornecer um esquema explícito em vez de usar a detecção automática.

É possível ter um arquivo CSV com uma linha de cabeçalho, em que todos os campos de dados são strings. Nesse caso, o BigQuery não detectará automaticamente que a primeira linha é um cabeçalho. Use a opção --skip_leading_rows para pular a linha do cabeçalho. Caso contrário, o cabeçalho será importado como dados. Considere também fornecer um esquema explícito neste caso, para que seja possível atribuir nomes de coluna.

Novas linhas entre aspas em CSV

No BigQuery, os caracteres de nova linha entre aspas dentro de um campo CSV são detectados, mas não são interpretados como limite de linha.

Opções de CSV

Para alterar a forma como o BigQuery analisa dados CSV, especifique outras opções no console do Google Cloud, na ferramenta de linha de comando bq ou na API.

Para mais informações sobre o formato CSV, consulte RFC 4180 (em inglês).

Opção de CSV	Opção do console	Sinalização da ferramenta bq	Propriedade da API BigQuery	Descrição
Delimitador de campo	Delimitador de campo: vírgula, tabulação, barra vertical, personalizado	-F ou --field_delimiter	fieldDelimiter (Java, Python)	(Opcional) O separador de campos em um arquivo CSV. O separador pode ser qualquer caractere de um byte em ISO-8859-1. O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte dela para dividir os dados em estado bruto binário. O BigQuery também aceita a sequência de escape "\t" para especificar um separador de tabulação. O valor padrão é a vírgula (",").
Linhas de cabeçalho	Linhas de cabeçalho a serem ignoradas	--skip_leading_rows	skipLeadingRows (Java, Python)	(Opcional) Um número inteiro que indica o número de linhas de cabeçalho nos dados de origem.
Número de registros corrompidos permitidos	Número de erros permitidos	--max_bad_records	maxBadRecords (Java, Python)	(Opcional) O número máximo de registros inválidos que o BigQuery pode ignorar ao executar o job. Se o número exceder esse valor, um erro inválido será retornado no resultado do job. O valor padrão é 0, o que exige que todos os registros sejam válidos.
Caracteres de nova linha	Permitir novas linhas com consulta	--allow_quoted_newlines	allowQuotedNewlines (Java, Python)	(Opcional) Indica se as seções de dados citados que contêm caracteres de nova linha em um arquivo CSV podem ser permitidas. O valor padrão é falso.
Valores nulos personalizados	Nenhum	--null_marker	nullMarker (Java, Python)	(Opcional) Especifica uma string que representa um valor nulo em um arquivo CSV. Por exemplo, se você especificar "\N", o BigQuery o interpretará como um valor nulo ao carregar um arquivo CSV. O valor padrão é a string vazia. Ao definir um valor personalizado, o BigQuery lançará um erro se uma string vazia estiver presente para qualquer tipo de dados, exceto STRING e BYTE. Nessas colunas, o BigQuery interpreta a string vazia como um valor vazio.
Colunas posteriores opcionais	Permitir linhas dentadas	--allow_jagged_rows	allowJaggedRows (Java, Python)	(Opcional) Aceita linhas que não têm colunas opcionais posteriores. Os valores que faltam são tratados como nulos. Se for falso, os registros sem colunas posteriores serão tratados como corrompidos e, se houver muitos dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é falso. Aplicável apenas para CSV, ignorado para outros formatos.
Valores desconhecidos	Ignorar valores desconhecidos	--ignore_unknown_values	ignoreUnknownValues (Java, Python)	Opcional: indica se o BigQuery permite outros valores que não estão representados no esquema da tabela. Se for verdadeiro, os outros valores serão ignorados. Se for falso, os registros com colunas extras serão tratados como corrompidos e, se houver muitos dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é falso. A propriedade sourceFormat determina o que o BigQuery trata como um valor extra: CSV: colunas posteriores JSON: valores nomeados que não correspondem a nenhum nome de coluna
Citação	Nenhum	--quote	quote (Java, Python)	(Opcional) O valor usado para citar seções de dados em um arquivo CSV. O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte da string codificada para dividir os dados no estado bruto binário. O valor padrão são aspas duplas (""). Se os dados não tiverem seções citadas, defina o valor da propriedade como uma string vazia. Se os dados contiverem caracteres de nova linha com consulta, será necessário definir a propriedade allowQuotedNewlines como true. Para incluir o caractere de citação específico dentro de um valor entre aspas, coloque um caractere extra antes dele. Por exemplo, se quiser inserir o caractere padrão ", use "".
Codificação	Nenhum	-E ou --encoding	encoding (Java, Python)	(Opcional) A codificação de caracteres dos dados. Os valores aceitos são UTF-8 ou ISO-8859-1. O valor padrão é UTF-8. O BigQuery decodifica os dados depois que os dados binários brutos são divididos usando os valores das propriedades quote e fieldDelimiter.