Carregar dados ORC a partir do Cloud Storage

Esta página fornece uma vista geral do carregamento de dados ORC do Cloud Storage para o BigQuery.

O ORC é um formato de dados orientado para colunas de código aberto amplamente usado no ecossistema do Apache Hadoop.

Quando carrega dados ORC do Cloud Storage, pode carregá-los para uma nova tabela ou partição, ou pode anexá-los ou substituir uma tabela ou uma partição existente. Quando os dados são carregados para o BigQuery, são convertidos para o formato de colunas para o Capacitor (o formato de armazenamento do BigQuery).

Quando carrega dados do Cloud Storage para uma tabela do BigQuery, o conjunto de dados que contém a tabela tem de estar na mesma localização regional ou multirregional que o contentor do Cloud Storage.

Para obter informações sobre o carregamento de dados ORC a partir de um ficheiro local, consulte o artigo Carregar dados para o BigQuery a partir de uma origem de dados local.

Limitações

Está sujeito às seguintes limitações quando carrega dados para o BigQuery a partir de um contentor do Cloud Storage:

  • O BigQuery não garante a consistência dos dados para origens de dados externas. As alterações aos dados subjacentes durante a execução de uma consulta podem resultar num comportamento inesperado.
  • O BigQuery não suporta o controlo de versões de objetos do Cloud Storage. Se incluir um número de geração no URI do Cloud Storage, a tarefa de carregamento falha.

Antes de começar

Conceda funções de gestão de identidade e de acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento e crie um conjunto de dados para armazenar os seus dados.

Autorizações necessárias

Para carregar dados para o BigQuery, precisa de autorizações da IAM para executar uma tarefa de carregamento e carregar dados para tabelas e partições do BigQuery. Se estiver a carregar dados do Cloud Storage, também precisa de autorizações de IAM para aceder ao contentor que contém os seus dados.

Autorizações para carregar dados para o BigQuery

Para carregar dados para uma nova tabela ou partição do BigQuery, ou para anexar ou substituir uma tabela ou uma partição existente, precisa das seguintes autorizações de IAM:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para carregar dados para uma tabela ou uma partição do BigQuery:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode criar e atualizar tabelas através de uma tarefa de carregamento nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para carregar dados do Cloud Storage

Para receber as autorizações de que precisa para carregar dados de um contentor do Cloud Storage, peça ao seu administrador para lhe conceder a função de IAM Administrador de armazenamento (roles/storage.admin) no contentor. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para carregar dados a partir de um contentor do Cloud Storage. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para carregar dados de um contentor do Cloud Storage:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Crie um conjunto de dados

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

Esquemas ORC

Quando carrega ficheiros ORC para o BigQuery, o esquema da tabela é obtido automaticamente dos dados de origem autodescritivos. Quando o BigQuery obtém o esquema dos dados de origem, é usado o ficheiro alfabeticamente último.

Por exemplo, tem os seguintes ficheiros ORC no Cloud Storage:

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

