Como carregar dados Avro do Cloud Storage

Avro é um formato de dados de código aberto que possibilita o agrupamento de dados serializados com o esquema de dados no mesmo arquivo.

Ao carregar dados Avro do Cloud Storage, é possível carregá-los em uma nova tabela ou partição, anexar dados a uma tabela ou partição existente, ou substituir uma tabela ou partição existente. Quando os dados são carregados no BigQuery, eles são convertidos no formato de colunas do Capacitor, o formato de armazenamento do BigQuery.

Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que contém a tabela precisa estar na mesma região ou multirregião que o bucket do Cloud Storage.

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

Observação: o BigQuery não é compatível com o carregamento de arquivos autônomos Avro (.avsc). Para importar um esquema para o BigQuery, especifique um arquivo de esquema JSON.

Limitações

Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:

• Se o local do conjunto de dados estiver definido como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados.
• O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.
• O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.

Requisitos para arquivos de entrada

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

• Mantenha tamanhos de linha de 50 MB ou menos.
• Se a linha contiver muitos campos de matriz ou qualquer campo de matriz muito longo, divida os valores da matriz em campos separados.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedem aos usuários as permissões necessárias para executar cada tarefa neste documento e crie um conjunto de dados para armazenar seus dados.

Permissões necessárias

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

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

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

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

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

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Criar um conjunto de dados e uma tabela

Para armazenar seus dados, crie um conjunto de dados do BigQuery e, em seguida, crie uma tabela do BigQuery nesse conjunto de dados.

Vantagens do Avro

O Avro é o formato preferido para carregar dados no BigQuery. O carregamento de arquivos Avro tem as seguintes vantagens sobre CSV e JSON (delimitado por nova linha):

• O formato binário Avro:
  • é mais rápido para carregar. Os dados podem ser lidos em paralelo, mesmo que os blocos de dados estejam compactados;
  • não requer digitação ou serialização;
  • é mais fácil de analisar porque não há os problemas de codificação encontrados em outros formatos, como o ASCII.
• Ao carregar arquivos Avro no BigQuery, o esquema da tabela é recuperado automaticamente dos dados de origem autoexplicativos.

Esquemas Avro

Ao carregar arquivos Avro em uma nova tabela do BigQuery, o esquema da tabela é recuperado automaticamente usando os dados de origem. Quando o BigQuery recupera o esquema dos dados de origem, o último arquivo em ordem alfabética é usado.

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

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

Executar esse comando na ferramenta de linha de comando bq carrega todos os arquivos (como uma lista separada por vírgulas) e o esquema é derivado de mybucket/01/b.avro:

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

Todos os esquemas precisam ser compatíveis com a Resolução de esquema da Avro ao importar vários arquivos nesse formato.

Quando o BigQuery detecta o esquema, alguns tipos de dados Avro são convertidos em tipos de dados do BigQuery para torná-los compatíveis com a sintaxe do GoogleSQL. Para saber mais informações, consulte as 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 comando bq como o URL do arquivo de referência.

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

Compactação Avro

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

• Snappy
• DEFLATE
• ZSTD

Como carregar dados Avro em uma nova tabela

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

Console

1. No Console do Google Cloud, abra a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, 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 seção Origem:

   • Em Criar tabela de, selecione Google Cloud Storage.

   • No campo de origem, navegue até o URI do Cloud Storage ou insira-o. Não é possível incluir vários URIs no Console do Cloud, mas os caracteres curinga são compatíveis. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela sendo criada.

     

   • Em Formato de arquivo, selecione Avro.

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

   • Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
   • Verifique se o Tipo de tabela está definido como Tabela nativa.
   • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

7. Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.

8. (Opcional) Para particionar a tabela, escolha as opções nas Configurações de particionamento e do cluster: Para mais informações, consulte Como criar tabelas particionadas.

9. (Opcional) Em Filtro de particionamento, clique na caixa Exigir filtro de particionamento para solicitar que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte Exigir um filtro de partição em consultas. Essa opção ficará indisponível se a opção Sem particionamento estiver selecionada.

10. Opcional: para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering.

11. Opcional: clique em Opções avançadas.

    • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Essa opção cria uma nova tabela e carrega seus dados nela.
    • Em Valores desconhecidos, deixe a opção Ignorar valores desconhecidos desmarcada. Essa opção se refere apenas a arquivos CSV e JSON.
    • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.

12. Selecione Criar tabela.

