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:

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:

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>`

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")

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");

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:

SQLbq

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.

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.

A seguir