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

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

Permissões necessárias

Ao carregar dados no BigQuery, você precisa de permissões para os envolvidos no projeto ou no nível do conjunto de dados para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará acessar o intervalo que contém os dados.

Permissões do BigQuery

Ao carregar dados no BigQuery a partir do Cloud Storage, você precisa ter os papéis bigquery.dataOwner ou bigquery.dataEditor para envolvidos no projeto ou no nível do conjunto de dados. Os dois papéis concedem aos usuários e grupos permissão para carregar dados em uma nova tabela, anexá-los a uma tabela ou substitui-la.

Com os papéis para envolvidos no projeto, os usuários ou grupos têm permissão para carregar dados em tabelas em cada conjunto de dados no projeto. Já com os papéis no nível do conjunto de dados, os usuários ou grupos podem carregar dados apenas em tabelas desse conjunto de dados.

Para mais informações sobre como configurar o acesso aos conjuntos de dados, consulte Como controlar o acesso a conjuntos de dados. Para saber mais sobre papéis do IAM no BigQuery, consulte Controle de acesso.

Permissões do Cloud Storage

Para carregar dados de um intervalo do Cloud Storage, você precisa de permissões storage.objects.get no nível do projeto ou do intervalo individual. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list.

O papel do IAM predefinido storage.objectViewer pode ser concedido para fornecer permissões storage.objects.get e storage.objects.list.

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 --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "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.

Como carregar dados Avro em uma nova tabela

Para carregar dados Avro do Cloud Storage em uma nova tabela do BigQuery ou anexar dados a uma tabela atual:

Console

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

  2. No painel de navegação, na seção Recursos, expanda seu 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. Siga estas etapas na página Criar tabela, na seção Origem:

    • Em Criar tabela de, selecione o tipo de fonte desejada.

      Criar fonte de tabela

    • No campo de origem, procure o arquivo/intervalo do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas caracteres curinga são aceitos. 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.

      Escolher conjunto de dados

    • No campo Nome da tabela, insira o nome da tabela que você está criando 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 é inferido dos arquivos Avro.

  7. 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 depois em 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:

    • 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 caracteres curinga são aceitos. 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 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 da tabela, insira um nome para a tabela que você está criando no BigQuery.
    • Verifique se o Tipo de tabela está configurado como Tabela nativa.

  5. Na seção Esquema, nenhuma ação é necessária. O esquema é inferido dos arquivos Avro.

  6. Clique em Criar tabela.

Linha de comando

Use o comando bq load, especifique AVRO como 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 contendo um caractere curinga.

Forneça a sinalização --location e defina o valor do local.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

em que:

  • [LOCATION] é o local. A sinalização --location será opcional se os seus dados estiverem nos locais multirregionais US ou EU. 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 existente;
  • [TABLE] é o nome da tabela em que você está carregando dados;
  • [PATH_TO_SOURCE] é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Caracteres curinga também são aceitos.

Exemplos:

  • O comando a seguir carrega dados de gs://mybucket/mydata.avro para uma tabela chamada mytable no mydataset. mybucket e mydataset foram criados na multirregião US.

    bq --location=US 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 no mydataset. O URI do Cloud Storage usa um caractere curinga: mybucket e mydataset foram criados na multirregião US.

    bq --location=US 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 no mydataset. O comando inclui uma lista separada por vírgula de URIs do Cloud Storage com caracteres curingas. mybucket e mydataset foram criados na região asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

