Importer des fichiers Parquet dans le stockage vers le catalogue d'exécution Lakehouse à l'aide de Dataflow

Vous pouvez utiliser un plan de compilateur de jobs Dataflow pour ajouter des fichiers Apache Parquet existants dans le cloud (Cloud Storage, Amazon S3 ou Azure Blob Storage) à une table Apache Iceberg dans un lakehouse sans frontières.

Ce processus utilise la transformation IcebergAddFiles. Si vos fichiers Parquet se trouvent dans Cloud Storage, cette transformation les enregistre dans Lakehouse sans déplacer ni réécrire les données sous-jacentes. Si vos fichiers se trouvent dans un système de stockage externe comme Amazon S3, ils sont copiés dans Cloud Storage pour accélérer les requêtes via Lakehouse, puis enregistrés.

Utilisez les informations de connexion suivantes pour ajouter des fichiers Parquet à partir d'un espace de stockage dans le cloud à une table Apache Iceberg dans Lakehouse.

Avant de commencer

  1. Activez les API Dataflow, BigQuery et Lakehouse.

  2. Pour obtenir les autorisations nécessaires pour créer les ressources, demandez à votre administrateur de vous accorder les rôles IAM (Identity and Access Management) requis sur votre projet.

  3. Créez un catalogue, un espace de noms et une table Lakehouse dans lesquels importer des données.

  4. Créez un bucket de stockage dans le cloud (Cloud Storage, Amazon S3 ou Azure Blob Storage) et importez-y vos fichiers Parquet.

  5. Si le bucket de stockage dans le cloud que vous utilisez n'est pas Cloud Storage de Google, créez un bucket Cloud Storage pour stocker les journaux d'erreurs de votre job.

Compatibilité et limites

L'importation de fichiers Parquet stockés dans le cloud vers Lakehouse à l'aide de Dataflow présente les limites suivantes :

  • Les données sources doivent être au format Apache Parquet et stockées dans Cloud Storage, Amazon S3 ou Azure Blob Storage.
  • Cette fonctionnalité n'est compatible qu'avec les pipelines par lots.

Importer des fichiers Parquet dans Lakehouse

Suivez les étapes ci-dessous pour importer des fichiers Parquet depuis un espace de stockage dans le cloud vers une table Iceberg dans Lakehouse à l'aide de l'UI du générateur de jobs Dataflow.

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

    Accéder à Lakehouse

  2. Sélectionnez le catalogue, l'espace de noms et la table dans lesquels vous souhaitez importer des données.

  3. Sur la page Détails de la table, cliquez sur Importer une table, puis sélectionnez À partir de fichiers Apache Parquet (lot).

    La page Générateur de jobs de Dataflow s'ouvre.

  4. Dans la section Sources :

    1. Ouvrez l'entrée source CreateGlobalInput déjà créée.

    2. Dans la section de l'éditeur Configuration de la source YAML, saisissez un ou plusieurs chemins d'accès à vos fichiers Parquet dans la séquence elements.

      Pour améliorer l'efficacité de l'importation, spécifiez plusieurs ensembles de fichiers (globs) lorsque vous enregistrez un grand nombre de fichiers. Exemple :

      reshuffle: true
      elements:
        -   gs://BUCKET_NAME/restaurant-data/2023/*.parquet
        -   gs://BUCKET_NAME/restaurant-data/2024/*.parquet
      
    3. Cliquez sur OK.

  5. Dans la section Transformations :

    1. Cliquez sur la section de transformation IcebergAddFiles pour l'ouvrir.

    2. Dans le champ Table Iceberg, saisissez l'espace de noms et le nom de la table. Par exemple, NAMESPACE .TABLE_NAME .

    3. Facultatif : Dans le champ Taille du fichier manifeste, saisissez le nombre de fichiers de données à inclure dans chaque fichier manifeste. La valeur par défaut est 10 000.

    4. Sous Propriétés du catalogue, configurez les éléments suivants :

      1.  : emplacement Cloud Storage de votre catalogue. Exemple :gs://CATALOG_PATH

      2. header.x-goog-user-project : ID de votre projet Google Cloud  : PROJECT_ID.

    5. Facultatif : Pour permettre au job de mettre à jour le schéma de la table de destination afin qu'il corresponde à vos fichiers Parquet, sélectionnez une ou plusieurs options dans la liste Évolution du schéma. Pour en savoir plus, consultez Configurer l'évolution du schéma.

    6. Cliquez sur OK.

    7. Si vous effectuez une migration depuis Amazon S3 ou Azure Blob Storage, vous devez fournir des configurations supplémentaires pour copier des fichiers Parquet vers Cloud Storage. Cette étape n'est pas nécessaire si vos fichiers se trouvent déjà dans Cloud Storage.

      1. Cliquez sur la section de transformation CopyFilesToGCS pour l'ouvrir.

      2. Définissez la valeur du paramètre de configuration gcs_file_path pour fournir le bucket Cloud Storage complet vers lequel copier les fichiers temporaires. Nous vous recommandons d'utiliser le même bucket Cloud Storage que celui utilisé par l'entrepôt Lakehouse.

      3. Cliquez sur OK.

      4. Cliquez sur la section Options Dataflow pour l'ouvrir.

      5. Si vos fichiers Parquet se trouvent dans Amazon S3, cliquez sur Ajouter des options de pipeline supplémentaires pour fournir des options de pipeline Apache Beam liées à S3. Par exemple, s3_region_name, s3_access_key_id, s3_secret_access_key et leurs valeurs correspondantes.

      6. Si vos fichiers Parquet se trouvent dans Azure Blob Storage, cliquez sur Ajouter des options de pipeline supplémentaires pour fournir des options de pipeline Apache Beam liées à Azure. Par exemple, azure_connection_string, blob_service_endpoint, azure_managed_identity_client_id et leurs valeurs correspondantes.

  6. Dans la section Sinks (Sinks) :

    1. Cliquez sur le récepteur Write results (Écrire les résultats) pour l'ouvrir.

    2. Dans le champ Emplacement JSON, spécifiez l'emplacement Cloud Storage et le nom du fichier pour écrire les résultats d'erreur. Exemple :

      gs://BUCKET_NAME/errors/errors.json
      
    3. Cliquez sur OK.

  7. Dans la section Options Dataflow, cliquez sur Exécuter le job.

