Como carregar dados particionados externamente

O BigQuery é compatível com o carregamento de dados particionados externamente em formatos Avro, Parquet, ORC, CSV e JSON, e armazenados no Cloud Storage usando um layout padrão de particionamento do Hive.

Limitações

  • A compatibilidade com o particionamento do Hive é baseada na atribuição a todos os URIs de um prefixo de URI de origem comum que termina imediatamente antes da codificação da partição, que tem este formato: gs://<bucket>/<path_to_table>/.
  • Na estrutura de diretório de uma tabela particionada do Hive, as mesmas chaves de particionamento aparecem na mesma ordem com até 10 chaves de partição por tabela.
  • Os dados precisam estar em conformidade com um layout padrão de particionamento do Hive.
  • Não é possível sobrepor as chaves de particionamento do Hive e as colunas nos arquivos subjacentes.
  • No momento, a compatibilidade está limitada ao Console do Cloud, à ferramenta de linha de comando bq e à API REST.
  • Todas as limitações de carregamento pelo Cloud Storage são aplicáveis.

Layouts de dados compatíveis

Os dados precisam estar em conformidade com um layout padrão de particionamento do Hive. O layout padrão está presente nos arquivos a seguir, por exemplo. Neles, os pares de chave-valor são definidos como diretórios em que o sinal = serve como separador, e as chaves de partição estão sempre na mesma ordem.

gs://bucket/table/dt=2019-10-31/lang=en/foo
gs://bucket/table/dt=2018-10-31/lang=fr/bar

O prefixo de URI de origem comum neste exemplo é gs://bucket/table.

Layouts de dados incompatíveis

Se os nomes das chaves de partição não forem codificados no caminho do diretório, a detecção do esquema de partição falhará. Observe o caminho a seguir, por exemplo, que não codifica os nomes da chave de partição:

gs://bucket/table/2019-10-31/en/foo

A detecção também falha nos arquivos em que o esquema não segue uma ordem consistente. Por exemplo, observe os dois arquivos a seguir com codificações de chaves de partição invertidas:

gs://bucket/table/dt=2019-10-31/lang=en/foo
gs://bucket/table/lang=fr/dt=2018-10-31/bar

Modos de detecção de esquemas de partição

As chaves de partição do Hive são exibidas como colunas normais ao carregar dados do Cloud Storage. Três modos de detecção de esquemas de partição do Hive são compatíveis:

  • AUTO: os nomes e tipos de chave são detectados automaticamente. É possível detectar estes tipos: STRING, INTEGER, DATE e TIMESTAMP.
  • STRINGS: os nomes de chaves são inferidos automaticamente com o tipo STRING.
  • CUSTOM: o esquema da chave de partição é codificado no prefixo do URI de origem.

Como fornecer um esquema de chave de partição CUSTOM

A detecção CUSTOM exige a codificação do esquema no campo do prefixo de URI de origem ao fornecer pares de nome/tipo de chave de partição. Os valores precisam ser analisados como o tipo especificado, caso contrário o carregamento falhará.

Por exemplo, definir "source_uri_prefix" como gs://my_bucket/my_table/{dt:DATE}/{val:STRING} trata val como STRING e dt como DATE, bem como extrair gs://my_bucket/my_table como o prefixo de URI de origem dos arquivos correspondentes.

Consulte as instruções detalhadas sobre o Console do Cloud, a ferramenta de linha de comando bq e a API REST.

Como executar cargas incrementais

Considere o layout de dados a seguir:

gs://my_bucket/my_table/dt=2019-10-31/val=1/file1
gs://my_bucket/my_table/dt=2018-10-31/val=2/file2
gs://my_bucket/my_table/dt=2017-10-31/val=3/file3
gs://my_bucket/my_table/dt=2016-10-31/val=4/file4

