Interroger les formats de tables ouverts avec des fichiers manifestes

Ce document explique comment utiliser des fichiers manifestes pour interroger des données stockées dans des formats de table ouverts, tels que Apache Hudi et Delta Lake.

Certains formats de table ouverts, tels que Hudi et Delta Lake, exportent leur état actuel sous la forme d'un ou de plusieurs fichiers manifestes. Un fichier manifeste contient une liste de fichiers de données qui créent des tables. Avec la prise en charge du fichier manifeste dans BigQuery, vous pouvez interroger et charger des données stockées dans des formats de table ouverts.

Avant de commencer

Rôles requis

Pour interroger des tables BigLake basées sur des données Hudi et Delta Lake, assurez-vous de disposer des rôles suivants :

  • Utilisateur de connexion BigQuery (roles/bigquery.connectionUser)
  • Lecteur de données BigQuery (roles/bigquery.dataViewer)
  • Utilisateur BigQuery (roles/bigquery.user)

Vous pouvez également interroger des tables externes Hudi. Cependant, nous vous recommandons de mettre à niveau la table externe vers BigLake. Pour interroger des tables externes Hudi, assurez-vous de disposer des rôles suivants :

  • Lecteur de données BigQuery (roles/bigquery.dataViewer)
  • Utilisateur BigQuery (roles/bigquery.user)
  • Lecteur des objets de l'espace de stockage (roles/storage.objectViewer)

Selon vos autorisations, vous pouvez vous attribuer ces rôles ou demander à votre administrateur de vous les accorder. Pour en savoir plus sur l'attribution de rôles, consultez la page Afficher les rôles pouvant être attribués sur des ressources.

Pour afficher les autorisations exactes requises pour interroger des tables BigLake, développez la section Autorisations requises :

Autorisations requises

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Interroger des charges de travail Hudi

Procédez comme suit pour interroger des données Hudi :

  1. Créez une table externe basée sur les données Hudi.
  2. Mettez à niveau la table externe vers BigLake.

Créer des tables externes Hudi

Lorsque vous synchronisez des tables à l'aide de l'outil de synchronisation pour Hudi et BigQuery, activez l'option use-bq-manifest-file pour passer à l'approche basée sur des fichiers manifestes. Cette option exporte également un fichier manifeste dans un format compatible avec BigQuery et l'utilise pour créer une table externe avec le nom spécifié dans le paramètre --table.

Procédez comme suit pour créer une table externe Hudi :

  1. Pour créer une table externe Hudi, envoyez un job à un cluster Dataproc existant. Lorsque vous créez le connecteur Hudi-BigQuery, activez l'option use-bq-manifest-file pour passer à l'approche basée sur des fichiers manifestes. Cette option exporte un fichier manifeste dans un format compatible avec BigQuery et l'utilise pour créer une table externe avec le nom spécifié dans le paramètre --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

    Remplacez les éléments suivants :

    • JAR : si vous utilisez le connecteur Hudi-BigQuery, spécifiez hudi-gcp-bundle-0.14.0.jar. Si vous utilisez le composant Hudi dans Dataproc 2.1, spécifiez /usr/lib/hudi/tools/bq-sync-tool/hudi-gcp-bundle-0.12.3.1.jar.

    • PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table BigLake Hudi.

    • DATASET : ensemble de données dans lequel vous souhaitez créer la table BigLake Hudi.

    • LOCATION : emplacement dans lequel vous souhaitez créer la table BigLake Hudi.

    • TABLE : nom de la table que vous souhaitez créer.

      Si vous effectuez une transition depuis la version précédente du connecteur Hudi-BigQuery (0.13.0 et versions antérieures) qui a créé des vues sur les fichiers manifestes, assurez-vous d'utiliser le même nom de table, car cela va vous permettre de conserver le code du pipeline en aval existant.

    • URI : URI Cloud Storage que vous avez créé pour stocker le fichier manifeste Hudi.

      Cet URI pointe vers la partition de premier niveau. Veillez à inclure la clé de partition. Par exemple : gs://mybucket/hudi/mydataset/EventDate=*

    • URI_PREFIX : préfixe du chemin d'URI Cloud Storage (généralement le chemin d'accès aux tables Hudi).

    • BASE_PATH : chemin de base pour les tables Hudi.

      Par exemple : gs://mybucket/hudi/mydataset/

    • PARTITION_BY : valeur de la partition.

      Par exemple : EventDate

    Pour en savoir plus sur la configuration du connecteur, consultez la page Connecteur Hudi-BigQuery.

  2. Pour définir des contrôles précis ou accélérer les performances en activant la mise en cache des métadonnées, consultez la section Mettre à niveau des tables BigLake.

Interroger des charges de travail Delta

Les tables Delta sont désormais compatibles de façon native. Nous vous recommandons de créer des tables BigLake Delta pour les charges de travail Delta. Les tables BigLake Delta Lake sont compatibles avec les tables Delta Lake plus avancées, y compris les tables avec remappage de colonnes et vecteurs de suppression. De plus, les tables BigLake Delta lisent directement le dernier instantané. Les mises à jour sont donc disponibles immédiatement.

Procédez comme suit pour interroger des charges de travail Delta :

  1. Générez un fichier manifeste.
  2. Créez une table BigLake basée sur le fichier manifeste.
  3. Définissez des contrôles précis ou accélérez les performances en activant la mise en cache des métadonnées. Pour ce faire, consultez la section Mettre à niveau des tables BigLake.

Générer un fichier manifeste

