Consultar formatos de tabela aberta com manifestos

Neste documento, descrevemos como usar arquivos de manifesto para consultar dados armazenados em formatos de tabela aberta, como Apache Hudi e Delta Lake.

Alguns formatos de tabela abertos, como Hudi e Delta Lake, exportam o estado atual como um ou mais arquivos de manifesto. Um arquivo de manifesto contém uma lista de arquivos de dados que fazem tabelas. Com o suporte a manifestos no BigQuery, é possível consultar e carregar dados armazenados em formatos de tabela aberta.

Antes de começar

Funções exigidas

Para consultar as tabelas do BigLake com base nos dados do Hudi e Delta Lake, verifique se você tem os seguintes papéis:

  • Usuário de conexão do BigQuery (roles/bigquery.connectionUser)
  • Leitor de dados do BigQuery (roles/bigquery.dataViewer)
  • Usuário do BigQuery (roles/bigquery.user)

Também é possível consultar tabelas externas do Hudi. No entanto, recomendamos que você faça upgrade da tabela externa para o BigLake. Para consultar tabelas externas do Hudi, verifique se você tem os seguintes papéis:

  • Leitor de dados do BigQuery (roles/bigquery.dataViewer)
  • Usuário do BigQuery (roles/bigquery.user)
  • Leitor de objetos do Storage (roles/storage.objectViewer)

Dependendo das suas permissões, é possível conceder esses papéis a você mesmo ou pedir ao administrador para concedê-los. Para mais informações sobre como conceder papéis, consulte Como visualizar os papéis atribuíveis em recursos.

Para conferir as permissões exatas que são necessárias para consultar as tabelas do BigLake, expanda a seção Permissões necessárias:

Permissões necessárias

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Consultar cargas de trabalho do Hudi

Para consultar dados do Hudi, siga estas etapas:

  1. Crie uma tabela externa com base nos dados do Hud.
  2. Faça upgrade da tabela externa para o BigLake.

Criar tabelas externas do Hudi

Ao sincronizar tabelas usando a ferramenta de sincronização para Hudi e BigQuery, ative a flag use-bq-manifest-file para fazer a transição para a abordagem de arquivo de manifesto. Essa flag também exporta um arquivo de manifesto em um formato compatível com o BigQuery e o utiliza para criar uma tabela externa com o nome especificado no parâmetro --table.

Para criar uma tabela externa do Hudi, siga estas etapas:

  1. Para criar uma tabela externa do Hudi, envie um job para um cluster do Dataproc. Ao criar o conector Hud-BigQuery, ative a flag use-bq-manifest-file para fazer a transição para a abordagem do arquivo de manifesto. Essa flag exporta um arquivo de manifesto em um formato compatível com o BigQuery e o utiliza para criar uma tabela externa com o nome especificado no parâmetro --table.

    spark-submit \
   --master yarn \
   --packages com.google.cloud:google-cloud-bigquery:2.10.4 \
   --class org.apache.hudi.gcp.bigquery.BigQuerySyncTool  \
   JAR \
   --project-id PROJECT_ID \
   --dataset-name DATASET \
   --dataset-location LOCATION \
   --table TABLE \
   --source-uri URI  \
   --source-uri-prefix URI_PREFIX \
   --base-path BASE_PATH  \
   --partitioned-by PARTITION_BY \
   --use-bq-manifest-file

    Substitua:

    • JAR: se você estiver usando o conector Hudi-BigQuery, especifique hudi-gcp-bundle-0.14.0.jar. Se você estiver usando o componente Hudi no Dataproc 2.1, especifique /usr/lib/hudi/tools/bq-sync-tool/hudi-gcp-bundle-0.12.3.1.jar.

    • PROJECT_ID: o ID do projeto em que você quer criar a tabela do Hudi BigLake.

    • DATASET: o conjunto de dados em que você quer criar a tabela do Hudi BigLake.

    • LOCATION: o local em que você quer criar a tabela do Hudi BigLake.

    • TABLE: o nome da tabela que você quer criar.

      Se você estiver fazendo a transição da versão anterior do conector Hud-BigQuery (0.13.0 e anteriores) que criava visualizações nos arquivos de manifesto, use o mesmo nome de tabela, porque ele permite manter o código do pipeline downstream atual.

    • URI: o URI do Cloud Storage que você criou para armazenar o arquivo de manifesto do Hudi.

      Esse URI aponta para a partição de primeiro nível. inclua a chave de partição. Por exemplo, gs://mybucket/hudi/mydataset/EventDate=*.

    • URI_PREFIX: o prefixo do caminho do URI do Cloud Storage, geralmente o caminho para as tabelas do Hudi.

    • BASE_PATH: o caminho base das tabelas do Hudi.

      Por exemplo, gs://mybucket/hudi/mydataset/.

    • PARTITION_BY: o valor da partição.

      Por exemplo, EventDate.

    Para mais informações sobre a configuração do conector, consulte Conector Hud-BigQuery.

  2. Para definir controles refinados adequados ou acelerar o desempenho ativando o armazenamento em cache de metadados, consulte Atualizar tabelas do BigLake

