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 no formato de colunas do Capacitor, o formato de armazenamento 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 intervalo 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.

Limitações

Ao carregar dados CSV do Cloud Storage ao BigQuery, observe estes pontos:

  • Os arquivos CSV não são compatíveis com dados aninhados ou repetidos.
  • Se você usa a compressão gzip, o BigQuery não consegue ler os dados em paralelo. O carregamento de dados CSV compactados no BigQuery é mais lento do que o carregamento de dados não compactados.
  • Não é possível incluir arquivos compactados e descompactados no mesmo job de carga.
  • Quando você carrega dados CSV ou JSON, os valores nas colunas DATE precisam usar o separador traço (-) e a data precisa estar no formato: YYYY-MM-DD (ano-mês-dia).
  • Quando você carrega dados JSON ou CSV, os valores nas colunas TIMESTAMP precisam usar o separador de traço (-) na parte de 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 dois-pontos (:).

Codificação de CSV

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 ao carregar seus dados para que seja possível converter em UTF-8.

Em arquivos CSV, os delimitadores podem ser qualquer caractere de um byte em ISO-8859-1. Para usar um caractere no intervalo 128-255, codifique-o como UTF-8. O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte dela para dividir os dados em seu estado bruto, binário.

Permissões exigidas

Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carga e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões para acessar o intervalo que contém os dados.

Permissões do BigQuery

Pelo menos as permissões a seguir são obrigatórias para carregar dados no BigQuery. Elas serão necessárias se você estiver carregando dados em uma nova tabela ou partição ou anexando/substituindo uma tabela ou partição.

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

Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, recebe o acesso bigquery.dataOwner a ele. Com o acesso bigquery.dataOwner, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carga.

Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, é necessário ter permissões storage.objects.get. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list.

O papel predefinido do Cloud IAM storage.objectViewer pode ser concedido para fornecer ambas as permissões storage.objects.get e storage.objects.list.

Como carregar dados CSV em uma tabela

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

  • Com o uso do Console do GCP ou da IU da Web clássica.
  • Com o uso do comando bq load da CLI.
  • Chamando o método de API jobs.insert e configurando um job load.
  • Com o uso de bibliotecas de cliente.

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

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar o Console do GCP

  2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

  3. No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

    Criar tabela

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

    • Em Criar tabela de, selecione Cloud Storage.

    • No campo de origem, procure ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no Console do GCP, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.

      Selecionar arquivo

    • Em Formato de arquivo, selecione CSV.

  5. Siga estas etapas na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto apropriado.

      Ver conjunto de dados

    • Verifique se o Tipo de tabela está definido como Tabela nativa.

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

  6. Na seção Esquema, em Detectar automaticamente, marque Parâmetros de esquema e entrada para ativar a detecção automática do esquema. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:

    • Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

      Adicionar esquema como matriz JSON

    • Use Adicionar campo para inserir manualmente o esquema.

      Adicionar definição de esquema usando o botão "Adicionar campo"

  7. (Opcional) Para particionar a tabela, escolha as opções em Configurações de particionamento e cluster:

    • Para criar uma tabela particionada, clique em Sem particionamento, selecione Particionar por campo e escolha uma coluna DATE ou TIMESTAMP. Essa opção estará indisponível se o esquema não incluir uma coluna DATE ou TIMESTAMP.
    • Para criar uma tabela particionada por tempo de ingestão, clique em Sem particionamento e selecione Partição por tempo de ingestão.
  8. (Opcional) Em Filtro de particionamento, clique na caixa Exigir filtro de particionamento para solicitar que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte Como consultar tabelas particionadas. Essa opção estará indisponível se Sem particionamento estiver selecionado.

  9. (Opcional) Para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering. Atualmente, o clustering é compatível apenas com tabelas particionadas.

  10. (Opcional) Clique em Opções avançadas.

    • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Essa opção 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á.
    • Em Valores desconhecidos, marque Ignorar valores desconhecidos para ignorar quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
    • 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, digite 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 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.
    • 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.
  11. Clique em Criar tabela.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

  3. Na página Criar tabela, na seção Dados de origem:

    • Clique em Criar da origem.
    • Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.
    • Em Formato de arquivo, selecione CSV.
  4. Na seção Tabela de destino:

    • Em Nome da tabela, escolha o conjunto de dados apropriado. No campo do nome da tabela, insira um nome para a tabela que você está criando no BigQuery.
    • Verifique se o Tipo de tabela está definido como Tabela nativa.
  5. Na seção Esquema, em Detectar automaticamente, marque Parâmetros de esquema e entrada para ativar a detecção automática do esquema. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:

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

      Adicionar esquema como matriz JSON

    • Use Adicionar campo para inserir manualmente o esquema:

      Adicionar esquema usando campos de adição

  6. (Opcional) Na seção Opções:

    • Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Outro. Se você escolher Outro, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
    • Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
    • 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á.
    • Em Permitir novas linhas com consulta, marque a caixa de seleção 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 Permitir linhas dentadas, marque a caixa de seleção 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 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.
    • Em Ignorar valores desconhecidos, marque a caixa de seleção para ignorar quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
    • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Essa opção cria uma nova tabela e carrega seus dados nela.
    • Para particionar a tabela:
      • Em Tipo de particionamento, clique em Nenhum e escolha Dia.
      • No Campo de particionamento:
      • Para criar uma tabela particionada, escolha uma coluna DATE ou TIMESTAMP. Essa opção estará indisponível se o esquema não incluir uma coluna DATE ou TIMESTAMP.
      • Para criar uma tabela particionada por tempo de ingestão, use o valor padrão: _PARTITIONTIME.
      • Clique na caixa Exigir filtro de partição para solicitar que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte Como consultar tabelas particionadas. Essa opção estará indisponível se Tipo de particionamento estiver definido como Nenhum.
    • Para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Campos em cluster.
    • Em Criptografia de destino, escolha Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração Default, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
  7. Clique em Criar tabela.