BigQuery accepte le fichier manifeste au format SymLinkTextInputFormat, qui correspond à une liste d'URI délimités par un saut de ligne. Pour en savoir plus sur la génération d'un fichier manifeste, consultez la section Configurer l'intégration Presto-Delta Lake et interroger des tables Delta.

Pour générer un fichier manifeste, envoyez un job à un cluster Dataproc existant :

SQL

À l'aide de Spark, exécutez la commande suivante sur une table Delta située à l'emplacement path-to-delta-table :

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

Scala

À l'aide de Spark, exécutez la commande suivante sur une table Delta située à l'emplacement path-to-delta-table :

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

Java

À l'aide de Spark, exécutez la commande suivante sur une table Delta située à l'emplacement path-to-delta-table :

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

Python

À l'aide de Spark, exécutez la commande suivante sur une table Delta située à l'emplacement path-to-delta-table :

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

Créer des tables BigLake Delta

Pour créer une table BigLake Delta, utilisez l'instruction CREATE EXTERNAL TABLE avec le champ file_set_spec_type défini sur NEW_LINE_DELIMITED_MANIFEST :

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, exécutez l'instruction 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');

    Remplacez les éléments suivants :

    • DATASET_NAME : nom de l'ensemble de données que vous avez créé.
    • TABLE_NAME : nom à attribuer à la table.
    • REGION : emplacement de la connexion (par exemple, us-east1).
    • CONNECTION_NAME : nom de la connexion créée
    • DATA_FORMAT : tout format accepté (tel que PARQUET).
    • URI : chemin d'accès au fichier manifeste (par exemple, gs://mybucket/path).
    • PATH_TO_DELTA_TABLE : préfixe commun à tous les URI sources avant le début de l'encodage de la clé de partition.
    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table BigLake et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur de littéral d'intervalle comprise entre 30 minutes et 7 jours. Par exemple, spécifiez INTERVAL 4 HOUR pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération récupère à la place les métadonnées de Delta Lake.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

    Exemple :

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

Mettre à niveau des tables BigLake

Vous pouvez également accélérer les performances de vos charges de travail en tirant parti de la mise en cache des métadonnées et des vues matérialisées. Si vous souhaitez utiliser la mise en cache des métadonnées, vous pouvez spécifier en même temps les paramètres s'y rapportant. Pour obtenir des détails sur la table, tels que son format source et son URI source, consultez la page Obtenir des informations sur la table.

Pour mettre à jour une table externe vers une table BigLake, ou pour mettre à jour une table BigLake existante, sélectionnez l'une des options suivantes :

SQL

Utilisez l'instruction LDD CREATE OR REPLACE EXTERNAL TABLE pour mettre à jour une table :

  1. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet contenant la table
    • DATASET : nom de l'ensemble de données contenant la table
    • EXTERNAL_TABLE_NAME : nom de la table
    • REGION : région qui contient la connexion
    • CONNECTION_ID : nom de la connexion à utiliser
    • TABLE_FORMAT : format utilisé par la table

      Vous ne pouvez pas modifier ce paramètre lors de la mise à jour de la table.

    • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table externe, au format ['gs://bucket_name/[folder_name/]file_name'].

      Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le chemin. Par exemple, ['gs://mybucket/file_name*']. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

      Les exemples suivants montrent des valeurs uris valides :

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

      Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

      Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser.

      Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur de littéral d'intervalle comprise entre 30 minutes et 7 jours. Par exemple, spécifiez INTERVAL 4 HOUR pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement.

      Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

  3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez les commandes bq mkdef et bq update pour mettre à jour une table :

  1. Générez une définition de table externe décrivant les aspects de la table à modifier :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet contenant la connexion
    • REGION : région qui contient la connexion
    • CONNECTION_ID : nom de la connexion à utiliser.
    • TABLE_FORMAT : format utilisé par la table. Vous ne pouvez pas modifier ce paramètre lors de la mise à jour de la table.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mettre en cache les métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé selon un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

    • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table externe, au format gs://bucket_name/[folder_name/]file_name.

      Vous pouvez limiter les fichiers sélectionnés à partir du bucket en spécifiant un caractère générique astérisque (*) dans le chemin. Par exemple, gs://mybucket/file_name*. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

      Les exemples suivants montrent des valeurs uris valides :

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

      Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

      Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

    • DEFINITION_FILE : nom du fichier de définition de table que vous créez.

  2. Mettez à jour la table en utilisant la nouvelle définition de table externe :

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

    Remplacez les éléments suivants :

    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur d'intervalle entre 30 minutes et 7 jours, à l'aide du format Y-M D H:M:S décrit dans la documentation de type de données INTERVAL. Par exemple, spécifiez 0-0 0 4:0:0 pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • DEFINITION_FILE : nom du fichier de définition de table que vous avez créé ou mis à jour.

    • PROJECT_ID : nom du projet contenant la table.

    • DATASET : nom de l'ensemble de données contenant la table.

    • EXTERNAL_TABLE_NAME : nom de la table

Interroger des tables BigLake et des tables externes

Après avoir créé une table BigLake, vous pouvez l'interroger à l'aide d'une syntaxe GoogleSQL, comme pour une table BigQuery standard. Par exemple, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Limites

  • BigQuery n'est compatible qu'avec l'interrogation de tables intégrant la v1 du lecteur Delta Lake.

  • L'intégration de Hudi et BigQuery ne fonctionne que pour les tables copy-on-write disposant d'un partitionnement Hive.

Étapes suivantes