Consultar cargas de trabalho Delta

As tabelas delta agora têm suporte nativo. Recomendamos a criação de tabelas Delta BigLake para cargas de trabalho Delta. As tabelas do Delta Lake BigLake são compatíveis com tabelas Delta Lake mais avançadas, incluindo tabelas com remapeamento de colunas e vetores de exclusão. Além disso, as tabelas do Delta BigLake leem diretamente o snapshot mais recente e as atualizações ficam disponíveis instantaneamente.

Para consultar cargas de trabalho Delta, siga estas etapas:

  1. Gere um arquivo de manifesto.
  2. Crie uma tabela do BigLake com base no arquivo de manifesto.
  3. Defina os controles refinados adequados ou acelere o desempenho ativando o armazenamento em cache de metadados. Para fazer isso, consulte Fazer upgrade de tabelas do BigLake.

Gerar um arquivo de manifesto

O BigQuery oferece suporte ao arquivo de manifesto em um formato SymLinkTextInputFormat, que é uma lista de URIs delimitadas por nova linha. Para mais informações sobre como gerar um arquivo de manifesto, consulte Configurar a integração do Presto para Delta Lake e consultar tabelas Delta.

Para gerar um arquivo de manifesto, envie um job para um cluster do Dataproc:

SQL

Usando o Spark, execute o comando a seguir em uma tabela Delta no local path-to-delta-table:

GENERATE symlink_format_manifest FOR TABLE delta.`<path-to-delta-table>`

Scala

Usando o Spark, execute o comando a seguir em uma tabela Delta no local path-to-delta-table:

val deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Java

Usando o Spark, execute o comando a seguir em uma tabela Delta no local path-to-delta-table:

DeltaTable deltaTable = DeltaTable.forPath(<path-to-delta-table>);
deltaTable.generate("symlink_format_manifest");

Python

Usando o Spark, execute o comando a seguir em uma tabela Delta no local path-to-delta-table:

deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Criar tabelas Delta do BigLake

Para criar uma tabela Delta do BigLake, use a instrução CREATE EXTERNAL TABLE com o campo file_set_spec_type definido como NEW_LINE_DELIMITED_MANIFEST:

  1. Acessar a página do BigQuery.

    Acessar o BigQuery

  2. No editor de consultas, execute a instrução CREATE EXTERNAL TABLE:

    CREATE EXTERNAL TABLE PROJECT_ID.DATASET_NAME.TABLE_NAME
