Como carregar dados Avro a partir do Cloud Storage

Como carregar arquivos 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 intervalo do Cloud Storage.

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

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

Esse comando carrega todos os arquivos em um único comando da CLI, como uma lista separada por vírgulas, e o esquema é derivado de mybucket/01/b.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 BigQuery SQL. Para saber mais informações, consulte as conversões Avro.

Compactação Avro

Arquivos Avro compactados não são compatíveis, mas blocos de dados compactados são. O BigQuery aceita os codecs DEFLATE e Snappy.

Permissões exigidas

Ao carregar dados no BigQuery, você precisa de permissões para executar o job correspondente e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também serão necessárias permissões para acessar o intervalo que contém os dados.

Permissões do BigQuery

Pelo menos as permissões a seguir são obrigatórias para carregar dados no BigQuery. Elas serão necessárias se você estiver anexando ou substituindo uma tabela ou partição ou carregando dados nelas.

bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create

Os papéis predefinidos do Cloud IAM a seguir incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

bigquery.user
bigquery.jobUser
bigquery.admin

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, ele recebe o acesso de bigquery.dataOwner ao conjunto. Com bigquery.dataOwner, o usuário tem a capacidade de criar e atualizar tabelas no conjunto de dados por meio de um job de carregamento.

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

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, é necessário ter as permissões de storage.objects.get. Se você estiver usando um caractere curinga de URI, também precisará ter as permissões de storage.objects.list.

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

Como carregar dados Avro em uma nova tabela

Para carregar dados Avro em uma nova tabela:

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

Para carregar os dados Avro do Cloud Storage em uma nova tabela do BigQuery:

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar o Console do GCP
Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
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 GCP, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.
- Em Formato de arquivo, selecione Avro.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto 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.
Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.
Opcional: para particionar a tabela, escolha as opções em Configurações de particionamento e cluster:
- Para criar uma tabela particionada, clique em Sem particionamento, selecione Particionar por campo e escolha uma coluna DATE ou TIMESTAMP. Essa opção estará indisponível se o esquema não incluir uma coluna DATE ou TIMESTAMP.
- Para criar uma tabela particionada por tempo de ingestão, clique em Sem particionamento e selecione Partição por tempo de ingestão.
Opcional: em Filtro de particionamento, clique na caixa Exigir filtro de particionamento para solicitar que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição reduz os custos e melhora o desempenho. Para mais informações, consulte Como consultar tabelas particionadas. Essa opção estará indisponível se Sem particionamento estiver selecionado.
Opcional: para agrupar a tabela, na caixa Ordem de clustering, insira até quatro nomes de campo. Atualmente, o clustering é compatível apenas com tabelas particionadas.
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 Quantidade de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas que contêm erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará.
- Em Valores desconhecidos, desmarque Ignorar valores desconhecidos. Essa opção se aplica somente a arquivos CSV e JSON.
- Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Clique em Criar tabela.

IU clássica

Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQuery
No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo e selecione Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.
Na página Criar tabela, na seção Dados de origem:
- Clique em Criar da origem.
- Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você está criando.
- Em Formato de arquivo, selecione Avro.
Na seção Tabela de destino:
- Em Nome da tabela, escolha o conjunto de dados apropriado. No campo do nome da tabela, insira um nome para a tabela que você está criando no BigQuery.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.
Opcional: na seção Opções:
- Em Quantidade de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas que contêm erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará.
- Em 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.
- Para particionar a tabela:
  - Em Tipo de particionamento, clique em Nenhum e escolha Dia.
  - No Campo de particionamento:
  - Para criar uma tabela particionada, escolha uma coluna DATE ou TIMESTAMP. Essa opção estará indisponível se o esquema não incluir uma coluna DATE ou TIMESTAMP.
  - Para criar uma tabela particionada por tempo de ingestão, use o valor padrão: _PARTITIONTIME.
  - Clique na caixa 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 Como consultar tabelas particionadas. Essa opção estará indisponível se Tipo de particionamento estiver definido como Nenhum.
- Para agrupar a tabela, na caixa Campos de clustering, insira até quatro nomes de campo.
- Em Criptografia de destino, clique em Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração Default, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
Clique em Criar tabela.