A execução deste comando na ferramenta de linhas de comando bq carrega todos os ficheiros (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 deteta o esquema, alguns tipos de dados ORC são convertidos em tipos de dados do BigQuery para os tornar compatíveis com a sintaxe do GoogleSQL. Todos os campos no esquema detetado são NULLABLE. Para mais informações, consulte o artigo Conversões de ORC.

Quando carrega vários ficheiros ORC com esquemas diferentes, os campos idênticos (com o mesmo nome e o mesmo nível aninhado) especificados em vários esquemas têm de ser mapeados para o mesmo tipo de dados do BigQuery convertido em cada definição de esquema.

Para fornecer um esquema de tabela para criar tabelas externas, defina a propriedade referenceFileSchemaUri na API BigQuery ou o parâmetro
--reference_file_schema_uri na ferramenta de linha de comandos bq para o URL do ficheiro de referência.

Por exemplo, --reference_file_schema_uri="gs://mybucket/schema.orc".

Compressão ORC

O BigQuery suporta os seguintes codecs de compressão para conteúdos de ficheiros ORC:

  • Zlib
  • Snappy
  • LZO
  • LZ4
  • ZSTD

Os dados em ficheiros ORC não permanecem comprimidos depois de serem carregados para o BigQuery. O armazenamento de dados é comunicado em bytes lógicos ou bytes físicos, consoante o modelo de faturação do armazenamento do conjunto de dados. Para obter informações sobre a utilização do armazenamento, consulte a vista INFORMATION_SCHEMA.TABLE_STORAGE.

Carregar dados ORC para uma nova tabela

Pode carregar dados ORC para uma nova tabela:

  • Usar a Trusted Cloud consola
  • Usar o comando bq load da ferramenta de linhas de comando bq
  • Chamar o método da API jobs.insert e configurar uma tarefa load
  • Usar as bibliotecas de cliente

Para carregar dados ORC do Cloud Storage para uma nova tabela do BigQuery:

Consola

  1. Na Trusted Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
  3. Na secção Informações do conjunto de dados, clique em Criar tabela.
  4. No painel Criar tabela, especifique os seguintes detalhes:
    1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
      1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Trusted Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir. selecione o ficheiro de origem para criar uma tabela do BigQuery
      2. Em Formato de ficheiro, selecione ORC.
    2. Na secção Destino, especifique os seguintes detalhes:
      1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
      2. No campo Tabela, introduza o nome da tabela que quer criar.
      3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
    3. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros ORC.
    4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas.
    5. Clique em Opções avançadas e faça o seguinte:
      • Para Preferência de escrita, deixe a opção Escrever se estiver vazio selecionada. Esta opção cria uma nova tabela e carrega os seus dados na mesma.
      • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
      • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google Cloud-powered key, o BigQuery encripta os dados em repouso.
    6. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte carrega um ficheiro ORC na nova tabela mytable:

  1. Na Trusted Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaração:

    LOAD DATA OVERWRITE mydataset.mytable
    FROM FILES (
      format = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq load, especifique ORC como source_format e inclua um URI do Cloud Storage. Pode incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contenha um caractere universal.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

Outras flags opcionais incluem:

  • --time_partitioning_type: ativa a partição baseada no tempo numa tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Esta flag é opcional quando cria uma tabela particionada numa coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição predefinido para a partição baseada no tempo é DAY. Não pode alterar a especificação de partição numa tabela existente.
  • --time_partitioning_expiration: um número inteiro que especifica (em segundos) quando uma partição baseada no tempo deve ser eliminada. O tempo de expiração é avaliado como a data UTC da partição mais o valor inteiro.
  • --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se a partição baseada no tempo estiver ativada sem este valor, é criada uma tabela particionada por tempo de ingestão.
  • --require_partition_filter: quando ativada, esta opção exige que os utilizadores incluam uma cláusula WHERE que especifique as partições a consultar. Exigir um filtro de partição pode reduzir o custo e melhorar o desempenho. Para mais informações, consulte o artigo Exija um filtro de partição nas consultas.
  • --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usados para criar uma tabela agrupada.
  • --destination_kms_key: a chave do Cloud KMS para a encriptação dos dados da tabela.

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

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

    Para mais informações sobre a encriptação de tabelas, consulte:

Para carregar dados ORC para o BigQuery, introduza o seguinte comando:

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

Onde:

  • location é a sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
  • format é ORC.
  • dataset é um conjunto de dados existente.
  • table é o nome da tabela para a qual está a carregar dados.
  • path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgula. Os carateres universais também são suportados.

Exemplos:

O comando seguinte carrega dados de gs://mybucket/mydata.orc para uma tabela denominada mytable em mydataset.

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

O comando seguinte carrega dados de gs://mybucket/mydata.orc para uma nova tabela particionada por tempo de carregamento denominada mytable em mydataset.

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

O comando seguinte carrega dados de gs://mybucket/mydata.orc para uma tabela particionada denominada mytable em mydataset. A tabela está particionada na coluna mytimestamp.

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

O comando seguinte carrega dados de vários ficheiros em gs://mybucket/ para uma tabela denominada mytable em mydataset. O URI do Cloud Storage usa um caráter universal.

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

O comando seguinte carrega dados de vários ficheiros em gs://mybucket/ para uma tabela denominada mytable em mydataset. O comando inclui uma lista de URIs do Cloud Storage separados por vírgulas com carateres universais.

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

API

  1. Crie uma tarefa load que aponte para os dados de origem no Cloud Storage.

  2. (Opcional) Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

  3. A propriedade source URIs tem de ser totalmente qualificada, no formato gs://bucket/object. Cada URI pode conter um carater universal "*".

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

  5. Para verificar o estado da tarefa, chame jobs.get(job_id*), onde job_id é o ID da tarefa devolvido pelo pedido inicial.

    • Se status.state = DONE, a tarefa foi concluída com êxito.
    • Se a propriedade status.errorResult estiver presente, o pedido falhou e esse objeto inclui informações que descrevem o que correu mal. Quando um pedido falha, não é criada nenhuma tabela nem são carregados dados.
    • Se status.errorResult estiver ausente, a tarefa foi concluída com êxito, embora possam ter ocorrido alguns erros não fatais, como problemas na importação de algumas linhas. Os erros não fatais são apresentados na propriedade status.errors do objeto de tarefa devolvido.

Notas da API:

  • Os trabalhos de carregamento são atómicos e consistentes. Se um trabalho de carregamento falhar, nenhum dos dados está disponível. Se um trabalho de carregamento for bem-sucedido, todos os dados estão disponíveis.

  • Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId quando chamar jobs.insert para criar uma tarefa de carregamento. Esta abordagem é mais robusta em caso de falha de rede, uma vez que o cliente pode sondar ou tentar novamente com o ID da tarefa conhecido.

  • A chamada jobs.insert num determinado ID da tarefa é idempotente. Pode tentar novamente quantas vezes quiser com o mesmo ID do trabalho e, no máximo, uma dessas operações é bem-sucedida.

C#

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.


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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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

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 experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

// 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 experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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 experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Ruby BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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

Anexe ou substitua uma tabela com dados ORC

Pode carregar dados adicionais para uma tabela a partir de ficheiros de origem ou acrescentando resultados de consultas.

Na Trusted Cloud consola, use a opção Preferência de escrita para especificar que ação realizar quando carregar dados de um ficheiro de origem ou de um resultado de consulta.

Tem as seguintes opções quando carrega dados adicionais numa tabela:

Opção da consola Sinalização da ferramenta bq Propriedade da API BigQuery Descrição
Escrever se estiver vazio Não suportado WRITE_EMPTY Escreve os dados apenas se a tabela estiver vazia.
Anexar à tabela --noreplace ou --replace=false; se --[no]replace não estiver especificado, a predefinição é anexar WRITE_APPEND (Predefinição) Anexa os dados ao final da tabela.
Substituir tabela --replace ou --replace=true WRITE_TRUNCATE Apaga todos os dados existentes numa tabela antes de escrever os novos dados. Esta ação também elimina o esquema da tabela, a segurança ao nível da linha e remove qualquer chave do Cloud KMS.

Se carregar dados para uma tabela existente, a tarefa de carregamento pode anexar os dados ou substituir a tabela.

Pode acrescentar ou substituir uma tabela:

  • Usar a Trusted Cloud consola
  • Usar o comando bq load da ferramenta de linhas de comando bq
  • Chamar o método da API jobs.insert e configurar uma tarefa load
  • Usar as bibliotecas de cliente

Para acrescentar ou substituir uma tabela com dados ORC:

Consola

  1. Na Trusted Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
  3. Na secção Informações do conjunto de dados, clique em Criar tabela.
  4. No painel Criar tabela, especifique os seguintes detalhes:
    1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
      1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Trusted Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir. selecione o ficheiro de origem para criar uma tabela do BigQuery
      2. Em Formato de ficheiro, selecione ORC.
    2. Na secção Destino, especifique os seguintes detalhes:
      1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
      2. No campo Tabela, introduza o nome da tabela que quer criar.
      3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
    3. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros ORC.
    4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas. Não pode converter uma tabela numa tabela particionada ou agrupada anexando-a ou substituindo-a. A Trusted Cloud consola não suporta a anexação nem a substituição de tabelas particionadas ou agrupadas num trabalho de carregamento.
    5. Clique em Opções avançadas e faça o seguinte:
      • Para Preferência de escrita, escolha Anexar à tabela ou Substituir tabela.
      • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
      • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google Cloud-powered key, o BigQuery encripta os dados em repouso.
    6. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte anexa um ficheiro ORC à tabela mytable:

  1. Na Trusted Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaração:

    LOAD DATA INTO mydataset.mytable
    FROM FILES (
      format = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Introduza o comando bq load com a flag --replace para substituir a tabela. Use a flag --noreplace para anexar dados à tabela. Se não for especificada nenhuma flag, a predefinição é anexar dados. Forneça a flag --source_format e defina-a como ORC. Uma vez que os esquemas ORC são obtidos automaticamente a partir dos dados de origem autodescritivos, não tem de fornecer uma definição de esquema.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

Outras flags opcionais incluem:

  • --destination_kms_key: a chave do Cloud KMS para a encriptação dos dados da tabela.
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Onde:

  • location é a sua localização. A flag --location é opcional. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
  • format é ORC.
  • dataset é um conjunto de dados existente.
  • table é o nome da tabela para a qual está a carregar dados.
  • path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgula. Os carateres universais também são suportados.

Exemplos:

O comando seguinte carrega dados de gs://mybucket/mydata.orc e substitui uma tabela denominada mytable em mydataset.

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

O comando seguinte carrega dados de gs://mybucket/mydata.orc e anexa dados a uma tabela denominada mytable em mydataset.

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

Para ver informações sobre como anexar e substituir tabelas particionadas através da ferramenta de linha de comandos bq, consulte: Anexar e substituir dados de tabelas particionadas.

API

  1. Crie uma tarefa load que aponte para os dados de origem no Cloud Storage.

  2. (Opcional) Especifique a sua localização na propriedade location na secção jobReference do recurso de trabalho.

  3. A propriedade source URIs tem de ser totalmente qualificada, no formato gs://bucket/object. Pode incluir vários URIs como uma lista separada por vírgulas. Tenha em atenção que os carateres universais também são suportados.

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

  5. Especifique a preferência de escrita definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

C#

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.


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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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

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

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

// 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 experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

Para substituir as linhas numa tabela existente, defina a propriedade LoadJobConfig.write_disposition como WRITE_TRUNCATE.
import io

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 = io.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

Antes de experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Ruby BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr.

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

Carregue dados ORC particionados por Hive

O BigQuery suporta o carregamento de dados ORC particionados por Hive armazenados no Cloud Storage e preenche as colunas de particionamento por Hive como colunas na tabela gerida do BigQuery de destino. Para mais informações, consulte o artigo Carregar dados particionados externamente a partir do Cloud Storage.

Conversões ORC

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

Tipos primitivos

Tipo de dados ORC Tipo de dados do BigQuery Notas
booleano BOOLEAN
byte INTEGER
curto INTEGER
int INTEGER
longo INTEGER
flutuante FLOAT
dupla FLOAT
de string STRING Apenas UTF-8
varchar STRING Apenas UTF-8
char STRING Apenas UTF-8
binário BYTES
data DATA Uma tentativa de converter qualquer valor nos dados ORC inferior a -719162 dias ou superior a 2932896 dias devolve um erro invalid date value. Se esta situação lhe afetar, contacte o apoio técnico para que os valores não suportados sejam convertidos no valor mínimo do BigQuery de 0001-01-01 ou no valor máximo de 9999-12-31, conforme adequado.
timestamp TIMESTAMP

O ORC suporta a precisão de nanossegundos, mas o BigQuery converte os valores inferiores a microssegundos em microssegundos quando os dados são lidos.

Uma tentativa de converter qualquer valor nos dados ORC inferior a -719162 dias ou superior a 2932896 dias devolve um erro invalid date value. Se isto lhe afetar, contacte o apoio técnico para que os valores não suportados sejam convertidos no valor mínimo do BigQuery de 0001-01-01 ou no valor máximo de 9999-12-31, conforme adequado.

decimal NUMERIC, BIGNUMERIC ou STRING Consulte a secção Tipo decimal.

Tipo decimal

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

Tipos complexos

Tipo de dados ORC Tipo de dados do BigQuery Notas
struct RECORD
  • Todos os campos são NULLABLE.
  • A ordem dos campos é ignorada.
  • O nome de um campo tem de ser um nome de coluna válido.
map<K,V> RECORD Um campo de mapa ORC<K,V> é convertido num 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. Ambos os campos são NULLABLE.
lista campos repetidos Não são suportadas listas aninhadas nem listas de mapas.
união RECORD
  • Quando a união tem apenas uma variante, é convertida num campo NULLABLE.
  • Caso contrário, uma união é convertida num RECORD com uma lista de campos NULLABLE. Os campos NULLABLE têm sufixos como field_0, field_1, e assim sucessivamente. Apenas um destes campos tem um valor atribuído quando os dados são lidos.

Nomes das colunas

Um nome de coluna pode conter letras (a-z, A-Z), números (0-9) ou sublinhados (_), e tem de começar por uma letra ou um sublinhado. Se usar nomes de colunas flexíveis, o BigQuery suporta o início de um nome de coluna com um número. Tenha cuidado ao iniciar colunas com um número, uma vez que a utilização de nomes de colunas flexíveis com a API BigQuery Storage Read ou a API BigQuery Storage Write requer um processamento especial. Para mais informações sobre o suporte de nomes de colunas flexíveis, consulte o artigo Nomes de colunas flexíveis.

Os nomes das colunas têm um comprimento máximo de 300 carateres. Os nomes das colunas não podem usar nenhum dos seguintes prefixos:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

Não são permitidos nomes de colunas duplicados, mesmo que a utilização de maiúsculas e minúsculas seja diferente. Por exemplo, uma coluna denominada Column1 é considerada idêntica a uma coluna denominada column1. Para saber mais sobre as regras de nomenclatura de colunas, consulte Nomes das colunas na referência do GoogleSQL.

Se o nome de uma tabela (por exemplo, test) for igual a um dos nomes das respetivas colunas (por exemplo, test), a expressão SELECT interpreta a coluna test como um STRUCT que contém todas as outras colunas da tabela. Para evitar esta colisão, use um dos seguintes métodos:

  • Evite usar o mesmo nome para uma tabela e as respetivas colunas.

  • Atribua um alias diferente à tabela. Por exemplo, a seguinte consulta atribui um alias de tabela t à tabela project1.dataset.test:

    SELECT test FROM project1.dataset.test AS t;
    
  • Inclua o nome da tabela quando fizer referência a uma coluna. Por exemplo:

    SELECT test.test FROM project1.dataset.test;
    

Nomes de colunas flexíveis

Tem mais flexibilidade na forma como denomina as colunas, incluindo acesso expandido a carateres em idiomas que não o inglês, bem como símbolos adicionais. Certifique-se de que usa carateres de acento grave (`) para incluir nomes de colunas flexíveis se forem Identificadores entre aspas.

Os nomes de colunas flexíveis suportam os seguintes carateres:

  • Qualquer letra em qualquer idioma, conforme representado pela expressão regular Unicode \p{L}.
  • Qualquer caráter numérico em qualquer idioma, representado pela expressão regular Unicode \p{N}.
  • Qualquer caráter de pontuação de conetor, incluindo sublinhados, conforme representado pela expressão regular Unicode \p{Pc}.
  • Um hífen ou um travessão representado pela expressão regular Unicode \p{Pd}.
  • Qualquer marca destinada a acompanhar outro caráter, conforme representado pela expressão regular Unicode \p{M}. Por exemplo, acentos, trema ou caixas delimitadoras.
  • Os seguintes carateres especiais:
    • Um E comercial (&), representado pela expressão regular Unicode \u0026.
    • Um sinal de percentagem (%) representado pela expressão regular Unicode \u0025.
    • Um sinal de igual (=) representado pela expressão regular Unicode \u003D.
    • Um sinal de mais (+) representado pela expressão regular Unicode \u002B.
    • Um dois pontos (:) representado pela expressão regular Unicode \u003A.
    • Um apóstrofo (') representado pela expressão regular Unicode \u0027.
    • Um sinal de menor do que (<), representado pela expressão regular Unicode \u003C.
    • Um sinal de maior do que (>) representado pela expressão regular Unicode \u003E.
    • Um sinal de número (#), representado pela expressão regular Unicode \u0023.
    • Uma linha vertical (|) representada pela expressão regular Unicode \u007c.
    • Espaço em branco.

Os nomes de colunas flexíveis não suportam os seguintes carateres especiais:

  • Um ponto de exclamação (!) representado pela expressão regular Unicode \u0021.
  • Uma marca de aspas ("), representada pela expressão regular Unicode \u0022.
  • Um cifrão ($) representado pela expressão regular Unicode \u0024.
  • Um parêntese esquerdo (() representado pela expressão regular Unicode \u0028.
  • Um parêntese direito ()), representado pela expressão regular Unicode \u0029.
  • Um asterisco (*), representado pela expressão regular Unicode \u002A.
  • Uma vírgula (,) representada pela expressão regular Unicode \u002C.
  • Um ponto (.), representado pela expressão regular Unicode \u002E. Os pontos não são substituídos por sublinhados nos nomes das colunas do ficheiro Parquet quando é usado um mapa de carateres do nome da coluna. Para mais informações, consulte as limitações das colunas flexíveis.
  • Uma barra (/) representada pela expressão regular Unicode \u002F.
  • Um ponto e vírgula (;) representado pela expressão regular Unicode \u003B.
  • Um ponto de interrogação (?), representado pela expressão regular Unicode \u003F.
  • Um sinal de arroba (@) representado pela expressão regular Unicode \u0040.
  • Um parêntesis reto esquerdo ([) representado pela expressão regular Unicode \u005B.
  • Uma barra invertida (\), representada pela expressão regular Unicode \u005C.
  • Um parêntesis reto direito (]), representado pela expressão regular Unicode \u005D.
  • Um acento circunflexo (^), representado pela expressão regular Unicode \u005E.
  • Um acento grave (`) representado pela expressão regular Unicode \u0060.
  • Uma chaveta esquerda {{) representada pela expressão regular Unicode \u007B.
  • Uma chaveta direita (}) representada pela expressão regular Unicode \u007D.
  • Um til (~) representado pela expressão regular Unicode \u007E.

Para ver diretrizes adicionais, consulte o artigo Nomes das colunas.

Os carateres de coluna expandidos são suportados pela API BigQuery Storage Read e pela API BigQuery Storage Write. Para usar a lista expandida de carateres Unicode com a API BigQuery Storage Read, tem de definir uma flag. Pode usar o atributo displayName para obter o nome da coluna. O exemplo seguinte mostra como definir uma flag com o cliente Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Para usar a lista expandida de carateres Unicode com a API Storage Write do BigQuery, tem de fornecer o esquema com a notação column_name, a menos que esteja a usar o objeto de gravação JsonStreamWriter. O exemplo seguinte mostra como fornecer o esquema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

Neste exemplo, item_name_column e item_description_column são nomes de marcadores de posição que têm de estar em conformidade com a convenção de nomenclatura do protocol buffer. Tenha em atenção que as anotações column_name têm sempre precedência sobre os nomes dos marcadores de posição.

Limitações

Valores NULL

Tenha em atenção que, para tarefas de carregamento, o BigQuery ignora os elementos NULL para o tipo composto list, uma vez que, caso contrário, seriam traduzidos em elementos NULL ARRAY que não podem persistir numa tabela (consulte Tipos de dados para obter detalhes).

Para mais informações sobre os tipos de dados ORC, consulte a especificação Apache ORC™ v1.