CLI

Use o comando bq load, especifique CSV com a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separada por vírgulas ou um URI que contenha 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.

(Opcional) Forneça a sinalização --location e defina o valor como seu local.

Estas são outras sinalizações opcionais:

  • --allow_jagged_rows: quando especificada, aceita 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 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 especificada, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
  • --autodetect: quando especificada, ativa a detecção automática de esquema para dados CSV e JSON.
  • --time_partitioning_type: ativa o particionamento baseado em tempo em uma tabela e define o tipo de partição. Atualmente, o único valor possível é DAY, que gera uma partição por dia. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE ou TIMESTAMP.
  • --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 estiver ativado sem esse valor, uma tabela particionada por tempo de ingestão será criada.
  • --require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte 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. Só é possível usar essa sinalização com tabelas particionadas.
  • --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

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

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

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

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 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;
  • dataset é um conjunto de dados atual;
  • table é o nome da tabela em que os dados serão carregados;
  • path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os 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 denominado 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 denominado myschema.json. O arquivo CSV inclui duas linhas de cabeçalho. Se --skip_leading_rows não for especificado, o comportamento padrão é presumir que o arquivo não contém 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 denominado 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 chamada mytable em mydataset. A tabela é particionada na coluna mytimestamp. O esquema é definido em um arquivo de esquema local denominado 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

O comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela denominada 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 comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela denominada 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 denominado 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 na seção jobReference do recurso de job.

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

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

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

    • O resultado status.state = DONE mostra que o job foi concluído com sucesso.
    • 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.
    • Se status.errorResult não for exibido, o job terá sido concluído com sucesso, mas é 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 o transmita 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 de job é idempotente. É possível tentar novamente quantas vezes quiser com o mesmo código 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 C#.


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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

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