CLI

Use o comando bq load, especifique AVRO com a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separada por vírgulas ou um URI que contenha um caractere curinga.

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

Estas são outras sinalizações opcionais:

--max_bad_records: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
--time_partitioning_type: ativa o particionamento baseado em tempo em uma tabela e define o tipo de partição. Atualmente, o único valor possível é DAY, que gera uma partição por dia. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE ou TIMESTAMP.
--time_partitioning_expiration: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.
--time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se o particionamento baseado em tempo estiver ativado sem esse valor, uma tabela particionada por tempo de ingestão será criada.
--require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que 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 Como consultar tabelas particionadas.
--clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster. Só é possível usar essa sinalização com tabelas particionadas.
--destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

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

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

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

Em que:

location é o local. A sinalização --location é opcional. Por exemplo, se você estiver usando o 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 os dados serão carregados;
path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis.

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 ingestão 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 chamada 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

Crie um job load que aponte para os dados de origem no Cloud Storage.
Opcional: especifique o local na propriedade location na seção jobReference do recurso de job.
A propriedade source URIs precisa ser totalmente qualificada, no formato gs://bucket/object. Cada URI pode conter um caractere curinga "*".
Especifique o formato de dados Avro definindo a propriedade sourceFormat como AVRO.
Para verificar o status do job, chame jobs.get(job_id*), em que job_id é o ID do job retornado pela solicitação inicial.
- O resultado status.state = DONE mostra que o job foi concluído com sucesso.
- 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.
- Se status.errorResult não for exibido, o job terá sido concluído com sucesso, mas é 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 o transmita 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 de job é idempotente. É possível tentar novamente quantas vezes quiser com o mesmo ID e, no máximo, uma das operações será bem-sucedida.

Python

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

Ver no GitHub Feedback

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

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

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Como anexar ou substituir uma tabela com dados Avro

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

No Console ou na IU da Web clássica do BigQuery, use a opção Gravar preferência para especificar a ação a ser executada ao carregar dados de um arquivo de origem ou de um resultado de consulta.

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

Opção do console	Opção da IU da Web clássica	Sinalização da CLI	Propriedade da API BigQuery	Descrição
Gravar apenas se a tabela estiver vazia	Gravar apenas se a tabela estiver vazia	Nenhuma	`WRITE_EMPTY`	Grava dados apenas se a tabela estiver vazia.
Anexar à tabela	Anexar à tabela	`--noreplace` ou `--replace=false`. Se `--[no]replace` não estiver especificado, o padrão será anexar	`WRITE_APPEND`	Padrão: anexa os dados ao final da tabela.
Substituir tabela	Substituir tabela	`--replace` ou `--replace=true`	`WRITE_TRUNCATE`	Apaga todos os dados em uma tabela antes de gravar os novos.

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

Para anexar ou substituir uma tabela:

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

Para anexar ou substituir uma tabela com dados Avro:

Console

Abra a IU da Web do BigQuery no Console do GCP.
Acessar o Console do GCP
Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.
No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.
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 na IU da Web do BigQuery, mas há compatibilidade com caracteres curinga. O intervalo 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.
Na página Criar tabela, na seção Destino:
- Em Nome do conjunto de dados, escolha o conjunto apropriado.
- No campo Nome da tabela, insira o nome da tabela que você está anexando ou substituindo no BigQuery.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. O esquema é 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.
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 GCP não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
Clique em Opções avançadas.
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Em Quantidade de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas que contêm erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará.
- Em Valores desconhecidos, desmarque Ignorar valores desconhecidos. Essa opção se aplica somente a arquivos CSV e JSON.
- Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
Clique em Criar tabela.