WITH PARTITION COLUMNS(
`PARTITION_COLUMN PARTITION_COLUMN_TYPE`,)
WITH CONNECTION `PROJECT_IDREGION.CONNECTION_NAME`
OPTIONS (
   format = "DATA_FORMAT",
   uris = ["URI"],
   file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST',
   hive_partition_uri_prefix = "PATH_TO_DELTA_TABLE"
   max_staleness = STALENESS_INTERVAL,
   metadata_cache_mode = 'CACHE_MODE');

    Substitua:

    • DATASET_NAME: o nome do conjunto de dados que você criou.
    • TABLE_NAME: o nome que você quer dar a esta tabela.
    • REGION: o local onde a conexão está localizada (por exemplo, us-east1)
    • CONNECTION_NAME: o nome da conexão que você criou.
    • DATA_FORMAT: qualquer um dos formatos compatíveis (como PARQUET)
    • URI: o caminho para o arquivo de manifesto (por exemplo, gs://mybucket/path).
    • PATH_TO_DELTA_TABLE: um prefixo comum para todos os URIs de origem antes do início da codificação da chave de partição.
    • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

      Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação recupera metadados do Delta Lake.

    • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

      Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

      Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

    Exemplo:

    CREATE EXTERNAL TABLE mydataset.mytable
WITH CONNECTION `us-east1.myconnection`
OPTIONS (
    format="PARQUET",
    uris=["gs://mybucket/path/partitionpath=*"],
    file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST'
    hive_partition_uri_prefix = "gs://mybucket/path/"
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

Fazer upgrade das tabelas do BigLake

Também é possível acelerar o desempenho das cargas de trabalho aproveitando o armazenamento em cache de metadados e as visualizações materializadas. Se você quiser usar o armazenamento em cache de metadados, especifique as configurações ao mesmo tempo. Para acessar detalhes como o formato e o URI de origem da tabela, consulte Receber informações da tabela.

Para atualizar uma tabela externa para uma do BigLake ou atualizar um BigLake, selecione uma das seguintes opções:

SQL

Use a instrução DDL CREATE OR REPLACE EXTERNAL TABLE para atualizar uma tabela:

  1. No Console do Google Cloud, acesse a página BigQuery.

    Ir para o BigQuery

  2. No editor de consultas, digite a seguinte instrução:

    CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION `REGION.CONNECTION_ID`
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Substitua:

    • PROJECT_ID: o nome do projeto que contém a tabela
    • DATASET: o nome do conjunto de dados onde está a tabela
    • EXTERNAL_TABLE_NAME: o nome da tabela
    • REGION: a região que contém a conexão
    • CONNECTION_ID: o nome da conexão a ser usada
    • TABLE_FORMAT: o formato usado pela tabela

      Não é possível mudar isso durante a atualização da tabela.

    • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela externa, no formato ['gs://bucket_name/[folder_name/]file_name'].

      É possível selecionar vários arquivos do bucket especificando um caractere curinga de asterisco (*) no caminho. Por exemplo, ['gs://mybucket/file_name*']. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

      É possível especificar vários buckets para a opção uris fornecendo múltiplos caminhos.

      Os exemplos a seguir mostram valores uris válidos:

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Quando você especifica valores uris voltados para vários arquivos, todos eles precisam compartilhar um esquema compatível.

      Para mais informações sobre o uso de URIs do Cloud Storage no BigQuery, consulte Caminho do recurso do Cloud Storage.

    • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela e quando eles precisam ser atualizados para que a operação possa usá-los.

      Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

      Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

    • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual.

      Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

      Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

      Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use os comandos bq mkdef e bq update para atualizar uma tabela:

  1. Gere uma definição de tabela externa que descreva os aspectos da tabela a serem alterados:

    bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

    Substitua:

    • PROJECT_ID: o nome do projeto que contém a conexão.
    • REGION: a região que contém a conexão.
    • CONNECTION_ID: o nome da conexão a ser usada.
    • TABLE_FORMAT: o formato usado pela tabela. Não é possível mudar isso durante a atualização da tabela.

    • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

      Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

      Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

    • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os dados da tabela externa, no formato gs://bucket_name/[folder_name/]file_name.

      É possível limitar os arquivos selecionados no bucket especificando um caractere curinga de asterisco (*) no caminho. Por exemplo, gs://mybucket/file_name*. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

      É possível especificar vários buckets para a opção uris fornecendo múltiplos caminhos.

      Os exemplos a seguir mostram valores uris válidos:

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.csv
      • gs://bucket/path1/*,gs://bucket/path2/file00*

      Quando você especifica valores uris voltados para vários arquivos, todos eles precisam compartilhar um esquema compatível.

      Para mais informações sobre o uso de URIs do Cloud Storage no BigQuery, consulte Caminho do recurso do Cloud Storage.

    • DEFINITION_FILE: o nome do arquivo de definição de tabela que você está criando.

  2. Atualize a tabela usando a nova definição de tabela externa:

    bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

    Substitua:

    • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela e quando eles precisam ser atualizados para que a operação possa usá-los. Para saber mais sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

      Para ativar o armazenamento em cache de metadados, especifique um valor de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

    • DEFINITION_FILE: o nome do arquivo de definição da tabela que você criou ou atualizou.

    • PROJECT_ID: o nome do projeto que contém a tabela.

    • DATASET: o nome do conjunto de dados onde está a tabela

    • EXTERNAL_TABLE_NAME: o nome da tabela

Consultar o BigLake e tabelas externas

Após criar uma tabela do BigLake, consulte-a usando a sintaxe do Google SQL, como se ela fosse uma tabela padrão do BigQuery. Por exemplo, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Limitações

  • O BigQuery só aceita a consulta de tabelas do leitor Delta Lake v1.

  • A integração do Hudi com o BigQuery só funciona para tabelas copy-on-write particionadas no estilo do Hive.

  • Não é possível usar manifestos para consultar dados no armazenamento de terceiros.

A seguir