Observação: ao carregar dados em uma tabela vazia usando o Console do Cloud, não será possível adicionar um rótulo, uma descrição ou uma validade de tabela ou de partição.

Após a criação da tabela, é possível atualizar a validade, a descrição e os identificadores dela. No entanto, não é possível adicionar uma validade de partição depois de criar uma tabela com o console do Google Cloud. Para mais informações, consulte Como gerenciar tabelas.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir carrega um arquivo Avro na nova tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instruçã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, acesse Executar uma consulta interativa.

bq

Use o comando bq load, especifique AVRO usando o sinalizador --source_format e inclua um URI do Cloud Storage É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.

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

Estas são outras sinalizações opcionais:

• --time_partitioning_type: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição padrão para o particionamento baseado em tempo é DAY. Não é possível alterar a especificação de particionamento em uma tabela existente.
• --time_partitioning_expiration: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.
• --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se o particionamento baseado em tempo for ativado sem esse valor, será criada uma tabela particionada por tempo de processamento.
• --require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que especifica as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte Exigir um filtro de partição em consultas.
• --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.

• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

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

  • Como criar tabelas particionadas

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

  • Como criar e usar tabelas em cluster

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

  • Como proteger dados com chaves do Cloud KMS

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

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

Substitua:

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

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.avro em uma tabela chamada mytable em mydataset.

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

O comando a seguir carrega dados de gs://mybucket/mydata.avro em uma tabela particionada por tempo de processamento chamada mytable em mydataset.

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

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

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

O comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O URI do Cloud Storage usa um caractere curinga.

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

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

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

API

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

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

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

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

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

   • status.state = DONE indica que o job foi concluído.
   • A propriedade status.errorResult mostra que houve falha na solicitação e o objeto incluirá informações que descrevem o erro. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados.
   • A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que haja alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

• Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.

• Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.

• Chamar jobs.insert em um determinado ID do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID e, no máximo, uma das operações será bem-sucedida.

Go

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Extrair dados JSON de dados Avro

Há duas maneiras de garantir que os dados Avro sejam carregados no BigQuery como dados JSON:

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

   {
       "type": {"type": "string", "sqlType": "JSON"},
       "name": "json_field"
   }

2. Especifique explicitamente o esquema da tabela de destino do BigQuery e defina o tipo de coluna como JSON. Para mais informações, consulte Como especificar um esquema.

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

Como anexar ou substituir uma tabela com dados Avro

Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.

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

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

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

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

Observação: nesta página, não é abordado como anexar ou substituir tabelas particionadas. Para informações sobre esse assunto, consulte Como anexar e substituir dados de tabelas particionadas.

Para anexar ou substituir uma tabela com dados Avro:

Console

1. No Console do Google Cloud, abra a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, 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 seção Origem:

   • Em Criar tabela de, selecione Cloud Storage.

   • No campo de origem, procure ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no Console do Cloud, mas os caracteres curinga são compatíveis. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está anexando ou substituindo.

     

   • Em Formato de arquivo, selecione Avro.

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

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

     

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

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

7. Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.

   Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.

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

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

   • Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
   • Em Valores desconhecidos, deixe a opção Ignorar valores desconhecidos desmarcada. Essa opção se refere apenas a arquivos CSV e JSON.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.

10. Selecione Criar tabela.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir anexa um arquivo Avro à tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instruçã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, acesse Executar uma consulta interativa.

bq

Digite o comando bq load com a sinalização --replace para substituir a tabela. Use a sinalização --noreplace para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados. Forneça a sinalização --source_format e defina-a como AVRO. Como os esquemas Avro são recuperados automaticamente dos dados de origem autodescritivos, não é necessário fornecer uma definição de esquema.

Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.

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

Estas são outras sinalizações opcionais:

• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Substitua:

• location é o local. A sinalização --location é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
• format é AVRO.
• dataset é um conjunto de dados atual;
• table é o nome da tabela em que você carregará dados;
• path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Caracteres curinga também são aceitos.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.avro e substitui uma tabela chamada mytable em mydataset.

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

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

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

Para informações sobre como anexar e substituir tabelas particionadas usando a ferramenta de linha de comando bq, consulte: Como anexar e substituir dados de tabelas particionadas.

API

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

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

3. A propriedade source URIs precisa ser totalmente qualificada no formato gs://bucket/object. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são compatíveis.

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

5. Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

Go

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Como carregar dados Avro particionados do Hive

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