IU clássica

Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQuery
No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo e selecione Criar nova tabela. O processo para anexar e substituir dados em um job de carregamento é igual ao de criação de uma tabela.
Na página Criar tabela, na seção Dados de origem:
- Em Local, selecione Cloud Storage e, no campo de origem, insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU, mas há compatibilidade com caracteres curinga. O intervalo 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.
Na página Criar tabela, na seção Tabela de destino:
- Em Nome da tabela, escolha o conjunto de dados apropriado e, no campo de nome, insira o nome da tabela que você está anexando ou substituindo.
- Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, nenhuma ação é necessária. As informações de esquema são autoexplicadas 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.
Na seção Opções:
- Em Quantidade de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas que contêm erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará.
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Use os valores padrão de Tipo de particionamento, Campo de particionamento, Exigir filtro de partição e Campos de clustering. Não é possível anexar ou substituir uma tabela para convertê-la em uma tabela particionada ou em cluster. Além disso, a IU da Web não é compatível com a anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
- Em Criptografia de destino, clique em Criptografia gerenciada pelo cliente para usar uma chave do Cloud Key Management Service para criptografar a tabela. Se você optar pela configuração Default, o BigQuery criptografará os dados em repouso usando uma chave gerenciada pelo Google.
Clique em Criar tabela.

CLI

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

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

Estas são outras sinalizações opcionais:

--max_bad_records: um número inteiro que especifica a quantidade máxima de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
--destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

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

Em que:

location é o local. A sinalização --location é opcional. Defina 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 os dados serão carregados;
path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis.

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 os anexa 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 CLI, consulte Como anexar e substituir dados de tabelas particionadas.

API

Crie um job load que aponte para os dados de origem no Cloud Storage.
Opcional: especifique o local na propriedade location na seção jobReference do recurso de job.
A propriedade source URIs precisa ser totalmente qualificada, no formato gs://bucket/object. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são compatíveis.
Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como AVRO.
Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

Python

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

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

Conversões Avro

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

Tipos primitivos

Tipo de dados Avro	Tipo de dados do BigQuery	Notas
nulo	O BigQuery ignora esses valores
booleano	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
bytes com um tipo lógico `decimal`	NUMERIC
string	STRING	somente UTF-8

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	Matrizes de matrizes não são aceitas. 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.
union	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.

Tipos lógicos

Por padrão, o BigQuery ignora o atributo logicalType e usa o tipo Avro subjacente.

Tipo lógico Avro	Tipo de dados do BigQuery
date	INTEGER
time-millis	INTEGER
time-micros	Número inteiro (convertido de LONG)
timestamp-millis	Número inteiro (convertido de LONG)
timestamp-micros	Número inteiro (convertido de LONG)
duration	BYTES (convertido do tipo `fixed` de tamanho 12)
decimal	NUMERIC (consulte Tipo lógico decimal)

Para ativar a conversão de tipos lógicos 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 ou configure a propriedade useAvroLogicalTypes no recurso do job quando 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 convertidos
date	DATE
time-millis	TIME
time-micros	TIME
timestamp-millis	TIMESTAMP
timestamp-micros	TIMESTAMP
duration	BYTES (convertido do tipo fixo de tamanho 12)
decimal	NUMERIC (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).

Tipo lógico decimal

Um tipo bytes Avro com um tipo lógico decimal pode ter, no máximo, precision de 38 (número total de dígitos) e, no máximo, uma scale de 9 (dígitos à direita do decimal). O número de dígitos de inteiro, a precision menos a scale, pode ter, no máximo, 29. Por exemplo, um decimal com uma precision de 38 e uma scale de 9 são compatíveis porque o número de dígitos de inteiro é 29. Um decimal com uma precision de 38 e uma scale de 5 não é compatível porque o número de dígitos de inteiro é 33.

Quando você carrega um arquivo Avro que contém uma coluna bytes com o tipo lógico decimal em uma tabela atual, o tipo de dados da coluna na definição do esquema da tabela pode ser BYTES ou NUMERIC. Se o tipo de dados da coluna for BYTES, o tipo lógico decimal na coluna no arquivo Avro será ignorado.

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

Como carregar arquivos Avro do Cloud Storage

Vantagens do Avro

Esquemas Avro

Compactação Avro

Permissões exigidas

Permissões do BigQuery

Permissões do Cloud Storage

Como carregar dados Avro em uma nova tabela

Console

IU clássica

CLI

API

Python

Como anexar ou substituir uma tabela com dados Avro

Console

IU clássica

CLI

API

Python

Conversões Avro

Tipos primitivos

Tipos complexos

Tipos lógicos

Tipo lógico decimal

Enviar comentários sobre…