Si vous devez personnaliser davantage le pipeline Dataflow utilisé pour enregistrer les fichiers Parquet, vous pouvez le faire à l'aide du formulaire du générateur de jobs ou de l'éditeur YAML.

Configurer l'évolution du schéma

Par défaut, la transformation IcebergAddFiles ne modifie pas le schéma de la table de destination. À l'aide d'un job par lot, vous pouvez activer l'évolution du schéma pour inspecter le pied de page de chaque fichier Parquet et mettre à jour le schéma de la table avant d'enregistrer les fichiers. Si la table de destination n'existe pas, le job la crée à partir des schémas combinés des fichiers Parquet.

Pour activer l'évolution du schéma dans la section de transformation IcebergAddFiles, sélectionnez une ou plusieurs options dans la liste Évolution du schéma :

  • Ajouter des colonnes : ajoute les colonnes d'un fichier Parquet qui ne figurent pas dans la table en tant que colonnes facultatives.
  • Rendre les colonnes facultatives : remplace une colonne de table obligatoire par une colonne facultative lorsqu'un fichier omet la colonne ou peut contenir des valeurs nulles.
  • Élargir les types de colonnes : élargit le type de données d'une colonne, par exemple de int à long.

Si un fichier de données possède un schéma incompatible, le pipeline échoue sans valider les modifications de schéma ni enregistrer de fichiers. Par exemple, un schéma est incompatible s'il nécessite une modification que vous n'avez pas sélectionnée ou s'il est en conflit avec la table ou un autre fichier.

Lorsque vous sélectionnez au moins une option d'évolution de schéma, vous pouvez également spécifier les colonnes qui doivent toujours être présentes et non nulles, même lorsque l'option Rendre les colonnes facultatives est sélectionnée. Développez Colonnes obligatoires, cliquez sur Ajouter un élément, puis saisissez une valeur dans le champ Nom de la colonne. Pour les champs imbriqués, séparez les noms de champs par des points, par exemple address.city. Les fichiers qui omettent une colonne obligatoire ou qui contiennent des valeurs nulles dans celle-ci sont envoyés vers la sortie d'erreur.

Examiner le résultat du job

Une fois le job terminé, vous pouvez vérifier que les données ont été enregistrées dans la table Iceberg en l'interrogeant dans BigQuery.

  1. Dans la liste des jobs Dataflow, vérifiez que l'état du job est Réussi.

    Accéder aux tâches

  2. Si le job échoue ou comporte des erreurs, consultez le fichier journal d'erreurs JSON dans Cloud Storage pour en savoir plus.

    Accéder à la page "Buckets"

  3. Dans la console Google Cloud , accédez à la page Studio de BigQuery.

    Accéder à BigQuery

  4. Dans l'éditeur de requête, saisissez une requête SQL pour inspecter la table. Vous pouvez utiliser la convention PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME pour interroger.

    SELECT * FROM `PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME` LIMIT 10
    
  5. Cliquez sur Exécuter.

  6. Examinez les résultats de la requête pour vous assurer que les données ont été traitées correctement.

Étapes suivantes