Carregue dados Avro a partir do Cloud Storage

O Avro é um formato de dados de código aberto que agrupa dados serializados com o esquema dos dados no mesmo ficheiro.

Quando carrega dados Avro 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 no 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 Avro 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.

As seguintes limitações também se aplicam quando carrega ficheiros Avro para o BigQuery:

  • O BigQuery não suporta o carregamento de ficheiros de esquema Avro (.avsc) autónomos.
  • A formatação de matrizes aninhadas não é suportada no BigQuery. Os ficheiros Avro que usam este formato têm de ser convertidos antes da importação.
  • Num ficheiro Avro, os nomes e os espaços de nomes de um nome completo só podem conter carateres alfanuméricos e o caráter de sublinhado _. A seguinte expressão regular mostra os carateres permitidos: [A-Za-z_][A-Za-z0-9_]*.

Para informações sobre os limites de tarefas de carregamento do BigQuery, consulte o artigo Tarefas de carregamento.

Requisitos do ficheiro de entrada

Para evitar erros resourcesExceeded ao carregar ficheiros Avro no BigQuery, siga estas diretrizes:

  • Mantenha os tamanhos das linhas iguais ou inferiores a 50 MB.
  • Se a linha contiver muitos campos de matriz ou campos de matriz muito longos, divida os valores da matriz em campos separados.

Antes de começar

Atribua funções de gestão de identidade e acesso (IAM) que concedam aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento e crie um conjunto de dados e uma tabela 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 e uma tabela

Para armazenar os seus dados, tem de criar um conjunto de dados do BigQuery e, de seguida, criar uma tabela do BigQuery nesse conjunto de dados.

Vantagens do Avro

O formato Avro é o formato preferido para carregar dados no BigQuery. O carregamento de ficheiros Avro tem as seguintes vantagens em relação aos ficheiros CSV e JSON (delimitados por nova linha):

  • O formato binário Avro:
    • É mais rápido de carregar. Os dados podem ser lidos em paralelo, mesmo que os blocos de dados estejam comprimidos.
    • Não requer introdução de texto nem serialização.
    • É mais fácil de analisar porque não existem problemas de codificação encontrados noutros formatos, como o ASCII.
  • Quando carrega ficheiros Avro para o BigQuery, o esquema da tabela é obtido automaticamente dos dados de origem autodescritivos.

Esquemas Avro

Quando carrega ficheiros Avro para uma nova tabela do BigQuery, o esquema da tabela é obtido automaticamente através dos dados de origem. Quando o BigQuery extrai o esquema dos dados de origem, é usado o ficheiro que aparece por último por ordem alfabética.

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

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

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.avro:

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

Quando importa vários ficheiros Avro com esquemas Avro diferentes, todos os esquemas têm de ser compatíveis com a resolução de esquemas do Avro.

Quando o BigQuery deteta o esquema, alguns tipos de dados Avro são convertidos em tipos de dados do BigQuery para os tornar compatíveis com a sintaxe do GoogleSQL. Para mais informações, consulte o artigo Conversões Avro.

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.avro".

Também pode importar o esquema para o BigQuery especificando um ficheiro de esquema JSON.

Compressão Avro

O BigQuery suporta os seguintes codecs de compressão para o conteúdo de ficheiros Avro:

  • Snappy
  • DEFLATE
  • ZSTD

Carregar dados Avro para uma nova tabela

Para carregar dados Avro do Cloud Storage para uma nova tabela do BigQuery, selecione uma das seguintes opções:

Consola

  1. Na Trusted Cloud consola, abra a página do BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o projeto e selecione um conjunto de dados.

  3. Expanda a opção Ações e clique em Abrir.

  4. No painel de detalhes, clique em Criar tabela .

  5. Na página Criar tabela, na secção Origem:

    • Em Criar tabela a partir de, selecione Google Cloud Storage.

    • No campo de origem, procure ou introduza o URI do Cloud Storage. Tenha em atenção que não pode incluir vários URIs na Trusted Cloud consola, mas caracteres 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 está a criar.

      Selecione o ficheiro

    • Em Formato de ficheiro, selecione Avro.

  6. Na página Criar tabela, na secção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto de dados adequado.
    • Verifique se o Tipo de tabela está definido como Tabela nativa.
    • No campo Nome da tabela, introduza o nome da tabela que está a criar no BigQuery.
  7. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros Avro.

  8. (Opcional) Para particionar a tabela, escolha as suas opções nas Definições de partição e agrupamento. Para mais informações, consulte o artigo Criar tabelas particionadas.

  9. (Opcional) Para o Filtro de partição, clique na caixa Exigir filtro de partição para exigir que os utilizadores incluam uma cláusula WHERE que especifique as partições a consultar. A exigência de 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. Esta opção não está disponível se a opção Sem criação de partições estiver selecionada.

  10. (Opcional) Para agrupar a tabela, na caixa Ordem de agrupamento, introduza entre um e quatro nomes de campos.

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

    • 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.
    • Para Valores desconhecidos, deixe a opção Ignorar valores desconhecidos desmarcada. Esta opção aplica-se apenas a ficheiros CSV e JSON.
    • 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.
  12. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte carrega um ficheiro Avro para a 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 = 'avro',
      uris = ['gs://bucket/path/file.avro']);

  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 AVRO usando a flag --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 Avro para o BigQuery, introduza o seguinte comando:

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

