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 atual, ou substituir uma tabela ou partição. 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 no mesmo local regional ou multirregional 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.
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
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 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
O BigQuery é compatível com os seguintes codecs de compactação para blocos de dados em arquivos Parquet:
Snappy
DEFLATE
Permissões necessárias
Ao carregar dados no BigQuery, você precisa de permissões para executar um job de carregamento e para carregar dados em tabelas e partições novas ou antigas do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de 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 carregando dados em uma nova tabela ou partição ou anexando/substituindo uma tabela ou partição.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Os seguintes papéis predefinidos do IAM incluem
as permissões bigquery.tables.create
e bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Além disso, quando um usuário tem permissões bigquery.datasets.create
e
cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner
ao conjunto.
O acesso bigquery.dataOwner
permite que o usuário crie e
atualize tabelas no conjunto de dados usando um job de carregamento.
Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.
Permissões do Cloud Storage
Para carregar dados de um bucket do Cloud Storage, você precisa ter
permissões storage.objects.get
. Se você estiver usando um caractere curinga de URI, também precisará ter permissões storage.objects.list
.
O papel predefinido storage.objectViewer
do IAM concede as permissões storage.objects.get
e
storage.objects.list
.
Como carregar dados Avro em uma nova tabela
É possível carregar dados Avro em uma nova tabela das seguintes maneiras:
- usando o Console do Cloud;
- usando o comando
bq load
na ferramenta de linha de comandobq
; - chamando o método da API
jobs.insert
e configurando um jobload
; - usando bibliotecas de cliente.
Para carregar os dados Avro do Cloud Storage em uma nova tabela do BigQuery:
Console
Abra a página do BigQuery no Console do Cloud.
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 seção Origem da página Criar tabela, faça o seguinte:
Em Criar tabela de, selecione 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.
Na página Criar tabela, na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
Verifique se 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 Partição por campo e escolha uma coluna
DATE
ouTIMESTAMP
. Essa opção ficará indisponível se o esquema não incluir uma colunaDATE
ouTIMESTAMP
. - Para criar uma tabela particionada por tempo de ingestão, clique em Sem particionamento e selecione Partição por tempo de ingestão.
- Para criar uma tabela particionada, clique em Sem particionamento, selecione Partição por campo e escolha uma coluna
(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 pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas. Essa opção ficará indisponível se a opção Sem particionamento estiver selecionada.Opcional: para inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering.
Opcional: clique em Opções avançadas.
- Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
- Em Número de erros permitidos, aceite o valor padrão
0
ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensageminvalid
e falhará. - 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.
Clique em Criar tabela.
bq
Use o comando bq load
, especifique AVRO
usando a sinalização
--source_format
e inclua um URI do Cloud Storage.
É possível incluir apenas um 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 como seu 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. 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 colunaDATE
ouTIMESTAMP
.--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 colunaDATE
ouTIMESTAMP
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áusulaWHERE
que especifica as partições a serem consultadas. A exigência de um filtro de particionamento pode reduzir os custos e melhorar o desempenho. Para mais informações, veja 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.--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 processamento
Para mais informações sobre tabelas em cluster, consulte:
Para mais informações sobre 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
Substitua:
- location é seu 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 comoasia-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 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
da seçãojobReference
do recurso do job.A propriedade
source URIs
precisa ser totalmente qualificada no formatogs://bucket/object
. Cada URI pode conter um caractere curinga "*".Especifique o formato de dados Avro definindo a propriedade
sourceFormat
comoAVRO
.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 propriedadestatus.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 chamarjobs.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.
Java
Node.js
Antes de testar essa amostra, siga as instruções de configuração para 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 (em inglês).
Python
Antes de testar essa amostra, siga as instruções de configuração para 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.
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 Cloud, use a opção Preferência de gravação para especificar qual ação será realizada 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 | Sinalização da ferramenta bq |
Propriedade da API BigQuery | Descrição |
---|---|---|---|
Gravar apenas se a tabela estiver vazia | Nenhuma | 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 remove qualquer chave do Cloud KMS. |
Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.
É possível anexar ou substituir uma tabela das seguintes maneiras:
- usando o Console do Cloud;
- usando o comando
bq load
na ferramenta de linha de comandobq
; - chamando o método da API
jobs.insert
e configurando um jobload
; - usando bibliotecas de cliente.
Para anexar ou substituir uma tabela com dados Avro:
Console
Abra a página do BigQuery no Console do Cloud.
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 seção Origem da página Criar tabela, faça o seguinte:
Em Criar tabela de, selecione 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 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 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.
Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.
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.
Clique em Opções avançadas.
- Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
- Em Número de erros permitidos, aceite o valor padrão
0
ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensageminvalid
e falhará. - 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.
Clique em Criar tabela.
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.
Opcional: forneça a sinalização --location
e defina o valor como seu 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 é seu 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
Crie um job
load
que aponte para os dados de origem no Cloud Storage.(Opcional) Especifique o local na propriedade
location
da seçãojobReference
do recurso do job.A propriedade
source URIs
precisa ser totalmente qualificada no formatogs://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
comoAVRO
.Especifique a preferência de gravação definindo a propriedade
configuration.load.writeDisposition
comoWRITE_TRUNCATE
ouWRITE_APPEND
.
Java
Node.js
Antes de testar essa amostra, siga as instruções de configuração para 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 (em inglês).
Python
Antes de testar essa amostra, siga as instruções de configuração para 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.
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 preencherá as colunas particionadas do hive como colunas na tabela de destino gerenciada pelo 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 do BigQuery | Notas | |
---|---|---|
nulo | O BigQuery ignora esses valores | |
booleano | BOOLEAN | |
int | INTEGER | |
long | INTEGER | |
float | FLOAT | |
double | FLOAT | |
bytes | BYTES | |
bytes com um decimal tipo lógico |
NUMERIC | |
string | STRING | somente UTF-8 |
Tipos complexos
Tipo de dados do BigQuery | Observações | |
---|---|---|
registro | RECORD |
|
enum | STRING |
|
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. |
union |
|
|
fixo | BYTES |
|
Tipos lógicos
Por padrão, o BigQuery ignora o atributo logicalType
e usa o tipo Avro subjacente.
Tipo de dados do BigQuery | |
---|---|
date | INTEGER |
time-millis | INTEGER |
time-micros | INTEGER (convertido de LONG) |
timestamp-millis | INTEGER (convertido de LONG) |
timestamp-micros | INTEGER (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 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 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 Avro bytes
com um tipo lógico decimal
pode ter no máximo um precision
de 38 (número total de dígitos) e no máximo um scale
de 9 (dígitos à direita do decimal). O número total de dígitos de inteiro, que é precision
menos scale
, pode ser no máximo 29. Por exemplo, um decimal
com um precision
de 38, e um scale
de 9 é compatível porque o número de dígitos de inteiro é 29. Um decimal
com um precision
de 38 e um 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.