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 um job de carga 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 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, recebe o acesso bigquery.dataOwner
a ele.
Com o acesso bigquery.dataOwner
, o usuário consegue criar e atualizar tabelas no conjunto de dados por meio de um job de carga.
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 permissões storage.objects.get
. Se você estiver usando um caractere curinga de URI, também precisará ter permissões 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;
- Com o uso do comando
bq load
da CLI. - Chamando o método de API
jobs.insert
e configurando um jobload
. - 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 GCPNa 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.
Siga estas etapas na página Criar tabela, 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
ouTIMESTAMP
. Essa opção estará 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 Particionar 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 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 inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Ordem de clustering. 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 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 refere-se 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.
IU clássica
Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQueryNo 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 Table type está definido como Native table.
Na seção Esquema, nenhuma ação é necessária. O esquema é autoexplicado nos arquivos Avro.
Opcional: na seção Opções:
- 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 Preferência de gravação, mantenha selecionada a opção 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
ouTIMESTAMP
. Essa opção estará indisponível se o esquema não incluir uma colunaDATE
ouTIMESTAMP
. - Para criar uma tabela particionada por tempo de ingestão, use o valor padrão:
_PARTITIONTIME
. - Clique na caixa Exigir filtro de partição 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 inserir a tabela em um cluster, insira até quatro nomes de campo na caixa Campos em cluster.
- Em Criptografia de destino, escolha 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.
- Em Número de erros permitidos, aceite o valor padrão
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 do 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 que o job inteiro falhe. 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 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 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:
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 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 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 denominada 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 denominada 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çãojobReference
do recurso de 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.- 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 propriedadestatus.errors
do objeto do job retornado.
- O resultado
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 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 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 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 Python.
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 de 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.
É possível anexar ou substituir uma tabela destas maneiras:
- Com o uso do Console do GCP ou da IU da Web clássica.
- Use o comando
bq load
da CLI. - Chame o método de API
jobs.insert
e configure um jobload
. - 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 GCPNa 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 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 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 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 refere-se 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.
IU clássica
Acesse a IU da Web do BigQuery.
Acessar a IU da Web do BigQueryNo 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 Table type está definido como Native table.
Na seção Esquema, nenhuma ação é necessária. As informações de esquema são autoexplicadas nos arquivos Avro.
Na seção Opções:
- 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 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, escolha 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.
- Em Número de erros permitidos, aceite o valor padrão
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 do 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 que o job inteiro falhe. 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çãojobReference
do recurso de 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
.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Python.
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 tipo lógico decimal
|
NUMERIC | |
string | STRING | somente UTF-8 |
Tipos complexos
Tipo de dados do BigQuery | Observações | |
---|---|---|
registro | RECORD |
|
enum | STRING |
|
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 |
|
|
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 | 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 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 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).