Como carregar dados ORC do Cloud Storage

Nesta página, apresentamos uma visão geral sobre como carregar dados ORC do Cloud Storage no BigQuery.

O formato de dados ORC (em inglês) tem código aberto, é orientado por colunas e é amplamente usado no ecossistema Apache Hadoop.

Ao carregar dados ORC usando o Cloud Storage, é possível carregá-los em uma nova tabela ou partição, além de anexá-los ou substituí-los em uma tabela ou partição existentes. Quando os dados são carregados no BigQuery, eles são convertidos para o formato em colunas Capacitor (formato de armazenamento do BigQuery).

Ao carregar dados do Cloud Storage para uma tabela do BigQuery, é necessário que o conjunto de dados que contém a tabela esteja na mesma região ou multirregião do bucket do Cloud Storage.

Para informações sobre como carregar dados ORC de um arquivo local, consulte Como carregar dados no BigQuery de uma fonte de dados local.

Esquemas ORC

Ao carregar arquivos ORC no BigQuery, o esquema da tabela é recuperado automaticamente dos dados de origem autodescritivos. Quando o BigQuery recupera o esquema dos dados de origem, o último arquivo em ordem alfabética é usado.

Por exemplo, você tem os seguintes arquivos ORC no Cloud Storage:

    gs://mybucket/00/
      a.orc
      z.orc
    gs://mybucket/01/
      b.orc
    

Esse comando carrega todos os arquivos em um único comando da CLI (como uma lista separada por vírgulas), e o esquema é derivado de mybucket/01/b.orc:

    bq load \
    --source_format=ORC \
    dataset.table \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
    

Quando o BigQuery detecta o esquema, alguns tipos de dados ORC são convertidos em tipos de dados do BigQuery para torná-los compatíveis com a sintaxe SQL do BigQuery. Todos os campos do esquema detectado são NULLABLE. Para mais informações, consulte Conversões de ORC.

Ao carregar vários arquivos ORC com esquemas diferentes, é necessário que os campos idênticos (com o mesmo nome e mesmo nível aninhado) especificados em mais de um esquema façam o mapeamento para o mesmo tipo de dados convertido do BigQuery em cada definição de esquema.

Compactação de ORC

O BigQuery é compatível com os seguintes tipos de compactação para conteúdo de arquivos ORC:

  • Zlib
  • Snappy
  • LZO
  • LZ4

Permissões exigidas

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

Permissões do BigQuery

Para carregar dados no BigQuery, é necessário ter, no mínimo, as permissões a seguir. 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 seguintes papéis predefinidos do Cloud IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

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

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

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

Além disso, se um usuário tiver permissões bigquery.datasets.create, receberá o acesso bigquery.dataOwner ao criar um conjunto de dados. Ao receber o acesso bigquery.dataOwner, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carregamento.

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 bucket do Cloud Storage, é necessário ter permissões storage.objects.get. Se você estiver usando um caractere curinga no URI, também será necessário ter permissões storage.objects.list.

É possível conceder o papel predefinido do Cloud IAM storage.objectViewer para fornecer as permissões storage.objects.get e storage.objects.list.

Como carregar dados ORC em uma nova tabela

Para carregar dados ORC em uma nova tabela:

  • use o Console do Cloud ou a IU clássica da Web;
  • use o comando bq load da CLI;
  • utilize o método da API jobs.insert e configure um job load;
  • use bibliotecas de cliente.

Para carregar dados ORC do Cloud Storage em uma nova tabela do BigQuery, siga as instruções a seguir:

