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

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar o Console do GCP

  2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

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

    Criar tabela

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

      Selecionar arquivo

    • Em Formato de arquivo, selecione Avro.

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

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

      Ver conjunto de dados

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

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

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

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

  10. 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.
  11. Clique em Criar tabela.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do í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.

  3. 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.
  4. 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.
  5. Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.

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

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

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

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

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

  2. Opcional: especifique o local na propriedade location na seção jobReference do recurso de 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.

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

# 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

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar o Console do GCP

  2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

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

    Criar tabela

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

      Selecionar arquivo

    • Em Formato de arquivo, selecione Avro.

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

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

      Escolher conjunto de dados

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

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

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

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

      Substituir tabela

  9. Clique em Criar tabela.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, passe o cursor sobre um conjunto de dados, clique no ícone de seta para baixo imagem do í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.

  3. 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.
  4. 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.
  5. Na seção Esquema, nenhuma ação é necessária. As informações de esquema são autoexplicadas nos arquivos Avro.

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

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

  2. Opcional: especifique o local na propriedade location na seção jobReference do recurso de 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.

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.

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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.