Substitua o seguinte:

  • 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 é AVRO.
  • 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írgulas. Os carateres universais também são suportados.

Exemplos:

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

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

O comando seguinte carrega dados de gs://mybucket/mydata.avro para uma tabela particionada por tempo de ingestão denominada mytable em mydataset.

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

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

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

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=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

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 \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

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 caráter universal "*".

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

  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 da tarefa e, no máximo, uma dessas operações vai ter êxito.

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"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java 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 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 load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // 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.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(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.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } 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 Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

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

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // 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), jobConfigurationLoad);

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

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.AVRO)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

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

Extraia dados JSON de dados Avro

Existem duas formas de garantir que os dados Avro são carregados para o BigQuery como dados JSON:

  1. Anote o seu esquema Avro com sqlType definido como JSON. Por exemplo, se carregar dados com o seguinte esquema Avro, a coluna json_field é lida como um tipo JSON:

    {
        "type": {"type": "string", "sqlType": "JSON"},
        "name": "json_field"
    }
  2. Especifique o esquema da tabela de destino do BigQuery explicitamente e defina o tipo de coluna como JSON. Para mais informações, consulte o artigo Especificar um esquema.

Se não especificar JSON como o tipo no esquema Avro ou no esquema da tabela do BigQuery, os dados são lidos como STRING.

Anexar ou substituir uma tabela com dados Avro

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.

Para acrescentar ou substituir uma tabela com dados Avro:

Consola

  1. Na Trusted Cloud consola, abra a página do BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o projeto e selecione um conjunto de dados.

  3. Expanda a opção Ações e clique em Abrir.

  4. No painel de detalhes, clique em Criar tabela .

  5. Na página Criar tabela, na secção Origem:

    • Em Criar tabela a partir de, selecione Cloud Storage.
    • No campo de origem, procure ou introduza o URI do Cloud Storage. Tenha em atenção que não pode incluir vários URIs na Trusted Cloud consola, mas os caracteres 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 está a acrescentar ou substituir.

      Selecione o ficheiro

    • Em Formato de ficheiro, selecione Avro.

  6. Na página Criar tabela, na secção Destino:

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

      Selecionar conjunto de dados

    • No campo Nome da tabela, introduza o nome da tabela que está a anexar ou substituir no BigQuery.

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

  7. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros Avro.

  8. Para as Definições de partição e cluster, deixe os valores predefinidos. Não pode converter uma tabela numa tabela particionada ou agrupada anexando-a ou substituindo-a, e a Trusted Cloud consola não suporta a anexação nem a substituição de tabelas particionadas ou agrupadas numa tarefa de carregamento.

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

    • Para Preferência de escrita, escolha Anexar à tabela ou Substituir tabela.
    • Para Valores desconhecidos, deixe a opção Ignorar valores desconhecidos desmarcada. Esta opção aplica-se apenas a ficheiros CSV e JSON.
    • 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.
  10. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte anexa um ficheiro Avro à 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 = 'avro',
      uris = ['gs://bucket/path/file.avro']);

  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 AVRO. Uma vez que os esquemas Avro são obtidos automaticamente 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

Substitua o seguinte:

  • location é a sua localização. A flag --location é opcional. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
  • format é AVRO.
  • 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írgulas. Os carateres universais também são suportados.

Exemplos:

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

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

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

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

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"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java 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 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 AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // 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.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      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.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO 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 clients
const bigquery = new BigQuery();
const storage = new Storage();

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