Console

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

  2. Na seção Recursos do painel de navegação, abra 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.

    Visualizar conjunto de dados

  4. Na seção Origem da página Criar tabela, faça o seguinte:

    • Em Criar tabela de, selecione "Cloud Storage".

    • No campo de origem, navegue até o URI do Cloud Storage ou insira-o. Não é possível incluir vários URIs no Console do Cloud, mas os caracteres curinga são compatíveis. É necessário que o bucket do Cloud Storage esteja no mesmo local que o conjunto de dados com a tabela a ser criada.

      Selecionar arquivo

    • Em Formato de arquivo, selecione ORC.

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

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

      Visualizar 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, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.

  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 Partição por campo e escolha uma coluna DATE ou TIMESTAMP. Essa opção ficará 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 particionamento pode reduzir os custos e melhorar o desempenho. Para mais informações, acesse Como consultar tabelas particionadas. Essa opção ficará indisponível se a opção Sem particionamento estiver selecionada.

  9. (Opcional) Para agrupar a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering. No momento, 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. 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á.
    • Em Valores desconhecidos, deixe a opção Ignorar valores desconhecidos desmarcada. Essa opção se refere apenas a arquivos CSV e JSON.
    • 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 do mouse sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Create new table. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

  3. Na página Create Table, na seção Source Data:

    • Clique em Create from source.
    • Em Location, selecione Cloud Storage e digite o Cloud Storage URI no campo de origem. Não é possível incluir vários URIs na IU da Web do BigQuery, mas caracteres curinga são compatíveis. É necessário que o bucket do Cloud Storage esteja no mesmo local que o conjunto de dados que contém a tabela que você está criando.
    • Em File format, selecione ORC.
  4. Na seção Destination Table:

    • Em Table name, escolha o conjunto de dados apropriado e insira, no campo correspondente, o nome da tabela que você está criando no BigQuery.
    • Verifique se Table type está definido como Native table.
  5. Na seção Schema, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.

  6. (Opcional) Na seção Options:

    • Em Number of errors allowed, 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 Write preference, selecione Write if empty. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
    • Para particionar a tabela:
      • Em Partitioning Type, clique em None e escolha Day.
      • Em Partitioning Field:
      • Para criar uma tabela particionada, escolha uma coluna DATE ou TIMESTAMP. Essa opção ficará 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 Require partition filter para obrigar os usuários a incluir 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, acesse Como consultar tabelas particionadas. Essa opção ficará indisponível se Partitioning type estiver definido como None.
    • Para agrupar a tabela em um cluster, insira até quatro nomes de campo na caixa Clustering fields.
    • Em Destination encryption, escolha Customer-managed encryption para usar uma chave do Cloud Key Management Service a fim de 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 Create Table.

CLI

Use o comando bq load, especifique ORC como 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.

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

Outras sinalizações opcionais:

  • --max_bad_records: um número inteiro que especifica o número máximo de registros inválidos permitidos antes de resultar na falha do job todo. 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.
  • --time_partitioning_type: ativa o particionamento baseado em tempo em uma tabela e define o tipo de partição. No momento, 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 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, será criada uma tabela particionada por tempo de ingestão.
  • --require_partition_filter: quando ativada, esta 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, veja Como consultar tabelas particionadas.
  • --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usada 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 criptografia de tabelas, consulte:

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

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

Em que:

  • location é o local. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, é possível definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para a unidade usando o arquivo .bigqueryrc.
  • format é ORC.
  • 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 separados por vírgulas. Os caracteres curinga também são compatíveis.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.orc em uma tabela com o nome mytable em mydataset.

    bq load \
        --source_format=ORC \
        mydataset.mytable \
        gs://mybucket/mydata.orc
    

O comando a seguir carrega dados de gs://mybucket/mydata.orc em uma tabela particionada por tempo de ingestão com o nome mytable em mydataset.

    bq load \
        --source_format=ORC \
        --time_partitioning_type=DAY \
        mydataset.mytable \
        gs://mybucket/mydata.orc
    

O comando a seguir carrega dados de gs://mybucket/mydata.orc em uma tabela particionada com o nome mytable em mydataset. A tabela é particionada na coluna mytimestamp.

    bq load \
        --source_format=ORC \
        --time_partitioning_field mytimestamp \
        mydataset.mytable \
        gs://mybucket/mydata.orc
    

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela com o nome mytable em mydataset. O URI do Cloud Storage usa um caractere curinga.

    bq load \
        --source_format=ORC \
        mydataset.mytable \
        gs://mybucket/mydata*.orc
    

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela com o nome mytable em mydataset. O comando inclui uma lista separada por vírgulas de URIs do Cloud Storage com caracteres curinga.

    bq load --autodetect \
        --source_format=ORC \
        mydataset.mytable \
        "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
    