Defina as propriedades a seguir para carregar os dados Avro usando a API.

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

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

  3. Os URIs de origem precisam ser totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. Cada URI pode conter um caractere curinga "*".

  4. Especifique o formato de dados Avro. Para isso, defina a propriedade configuration.load.sourceFormat como AVRO.

  5. Para verificar o status do job, chame jobs.get([JOB_ID]*), em que [JOB_ID] é o código do job retornado pela solicitação inicial.

    • O resultado status.state = DONE mostra que o job foi concluído com sucesso.
    • A presença da 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 não são adicionados dados.
    • Se status.errorResult estiver ausente, o job foi concluído com sucesso, embora possa haver 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 de 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, e se um deles for bem-sucedido, todos os dados estarão disponíveis.

  • Como prática recomendada, gere um código exclusivo e o transmita como jobReference.jobId ao chamar jobs.insert() para a criação de um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o código do job conhecido.

  • A chamada jobs.insert() com um determinado código de job é idempotente, ou seja, é possível repeti-la quantas vezes quiser com o mesmo código 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 no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para 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 substituir uma tabela por dados Avro

Carregue dados extras 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 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 Nenhum 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.

Por padrão, os jobs de carregamento anexam dados a uma tabela. Para substituir os dados da tabela usando um job de carregamento:

Console

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

  2. No painel de navegação, na seção Recursos, expanda seu 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.

  4. Na página Criar tabela, na seção Origem:

    • Em Criar uma tabela a partir de, selecione o tipo de fonte desejado e, no campo de origem, procure o arquivo/intervalo do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs na IU da Web do BigQuery, mas caracteres curinga são aceitos. 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.

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

    • Em Nome do conjunto de dados, escolha o conjunto de dados apropriado e, no campo Nome da tabela, insira o nome da tabela que você está criando 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 é inferido dos arquivos Avro.

  7. Na seção Opções avançadas, em Preferência de gravação, escolha Gravar se vazio, Anexar à tabela ou Substituir tabela.

  8. 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 depois em 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:

    • 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 caracteres curinga são aceitos. 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 insira o nome da tabela que você está anexando ou substituindo.
    • Verifique se o Tipo de tabela está configurado como Tabela nativa.

  5. Na seção Esquema, nenhuma ação é necessária. As informações do esquema são inferidas dos arquivos Avro.

  6. Na seção Opções, em Preferência de gravação, escolha Gravar se estiver vazia, Anexar à tabela ou Substituir tabela.

    Adicionar esquema usando campos de adição

  7. Clique em Criar tabela.

Linha de comando

Insira o comando bq load com a sinalização --replace para substituir a tabela. Forneça a sinalização --location e defina o valor do local. Use a sinalização --noreplace para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados.

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

em que:

  • [LOCATION] é o local. A sinalização --location será opcional se os seus dados estiverem nos locais multirregionais US ou EU.É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [DATASET] é um conjunto de dados atual;
  • [TABLE] é o nome da tabela em que você está carregando dados;
  • [PATH_TO_SOURCE] é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados 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. mybucket e mydataset foram criados na multirregião US.

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

  • O comando a seguir carrega dados de gs://mybucket/mydata.avro e acrescenta dados a uma tabela chamada mytable em mydataset. mybucket e mydataset foram criados na região asia-northeast1.

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

API

Defina as seguintes propriedades para carregar dados CSV usando a API.

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

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

  3. Os URIs de origem precisam ser totalmente qualificados no formato gs://[BUCKET]/[OBJECT]. É possível incluir vários URIs como uma lista separada por vírgulas. Caracteres curinga também são aceitos no carregamento de dados CSV do Cloud Storage.

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

  5. Defina a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE, WRITE_APPEND ou WRITE_EMPTY para especificar a preferência de gravação.

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para 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. Arrays contendo apenas os tipos NULL são ignorados.
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 nos tipos de dados correspondentes do BigQuery deles, defina a sinalização --use_avro_logical_types como True usando a ferramenta de linha de comando ou defina a propriedade useAvroLogicalTypes no recurso de job ao chamar o método jobs.insert para criar um job de carga.

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 saber mais informações sobre os tipos de dados Avro, consulte a Especificação do Apache Avro™ 1.8.2.

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 contendo uma coluna bytes com o tipo lógico decimal em uma tabela existente, 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.

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

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.