Job job = table.load(FormatOptions.csv(), sourceUri);
// Wait for the job to complete
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully
  } else {
    // Handle error case
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

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.

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

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 do Python em 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 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.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Antes de testar esta amostra, siga as instruções de configuração do Ruby em 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 (em inglês).

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 anexar ou substituir uma tabela com dados CSV

Carregue dados adicionais para uma tabela de arquivos de origem ou anexando resultados de consultas.

No Console ou na IU da Web clássica do BigQuery, use a opção Gravar preferência para especificar a ação a ser executada ao carregar dados de um arquivo de origem ou de um resultado de consulta.

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

Opção de console Opção da IU da Web clássica Sinalização da CLI Propriedade da API BigQuery Descrição
Gravar apenas se a tabela estiver vazia Gravar apenas se a tabela estiver vazia Nenhuma WRITE_EMPTY Grava dados apenas se a tabela estiver vazia.
Anexar à tabela Anexar à tabela --noreplace ou --replace=false. Se --[no]replace não estiver especificado, o padrão será anexar WRITE_APPEND (Padrão) Anexa os dados ao final da tabela.
Substituir tabela Substituir tabela --replace ou --replace=true WRITE_TRUNCATE Apaga todos os dados em uma tabela antes de gravar os novos.

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

É possível anexar ou substituir uma tabela destas maneiras:

  • Com o uso do Console do GCP ou da IU da Web clássica.
  • Com o uso do comando bq load da CLI.
  • Chamando o método de API jobs.insert e configurando um job load.
  • Com o uso de bibliotecas de cliente.

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar o Console do GCP

  2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

  3. No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.

    Criar tabela

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

    • Em Criar tabela de, selecione Cloud Storage.

    • No campo de origem, procure ou insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está anexando ou substituindo.

      Selecionar arquivo

    • Em Formato de arquivo, selecione CSV.

  5. Siga estas etapas na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto apropriado.

      Escolher conjunto de dados

    • No campo Nome da tabela, insira o nome da tabela que você está anexando ou substituindo no BigQuery.

    • Verifique se o Tipo de tabela está definido como Tabela nativa.

  6. Na seção Esquema, em Detectar automaticamente, marque Parâmetros de esquema e entrada para ativar a detecção automática do esquema. Como alternativa, insira manualmente a definição do esquema da maneira a seguir:

    • Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

      Adicionar esquema como matriz JSON

    • Use Adicionar campo para inserir manualmente o esquema.

      Adicionar definição de esquema usando o botão "Adicionar campo"

  7. Em Configurações de partição e cluster, use os valores padrão. Não é possível anexar ou substituir uma tabela para convertê-la em uma tabela particionada ou em cluster. Além disso, o Console do GCP não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.

  8. Clique em Opções avançadas.

    • 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á.
    • Em Valores desconhecidos, marque Ignorar valores desconhecidos para ignorar quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
    • 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, digite 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 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.
    • 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.

      Substituir tabela

  9. Clique em Criar tabela.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Criar nova tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.

  3. Na página Criar tabela, na seção Dados de origem:

    • Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está anexando ou substituindo.
    • Em Formato de arquivo, selecione CSV.
  4. Na página Criar tabela, na seção Tabela de destino:

    • Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo de nome, insira o nome da tabela que você está anexando ou substituindo.
    • Verifique se o Tipo de tabela está definido como Tabela nativa.
  5. Na seção Esquema, insira a definição do esquema.

    • Em arquivos CSV, marque a opção Detectar automaticamente para ativar a detecção automática de esquema.

      link da detecção automática

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

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

        Adicionar esquema como matriz JSON

      • Use Adicionar campo para inserir manualmente o esquema:

        Adicionar esquema usando campos de adição

  6. Na seção Opções:

    • Em Delimitador de campo, escolha o caractere que separa as células no seu arquivo CSV: Vírgula, Tabulação, Barra vertical ou Outro. Se você escolher Outro, insira o delimitador na caixa Delimitador de campo personalizado. O valor padrão é Vírgula.
    • Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas do cabeçalho a serem ignoradas na parte superior do arquivo CSV. O valor padrão é 0.
    • 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á.
    • Em Permitir novas linhas com consulta, marque a caixa de seleção 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 Permitir linhas dentadas, marque a caixa de seleção 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 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.
    • Em Ignorar valores desconhecidos, marque a caixa de seleção para ignorar quaisquer valores em uma linha que não estejam presentes no esquema da tabela.
    • Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
    • Use os valores padrão de Tipo de particionamento, Campo de particionamento, Exigir filtro de partição e Campos de clustering. Não é possível anexar ou substituir uma tabela para convertê-la em uma tabela particionada ou em cluster. Além disso, a IU da Web não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
    • Em Criptografia de destino, escolha Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração Default, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
  7. Clique em Criar tabela.

CLI

Use o comando bq load, especifique CSV com a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separada por vírgulas ou um URI que contenha 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.

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 como seu local.

Estas são outras sinalizações opcionais:

  • --allow_jagged_rows: quando especificada, aceita 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 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 especificada, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
  • --autodetect: quando especificada, ativa a detecção automática de esquema para 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

Em que:

  • 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 os dados serão carregados;
  • path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os 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 no mydataset. O esquema é definido por meio da detecção automática de esquema.

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

O comando a seguir carrega dados de gs://mybucket/mydata.csv e os anexa a uma tabela chamada mytable no 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 na seção jobReference do recurso de 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. Para especificar o formato de dados, defina 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 Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

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 do BigQuery para Node.js.

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

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

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 do Python em 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 Python.

Para substituir linhas em uma tabela, defina a propriedade LoadJobConfig.write_disposition como a constante SourceFormat WRITE_TRUNCATE.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.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_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

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

Opções de CSV

Para alterar a forma como o BigQuery analisa os dados CSV, especifique outras opções no console, na IU clássica, na CLI ou na API.

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

Opção de CSV Opção de console Opção da IU clássica Sinalização da CLI Propriedade da API BigQuery Descrição
Delimitador de campo Delimitador de campo: vírgula, tabulação, barra vertical, personalizado Delimitador de campo: vírgula, tabulação, barra vertical, outro -F ou --field_delimiter fieldDelimiter (Opcional) O separador de campos em um arquivo CSV. O separador pode ser qualquer caractere de um byte em ISO-8859-1. Para usar um caractere no intervalo 128-255, codifique-o como UTF-8. O BigQuery converte a string para a codificação ISO-8859-1 e usa o primeiro byte dela para dividir os dados em seu 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 Linhas de cabeçalho a serem ignoradas --skip_leading_rows skipLeadingRows (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 Número de erros permitidos --max_bad_records maxBadRecords (Opcional) O número máximo de registros corrompidos que o BigQuery pode ignorar ao executar o job. Se o número de registros corrompidos exceder esse valor, o erro "inválido" é 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 em citações Permitir novas linhas em citações --allow_quoted_newlines allowQuotedNewlines (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 Nenhuma Nenhuma --null_marker nullMarker (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 Permitir linhas dentadas --allow_jagged_rows allowJaggedRows (Opcional) Aceita linhas que não têm colunas opcionais posteriores. Os valores ausentes 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 Ignorar valores desconhecidos --ignore_unknown_values ignoreUnknownValues (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 Nenhuma Nenhuma --quote quote (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, em seguida, usa o primeiro byte da string codificada para dividir os dados em seu estado bruto binário. O valor padrão é uma aspa dupla ("). 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 citados, será necessário definir a propriedade allowQuotedNewlines como true.
Codificação Nenhuma Nenhuma -E ou --encoding encoding (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.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.