API

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

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

  3. É necessário que a property source URIs seja totalmente qualificada no formato gs://bucket/object. Cada URI pode conter um caractere curinga "*".

  4. Para especificar o formato dos dados ORC, defina a property sourceFormat como ORC.

  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 mostra que o job foi concluído com sucesso.
    • A presença da property status.errorResult mostra que houve falha na solicitação e que o objeto incluirá informações que descrevem o erro. Quando há falha na solicitação, nenhuma tabela é criada, e nenhum dado é carregado.
    • A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que tenha havido alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na property 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 dado 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 C# (em inglês).


    using Google.Apis.Bigquery.v2.Data;
    using Google.Cloud.BigQuery.V2;
    using System;

    public class BigQueryLoadTableGcsOrc
    {
        public void LoadTableGcsOrc(
            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.orc";
            var dataset = client.GetDataset(datasetId);
            TableReference destinationTableRef = dataset.GetTableReference(
                tableId: "us_states");
            // Create job configuration
            var jobOptions = new CreateLoadJobOptions()
            {
                SourceFormat = FileFormat.Orc
            };
            // Create and run job
            var loadJob = client.CreateLoadJob(
                sourceUri: gcsURI,
                destination: destinationTableRef,
                // Pass null as the schema because the schema is inferred when
                // loading Orc data
                schema: null,
                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 (em inglês).

import (
    	"context"
    	"fmt"

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

    // importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
    func importORC(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.orc")
    	gcsRef.SourceFormat = bigquery.ORC
    	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

    	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
    }
    

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 ORC file at
     * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.orc
     *
     * TODO(developer): Replace the following lines with the path to your file.
     */
    const bucketName = 'cloud-samples-data';
    const filename = 'bigquery/us-states/us-states.orc';

    async function loadTableGCSORC() {
      // Imports a GCS file into a table with ORC source format.

      /**
       * TODO(developer): Uncomment the following line 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: 'ORC',
        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 (em inglês).

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.orc';
    $loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
    $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 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 Python (em inglês).

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

    dataset_ref = client.dataset(dataset_id)
    job_config = bigquery.LoadJobConfig()
    job_config.source_format = bigquery.SourceFormat.ORC
    uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

    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 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 (em inglês).

require "google/cloud/bigquery"

    def load_table_gcs_orc 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.orc"
      table_id = "us_states"

      load_job = dataset.load_job table_id, gcs_uri, format: "orc"
      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 substituir ou anexar a uma tabela com dados ORC

É possível carregar dados complementares em uma tabela usando 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 complementares em uma tabela:

Opção de console Opção da IU da Web clássica Sinalização da CLI Property da API BigQuery Descrição
Gravar apenas se a tabela estiver vazia Write if empty Nenhuma WRITE_EMPTY Grava dados apenas se a tabela estiver vazia.
Anexar à tabela Append to table --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 Overwrite table --replace ou --replace=true WRITE_TRUNCATE Apaga todos os dados da tabela antes de gravar os novos.

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

Para anexar ou substituir uma tabela:

  • use o Console do Cloud ou a IU clássica da Web;
  • use o comando bq load da CLI;
  • utilize o método da API jobs.insert e configure um job load;
  • use bibliotecas de cliente.

Para anexar ou substituir uma tabela com dados ORC:

Console

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

  2. Na seção Recursos do painel de navegação, abra 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 seção Origem da página Criar tabela, faça o seguinte:

    • Em Criar tabela de, selecione "Cloud Storage".

    • No campo de origem, navegue até o URI do Cloud Storage ou insira-o. Não é possível incluir vários URIs na IU da Web do BigQuery, mas caracteres curinga são compatíveis. É necessário que o bucket do Cloud Storage esteja no mesmo local que o conjunto de dados com a tabela a ser anexada ou substituída.

      Selecionar arquivo

    • Em Formato de arquivo, selecione ORC.

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

    • Em Nome do conjunto de dados, escolha o conjunto de dados 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, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.

  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 Cloud 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, deixe a opção Ignorar valores desconhecidos desmarcada. Essa opção se refere apenas a arquivos CSV e JSON.
    • 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 do mouse sobre um conjunto de dados, clique no ícone de seta para baixo imagem do ícone de seta para baixo e selecione Create new table. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.

  3. Na página Create Table, na seção Source Data:

    • Em Location, selecione Cloud Storage e digite o Cloud Storage URI no campo de origem. Não é possível incluir vários URIs na IU, mas caracteres curinga são aceitos. É necessário que o bucket do Cloud Storage esteja no mesmo local que o conjunto de dados que contém a tabela que você está anexando ou substituindo.
    • Em File format, selecione ORC.
  4. Na página Create Table, na seção Destination Table:

    • Em Table name, escolha o conjunto de dados apropriado e, no campo de nome, insira o nome da tabela que você está anexando ou substituindo.
    • Verifique se Table type está definido como Native table.
  5. Na seção Schema, nenhuma ação é necessária. As informações do esquema são autodescritas em arquivos ORC.

  6. Na seção Options:

    • Em Number of errors allowed, 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 Write preference, escolha Append to table ou Overwrite table.
    • Use os valores padrão de Partitioning Type, Partitioning Field, Require partition filter e Clustering Fields. 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 Destination encryption, escolha Customer-managed encryption para usar uma chave do Cloud Key Management Service a fim de 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 Create Table.

CLI

Insira o comando bq load com 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. Indique a sinalização --source_format e defina como ORC. Como os esquemas ORC são recuperados automaticamente dos dados de origem autodescritivos, não é necessário fornecer uma definição de esquema.

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

Outras sinalizações opcionais:

  • --max_bad_records: um número inteiro que especifica o número máximo de registros inválidos permitidos antes de resultar na falha do job todo. 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.
  • --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
    

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 é ORC.
  • 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 separados por vírgulas. Os caracteres curinga também são compatíveis.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.orc e substitui uma tabela com o nome mytable em mydataset.

    bq load \
        --replace \
        --source_format=ORC \
        mydataset.mytable \
        gs://mybucket/mydata.orc
    

O comando a seguir carrega dados de gs://mybucket/mydata.orc e anexa dados a uma tabela com o nome mytable em mydataset.

    bq load \
        --noreplace \
        --source_format=ORC \
        mydataset.mytable \
        gs://mybucket/mydata.orc
    

Para informações sobre como anexar e substituir tabelas particionadas usando a CLI, consulte Como anexar e substituir dados de tabelas particionadas.

API

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

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

  3. É necessário que a property source URIs seja 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. Defina a property configuration.load.sourceFormat como ORC para especificar o formato dos dados.

  5. Defina a property configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND para especificar a preferência de gravação.

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# (em inglês).


    using Google.Apis.Bigquery.v2.Data;
    using Google.Cloud.BigQuery.V2;
    using System;

    public class BigQueryLoadTableGcsOrcTruncate
    {
        public void LoadTableGcsOrcTruncate(
            string projectId = "your-project-id",
            string datasetId = "your_dataset_id",
            string tableId = "your_table_id"
        )
        {
            BigQueryClient client = BigQueryClient.Create(projectId);
            var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
            var dataset = client.GetDataset(datasetId);
            TableReference destinationTableRef = dataset.GetTableReference(
                tableId: "us_states");
            // Create job configuration
            var jobOptions = new CreateLoadJobOptions()
            {
                SourceFormat = FileFormat.Orc,
                WriteDisposition = WriteDisposition.WriteTruncate
            };
            // Create and run job
            var loadJob = client.CreateLoadJob(
                sourceUri: gcsURI,
                destination: destinationTableRef,
                // Pass null as the schema because the schema is inferred when
                // loading Orc data
                schema: null, 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 (em inglês).

import (
    	"context"
    	"fmt"

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

    // importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
    // and overwriting/truncating existing data in the table.
    func importORCTruncate(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.orc")
    	gcsRef.SourceFormat = bigquery.ORC
    	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
    	// Default for import jobs is to append data to a table.  WriteTruncate
    	// specifies that existing data should instead be replaced/overwritten.
    	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
    }
    

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 the 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.orc';

    async function loadORCFromGCSTruncate() {
      /**
       * 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: 'ORC',
        // 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;
      }
    }

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 (em inglês).

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.orc';
    $loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->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 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 Python (em inglês).

Para substituir as linhas em uma tabela, configure a property LoadJobConfig.write_disposition como 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.source_format = bigquery.SourceFormat.ORC
    uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
    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))

Ruby

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

require "google/cloud/bigquery"

    def load_table_gcs_orc_truncate(
        dataset_id = "your_dataset_id",
        table_id   = "your_table_id"
      )
      bigquery = Google::Cloud::Bigquery.new
      dataset  = bigquery.dataset dataset_id
      gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

      load_job = dataset.load_job table_id,
                                  gcs_uri,
                                  format: "orc",
                                  write:  "truncate"
      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 ORC particionados no Hive

O BigQuery é compatível com o carregamento de dados ORC particionados no Hive armazenados no Cloud Storage e preenche as colunas de particionamento do Hive como colunas na tabela de destino gerenciada no BigQuery. Para mais informações, consulte Como carregar dados particionados externamente a partir do Cloud Storage.

Conversões ORC

O BigQuery converte tipos de dados ORC nos seguintes tipos de dados:

Tipos primitivos

Tipo de dados ORC Tipo de dados BigQuery Notas
boolean BOOLEAN
byte INTEGER
short INTEGER
int INTEGER
long INTEGER
float FLOAT
double FLOAT
string STRING somente UTF-8
varchar STRING somente UTF-8
char STRING somente UTF-8
binary BYTES
date DATE
timestamp TIMESTAMP ORC tem precisão de nanossegundos, mas o BigQuery converte valores de abaixo de microssegundos em microssegundos durante a leitura dos dados.
decimal NUMERIC ou STRING Os tipos NUMERIC são valores numéricos exatos com 38 dígitos de precisão e 9 dígitos decimais de escala. Consulte Tipo NUMERIC para mais detalhes. Se um tipo decimal em um esquema ORC tiver não mais que 9 dígitos de escala e não mais que 29 dígitos de precisão, ele será convertido em NUMERIC. Caso contrário, será convertido em STRING. Se um tipo decimal for convertido em STRING, uma mensagem de aviso será retornada.

Tipos complexos

Tipo de dados ORC Tipo de dados BigQuery Notas
struct RECORD
  • Todos os campos são ANULÁVEIS.
  • A ordem dos campos é ignorada.
  • É necessário que o nome do campo seja um nome de coluna válido.
map<K,V> RECORD Um campo map<K,V> ORC é convertido em um RECORD repetido que contém dois campos: uma chave do mesmo tipo de dados (K) e um valor do mesmo tipo de dados (V). Os dois campos são NULLABLE.
list campos repetidos Listas aninhadas e listas de mapas não são aceitas.
union RECORD
  • Quando o tipo union tiver apenas uma variante, será convertido em um campo NULLABLE.
  • Caso contrário, um tipo union será convertido em RECORD com uma lista de campos NULLABLE. Os campos NULLABLE têm sufixos, como field_0, field_1 e assim por diante. Apenas um desses campos terá um valor atribuído durante a leitura dos dados.

Nomes de coluna

É necessário que o nome da coluna contenha apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_) e comece com uma letra ou sublinhado. O comprimento máximo do nome de uma coluna é 128 caracteres. Não é possível usar estes prefixos em um nome de coluna:

  • _TABLE_
  • _FILE_
  • _PARTITION

Não é permitido haver nomes de coluna duplicados, mesmo com diferença de maiúsculas e minúsculas. Por exemplo, uma coluna com o nome Column1 é considerada idêntica a uma coluna com o nome column1.

Valores NULL

Para jobs de carregamento, o BigQuery ignora elementos NULL para o tipo composto list, porque senão eles seriam convertidos em elementos NULL ARRAY, que não podem permanecer em uma tabela. Consulte Tipos de dados para mais detalhes.

Para mais informações sobre os tipos de dados ORC, consulte a Especificação do Apache ORC™ v1 (em inglês).