Como carregar dados ORC a partir do Cloud Storage

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

ORC é um formato de dados de código aberto orientado por colunas que é muito usado no ecossistema Apache Hadoop.

Os dados ORC podem ser carregados pelo Cloud Storage em uma nova tabela ou partição. Também é possível anexá-los a uma tabela ou partição, além de substituir esses itens. Quando os dados são carregados no BigQuery, eles são convertidos no formato de colunas Capacitor (em inglês), 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 no mesmo local regional ou multirregional que o 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

Quando você carrega arquivos ORC no BigQuery, o esquema da tabela é recuperado automaticamente pelos 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 arquivos ORC a seguir no Cloud Storage:

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

executar esse comando na ferramenta de linha de comando bq carrega todos os arquivos (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 no formato 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, veja conversões de ORC.

Quando você carrega vários arquivos ORC com esquemas diferentes, campos idênticos (com o mesmo nome e mesmo nível aninhado) especificados em mais de um esquema precisam fazer o mapeamento para o mesmo tipo de dados convertido do BigQuery em cada definição de esquema.

Compactação 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 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 seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

bigquery.user
bigquery.jobUser
bigquery.admin

Além disso, quando um usuário tem permissões bigquery.datasets.create e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. O acesso bigquery.dataOwner permite que o usuário crie e atualize tabelas no conjunto de dados usando um job de carregamento.

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

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, você precisa 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 storage.objectViewer do IAM concede 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
Use o comando bq load da ferramenta de linha de comando bq.
Chame o método da API jobs.insert e configure um job load.
use as bibliotecas de cliente.

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

Console

Abra a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.

Observação: a experiência padrão é a versão de visualização do Console do Cloud. Se você clicou em Ocultar recursos da versão de visualização para acessar a versão de disponibilidade geral do Console do Cloud, faça o seguinte: na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
Na página Criar tabela, na seção Origem:
- 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. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela sendo criada.
- Em Formato de arquivo, selecione ORC.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
- Verifique se Tipo de tabela está definido como Tabela nativa.
- No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.
Na seção Esquema, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.
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.
(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 pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas. Essa opção ficará indisponível se a opção Sem particionamento estiver selecionada.
Opcional: para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering.
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 refere-se 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.
Clique em Criar tabela.

bq

Use o comando bq load, especifique ORC como o source_format e inclua um URI do Cloud Storage. É possível incluir apenas um URI, uma lista de URIs separados por vírgulas ou um URI que contenha um caractere curinga.

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

Estas são 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 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.
--time_partitioning_type: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição padrão para o particionamento baseado em tempo é DAY.
--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 especifica as partições a serem consultadas. A exigência de um filtro de particionamento pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas.
--clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.
--destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

Para mais informações sobre tabelas particionadas, consulte:
- Como criar e usar tabelas particionadas
- Como criar e usar tabelas particionadas por tempo de ingestão
Para mais informações sobre tabelas em cluster, consulte:
- Como criar e usar tabelas em cluster
Para mais informações sobre a criptografia de tabelas, consulte:
- Como proteger dados com chaves do Cloud KMS

Para carregar dados 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 você estiver usando BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
format é ORC.
dataset é um conjunto de dados atual;
table é o nome da tabela em que você carregará dados;
path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.orc em uma tabela chamada 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 chamada 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 chamada 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 comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O URI do Cloud Storage usa um caractere curinga.

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

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

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

API

Crie um job load que aponte para os dados de origem no Cloud Storage.
(Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.
A propriedade source URIs precisa ser totalmente qualificada no formato gs://bucket/object. Cada URI pode conter um caractere curinga "*".
Especifique o formato de dados ORC definindo a propriedade sourceFormat como ORC.
Para verificar o status do job, chame jobs.get(job_id*), em que job_id é o ID do job retornado pela solicitação inicial.
- status.state = DONE indica que o job foi concluído.
- A propriedade status.errorResult mostra que houve falha na solicitação e o objeto incluirá informações que descrevem o erro. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados.
- A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que haja alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.
Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.
Chamar jobs.insert em um determinado ID do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID do job e, no máximo, uma das operações será bem-sucedida.

C#

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

Ver no GitHub Feedback


using Google.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 essa amostra, siga as instruções de configuração para Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"

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

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

Java

Ver no GitHub

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

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

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

  public static void loadOrcFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

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

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

Node.js

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

Ver no GitHub Feedback

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

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

/**
 * This sample loads the 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 para PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery PHP.

Ver no GitHub Feedback

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

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

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

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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 essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Ver no GitHub Feedback

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(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_id, job_config=job_config
)  # Make an API request.

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

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

Ruby

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

Ver no GitHub Feedback

require "google/cloud/bigquery"

def load_table_gcs_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 anexar ou substituir uma tabela com dados ORC

É possível carregar mais dados para uma tabela a partir de arquivos de origem ou anexando resultados de consultas.

No Console do Cloud, use a opção Preferência de gravação para especificar qual ação será realizada ao carregar dados de um arquivo de origem ou de um resultado de consulta.

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

Opção do console	Sinalização da ferramenta `bq`	Propriedade da API BigQuery	Descrição
Gravar apenas se a tabela estiver vazia	Nenhuma	`WRITE_EMPTY`	Grava dados apenas se a tabela estiver vazia.
Anexar à tabela	`--noreplace` ou `--replace=false`; se `--[no]replace` não for especificado, o padrão será anexado	`WRITE_APPEND`	(Padrão) Anexa os dados ao final da tabela.
Substituir tabela	`--replace` ou `--replace=true`	`WRITE_TRUNCATE`	Apaga todos os dados da tabela antes de gravar os novos. Essa ação também exclui o esquema da tabela e remove qualquer chave do Cloud KMS.

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

É possível anexar ou substituir uma tabela com um destes métodos:

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

Para anexar ou substituir uma tabela com dados ORC:

Console

Abra a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.

Observação: a experiência padrão é a versão de visualização do Console do Cloud. Se você clicou em Ocultar recursos da versão de visualização para acessar a versão de disponibilidade geral do Console do Cloud, faça o seguinte: na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Criar tabela.
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 Cloud, mas os caracteres curinga são compatíveis. O bucket 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 ORC.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
- 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.
Na seção Esquema, nenhuma ação é necessária. O esquema é autodescrito em arquivos ORC.

Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
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.
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 refere-se 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.
Clique em Criar tabela.

bq

Digite 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 do local.

Estas são 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 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.
--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 você carregará dados;
path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.orc e substitui uma tabela chamada 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 chamada 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 ferramenta de linha de comando bq, consulte: Como anexar e substituir dados de tabelas particionadas.

API

Crie um job load que aponte para os dados de origem no Cloud Storage.
(Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.
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.
Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como ORC.
Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

C#

Ver no GitHub Feedback


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

Ver no GitHub Feedback

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
}

Java

Ver no GitHub

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

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

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

  public static void loadOrcFromGcsTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.orc())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS ORC file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Ver no GitHub Feedback

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

Ver no GitHub Feedback

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

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

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

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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

Para substituir as linhas em uma tabela existente, defina a propriedade LoadJobConfig.write_disposition como WRITE_TRUNCATE.

Ver no GitHub Feedback

import six

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

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

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.ORC,
)

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

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

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

Ruby

Ver no GitHub Feedback

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 do Cloud Storage.

Conversões de 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 é compatível com a precisão de nanossegundos, mas o BigQuery converte valores de submicrossegundos em microssegundos durante a leitura dos dados.
decimal	NUMERIC, BIGNUMERIC ou STRING	Consulte Tipo decimal.

Tipo decimal

Os tipos lógicos Decimal podem ser convertidos em tipos NUMERIC, BIGNUMERIC (Visualização) ou STRING. O tipo convertido depende dos parâmetros de precisão e escalonamento do tipo lógico decimal e dos tipos decimais de destino especificados. Especifique o tipo decimal de destino da seguinte forma:

Para um job de carregamento usando a API jobs.insert, use o campo JobConfigurationLoad.decimalTargetTypes.
Para um job de carregamento usando o comando bq load na ferramenta de linha de comando bq, use a sinalização --decimal_target_types.
Para uma consulta em uma tabela com fontes externas, use o campo ExternalDataConfiguration.decimalTargetTypes.
Para uma tabela externa permanente criada com DDL, use a opção decimal_target_types.

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> é convertido em um RECORD repetido que contém dois campos: uma chave do mesmo tipo de dados que K e um valor do mesmo tipo de dados que V. Os dois campos são ANULÁVEIS.
list	campos repetidos	Listas aninhadas e listas de mapas não são aceitas.
union	RECORD	Quando o tipo union tem apenas uma variante, ele é convertido em campo NULLABLE. Caso contrário, um tipo union é 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 recebe um valor durante a leitura dos dados.

Nomes de coluna

O nome da coluna precisa conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_) e começar com uma letra ou sublinhado. O comprimento máximo é de 128 caracteres. Não é possível usar estes prefixos nos nomes da coluna:

_TABLE_
_FILE_
_PARTITION

Os nomes de coluna duplicados não são permitidos, mesmo em caso de diferença de maiúsculas e minúsculas. Por exemplo, uma coluna chamada Column1 é considerada idêntica a uma coluna chamada column1.

Valores `NULL`

Para jobs de carregamento, o BigQuery ignora elementos NULL para o tipo composto list, porque senão eles seriam traduzidos como 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.

Como carregar dados ORC a partir do Cloud Storage

Esquemas ORC

Compactação ORC

Permissões exigidas

Permissões do BigQuery

Permissões do Cloud Storage

Como carregar dados ORC em uma nova tabela

Console

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

Como anexar ou substituir uma tabela com dados ORC

Console

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

Como carregar dados ORC particionados no Hive

Conversões de ORC

Tipos primitivos

Tipo decimal

Tipos complexos

Nomes de coluna

Valores NULL

Valores `NULL`