Para carregar apenas dados de 31-10-2019, faça o seguinte:

  • Defina o modo de particionamento do Hive como AUTO, STRINGS ou CUSTOM.
  • Defina o prefixo de URI de origem como gs://my_bucket/my_table/ para os modos AUTO ou STRINGS de particionamento do Hive. Para CUSTOM, forneça gs://my_bucket/my_table/{dt:DATE}/{val:INTEGER}.
  • Use o URI gs://my_bucket/my_table/dt=2019-10-31/*.
  • Os dados são carregados com as colunas dt e val incluídas, respectivamente com os valores 2019-10-31 e 1.

Para carregar dados somente de arquivos específicos, siga estas etapas:

  • Defina o modo de particionamento do Hive como AUTO, STRINGS ou CUSTOM.
  • Defina o prefixo de URI de origem como gs://my_bucket/my_table/ para os modos AUTO ou STRINGS de particionamento do Hive. Para CUSTOM, forneça gs://my_bucket/my_table/{dt:DATE}/{val:INTEGER}.
  • Use os URIs gs://my_bucket/my_table/dt=2017-10-31/val=3/file3,gs://my_bucket/my_table/dt=2016-10-31/val=4/file4.
  • Os dados são carregados dos dois arquivos com as colunas dt e val preenchidas.

Como definir HivePartitioningOptions usando o Console do Cloud

Para definir as opções de particionamento do Hive no Console do Cloud, siga estas etapas:

  1. Abra a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. No painel Recursos, selecione o conjunto de dados.

  3. Clique no botão Criar tabela para criar uma nova tabela.

  4. Selecione Cloud Storage na lista suspensa Criar tabela de.

    Opções de particionamento do Hive

  5. No campo Selecionar arquivo do bucket do Cloud Storage, insira o caminho do arquivo do conjunto de dados e, em seguida, selecione o tipo de arquivo na lista suspensa.

    1. Marque a caixa Particionamento de dados de origem e, então, insira o prefixo do URI de origem no campo fornecido.
    2. Em Modo de inferência da partição, escolha "Inferir tipos automaticamente" para AUTO ou "Todas as colunas são strings" para STRINGS.
    3. Selecione "Tabela nativa" na lista suspensa Tipo de tabela.

Como definir HivePartitioningOptions usando a ferramenta de linha de comando bq

Como solicitar a detecção automática de tipo de chave de particionamento

bq load --source_format=ORC --hive_partitioning_mode=AUTO \
--hive_partitioning_source_uri_prefix=gcs_uri_shared_prefix \
dataset.table gcs_uris

Para solicitar a detecção da chave de partição tipo STRING:

bq load --source_format=PARQUET --autodetect \
--hive_partitioning_mode=STRINGS \
--hive_partitioning_source_uri_prefix=gcs_uri_shared_prefix \
dataset.table gcs_uris

Para fornecer um esquema personalizado de chave de partição codificado via campo "source_uri_prefix":

bq load --source_format=JSON --hive_partitioning_mode=CUSTOM \
--hive_partitioning_source_uri_prefix=gcs_uri_shared_prefix/custom_schema_encoding \
dataset.table gcs_uris file_schema

O esquema da chave de partição é codificado imediatamente após o prefixo de URI de origem. Use o seguinte formato para especificar --hive_partitioning_source_uri_prefix:

--hive_partitioning_source_uri_prefix=gcs_uri_shared_prefix/{key1:TYPE1}/{key2:TYPE2}/{key3:TYPE3}

Como definir HivePartitioningOptions usando a API REST

A compatibilidade do particionamento do Hive é possível ao definir HivePartitioningOptions no JobConfigurationLoad.

Observe que, quando hivePartitioningOptions.mode estiver definido como CUSTOM, será necessário configurar hivePartitioningOptions.sourceUriPrefix como gs://bucket/path_to_table/{key1:TYPE1}/{key2:TYPE2}/{key3:TYPE3} para codificar o esquema da chave de partição dentro do sourceUriPrefix.