Conversões Avro

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

Tipos primitivos

Tipo de dados Avro sem atributo lógicoType	Tipo de dados do BigQuery	Observações
nulo	O BigQuery ignora esses valores
booleano	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
string	STRING	somente UTF-8

Tipos lógicos

Por padrão, o BigQuery ignora o atributo logicalType para a maioria dos tipos e usa o tipo Avro subjacente. Para converter tipos lógicos do Avro para os tipos de dados correspondentes do BigQuery, defina a sinalização --use_avro_logical_types como true usando a ferramenta de linha de comando bq ou configure a propriedade useAvroLogicalTypes no recurso do job ao chamar o método jobs.insert para criar um job 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	DATE
time-millis	INTEGER	TIME
time-micros	INTEGER (convertido de LONG)	TIME
timestamp-millis	INTEGER (convertido de LONG)	TIMESTAMP
timestamp-micros	INTEGER (convertido de LONG)	TIMESTAMP
local-timestamp-millis	INTEGER (convertido de LONG)	DATETIME
local-timestamp-micros	INTEGER (convertido de LONG)	DATETIME
duration	BYTES (convertido do tipo fixed de tamanho 12)	BYTES (convertido do tipo fixed de tamanho 12)
decimal	NUMERIC, BIGNUMERIC ou STRING (consulte Tipo lógico decimal)	NUMERIC, BIGNUMERIC ou STRING (consulte Tipo lógico decimal)

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

Observação: ao exportar do Avro para o BigQuery, o DATETIME é exportado como um STRING com um tempo lógico personalizado que não é reconhecido como DATETIME ao fazer a importação de volta para o BigQuery.

Tipo lógico de data

Em qualquer arquivo Avro que você queira carregar, é necessário 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 escalonamento do tipo lógico decimal e dos tipos decimais de destino especificados. Especifique o tipo decimal de destino da seguinte forma:

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

Para compatibilidade com versões anteriores, se os tipos de destino decimais não forem especificados, você poderá carregar um arquivo Avro contendo uma coluna bytes com o tipo lógico decimal em uma coluna BYTES de um existente. . Nesse caso, o tipo lógico decimal na coluna no arquivo Avro é ignorado. Esse modo de conversão está obsoleto e poderá ser removido no futuro.

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

Tipo lógico de horário

Em qualquer arquivo Avro que você pretende carregar, é necessário especificar tipos lógicos de tempo em um dos formatos a seguir.

Para 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 carimbo de data/hora

Em qualquer arquivo Avro que você queira carregar, especifique os tipos lógicos de carimbo de data/hora em um dos formatos a seguir.

Para 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 carimbo de data/hora local

Em qualquer arquivo Avro que você pretende carregar, especifique um tipo lógico de carimbo de data/hora em um dos seguintes formatos.

Para 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	Observações
registro	RECORD	Aliases são ignorados Doc é convertido em uma descrição de campo. Os valores padrão são definidos no momento da leitura A ordem é ignorada Os campos recursivos são descartados. Somente o primeiro nível de aninhamento é mantido para campos recursivos.
enum	STRING	A string é o valor simbólico do enum. Aliases são ignorados Doc é convertido em uma descrição de campo.
matriz	campos repetidos	Arrays de arrays não são aceitos. As matrizes que contêm apenas os tipos NULL são ignoradas.
mapa<T>	RECORD	O BigQuery converte um campo map<T> do Avro em um RECORD repetido contendo dois campos: uma chave e um valor. O BigQuery armazena a chave como uma STRING e converte o valor no tipo de dados correspondente no BigQuery.
união	Campo anulável RECORD com uma lista de campos anuláveis	Quando a união só tem um tipo não nulo, ele é convertido em campo anulável. Caso contrário, ele é convertido em RECORD com uma lista de campos anuláveis. Apenas um desses campos será definido no momento da leitura.
fixo	BYTES	Aliases são ignorados O tamanho é ignorado

Limitações

• A formatação de matriz aninhada não é compatível com o BigQuery. Os arquivos Avro que usam esse formato precisam ser convertidos antes da importação.
• Em um arquivo Avro, nomes e namespaces de um nome completo podem conter apenas caracteres alfanuméricos e o caractere sublinhado _. A expressão regular a seguir mostra os caracteres permitidos: [A-Za-z_][A-Za-z0-9_]*

Para mais informações, consulte Limites de jobs de carregamento do BigQuery.