async function loadTableGCSAvroTruncate() {
  /**
   * 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 = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // 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), jobConfigurationLoad);

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

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.

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.AVRO,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
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))

Carregar dados Avro particionados por Hive

O BigQuery suporta o carregamento de dados Avro 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 Avro

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

Tipos primitivos

Tipo de dados Avro sem o atributo logicalType Tipo de dados do BigQuery Notas
nulo O BigQuery ignora estes valores
booleano BOOLEAN
int INTEGER
longo INTEGER
flutuante FLOAT
dupla FLOAT
bytes BYTES
de string STRING Apenas UTF-8

Tipos lógicos

Por predefinição, o BigQuery ignora o atributo logicalType para a maioria dos tipos e usa o tipo Avro subjacente. Para converter tipos lógicos Avro nos respetivos tipos de dados do BigQuery, defina a flag --use_avro_logical_types como true através da ferramenta de linha de comandos bq ou defina a propriedade useAvroLogicalTypes no recurso de tarefa quando chamar o método jobs.insert para criar uma tarefa de carregamento.

A tabela abaixo mostra a conversão de tipos lógicos Avro em tipos de dados do BigQuery.

Tipo lógico Avro Tipo de dados do BigQuery: tipo lógico desativado Tipo de dados do BigQuery: tipo lógico ativado
data INTEGER DATA
time-millis INTEGER HORA
time-micros INTEGER (convertido de LONG) HORA
timestamp-millis INTEGER (convertido de LONG) TIMESTAMP
timestamp-micros INTEGER (convertido de LONG) TIMESTAMP
local-timestamp-millis INTEGER (convertido de LONG) DATA/HORA
local-timestamp-micros INTEGER (convertido de LONG) DATA/HORA
duração BYTES (convertido do tipo fixed de tamanho 12) BYTES (convertido do tipo fixed de tamanho 12)
decimal NUMERIC, BIGNUMERIC ou STRING (consulte o tipo lógico decimal) NUMERIC, BIGNUMERIC ou STRING (consulte o tipo lógico decimal)

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

Tipo lógico de data

Em qualquer ficheiro Avro que pretenda carregar, tem de especificar tipos lógicos de data no seguinte formato:

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

Tipo lógico 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:

Para compatibilidade com versões anteriores, se os tipos de destino decimais não forem especificados, pode carregar um ficheiro Avro que contenha uma coluna bytes com o tipo lógico decimal numa coluna BYTES de uma tabela existente. Neste caso, o tipo lógico decimal na coluna do ficheiro Avro é ignorado. Este modo de conversão foi descontinuado e pode ser removido no futuro.

Para mais informações sobre o tipo lógico decimal do Avro, consulte a especificação do Apache Avro™ 1.8.2.

Tipo lógico de tempo

Em qualquer ficheiro Avro que pretenda carregar, tem de especificar tipos lógicos de tempo num dos seguintes formatos.

Para uma precisão de milissegundos:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Para precisão de microssegundos:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Tipo lógico de data/hora

Em qualquer ficheiro Avro que pretenda carregar, tem de especificar tipos lógicos de indicação de tempo num dos seguintes formatos.

Para uma precisão de milissegundos:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Para precisão de microssegundos:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Tipo lógico de data/hora local

Em qualquer ficheiro Avro que pretenda carregar, tem de especificar um tipo lógico de data/hora local num dos seguintes formatos.

Para uma precisão de milissegundos:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Para precisão de microssegundos:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

Tipos complexos

Tipo de dados Avro Tipo de dados do BigQuery Notas
gravar RECORD
  • Os aliases são ignorados
  • O documento é convertido numa descrição do campo
  • Os valores predefinidos são definidos no momento da leitura
  • A encomenda é ignorada
  • Os campos recursivos são ignorados. Apenas o primeiro nível de aninhamento é mantido para campos recursivos
enum STRING
  • A string é o valor simbólico da enumeração
  • Os aliases são ignorados
  • O documento é convertido numa descrição do campo
matriz campos repetidos As matrizes de matrizes não são suportadas. As matrizes que contêm apenas tipos NULL são ignoradas.
map<T> RECORD O BigQuery converte um campo de mapa<T> Avro num RECORD repetido que contém dois campos: uma chave e um valor. O BigQuery armazena a chave como uma STRING e converte o valor no respetivo tipo de dados no BigQuery.
união
  • Campo anulável
  • RECORD com uma lista de campos anuláveis
  • Quando a união tem apenas um tipo não nulo, é convertida num campo anulável.
  • Caso contrário, é convertido num REGISTO com uma lista de campos anuláveis. Apenas um destes campos é definido no momento da leitura.
fixo BYTES
  • Os aliases são ignorados
  • O tamanho é ignorado