Utiliser l'agent d'ingénierie des données pour créer et modifier des pipelines de données

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Pour envoyer des commentaires ou poser des questions sur cette fonctionnalité en preview, contactez [e-mail].

L'agent d'ingénierie des données vous permet d'utiliser Gemini dans BigQuery pour créer, modifier et gérer des pipelines de données afin de charger et de traiter des données dans BigQuery. L'agent d'ingénierie des données vous permet d'utiliser des requêtes en langage naturel pour générer des pipelines de données à partir de diverses sources de données ou d'adapter des pipelines de données existants à vos besoins en ingénierie des données. L'agent d'ingénierie des données présente les caractéristiques suivantes :

• Langage naturel pour la création de pipelines : l'agent utilise Gemini pour comprendre vos données et interpréter vos instructions en langage clair. Vous pouvez utiliser des instructions en langage clair pour demander à l'agent Data Engineering de créer ou de modifier des pipelines de données.

• Intégration de Dataform : l'agent génère et organise le code de pipeline nécessaire dans des fichiers SQLX au sein d'un dépôt Dataform. L'agent fonctionne dans l'espace de travail Dataform. Les pipelines Dataform sont donc automatiquement disponibles pour l'agent.

• Instructions pour les agents personnalisés : créez des instructions en langage clair pour définir des règles personnalisées pour l'agent Data Engineering. Les instructions pour les agents sont persistantes dans toute votre organisation. Elles peuvent être utiles pour appliquer des règles à l'échelle de l'organisation, telles que des conventions de dénomination ou des guides de style.

• Validation du pipeline : l'agent valide tout code généré pour s'assurer que les pipelines de données sont fonctionnels.

Vous pouvez utiliser des requêtes en langage naturel avec l'agent Data Engineering pour créer des fichiers SQLX de tables, de vues, d'assertions, de déclarations et d'opérations. Par exemple, vous pouvez utiliser l'agent Data Engineering pour effectuer les opérations suivantes :

• Chargez des données à partir de sources de données externes telles que Cloud Storage dans différents formats, comme CSV, AVRO ou PARQUET.
• Créez ou utilisez des routines BigQuery (UDF) existantes pour effectuer des analyses et des transformations personnalisées sur vos données.
• Définissez des consignes réutilisables pour l'agent en langage naturel.

Pour obtenir d'autres exemples de requêtes que vous pouvez utiliser avec l'agent Data Engineering, consultez Exemples de requêtes.

Limites

L'agent Data Engineering présente les limites suivantes :

• L'agent Data Engineering est une offre de pré-DG qui n'est pas destinée à une utilisation en production.
• L'agent Data Engineering n'accepte pas les commandes en langage naturel pour les types de fichiers suivants :
  • Notebooks
  • Préparation des données
  • Javascript dans n'importe quel SQLx
• L'agent Data Engineering ne peut pas exécuter de pipelines. Les utilisateurs doivent examiner, exécuter ou planifier des pipelines.
• L'agent Data Engineering ne peut pas valider le code SQL qui dépend de ressources intermédiaires inexistantes sans l'invocation complète du pipeline (déclenchée par l'utilisateur).
• L'agent Data Engineering ne peut pas rechercher de liens Web ni d'URL fournis dans les instructions ou les requêtes directes.
• Lorsque vous importez des fichiers dans un fichier d'instructions de l'agent, la syntaxe d'importation @ n'accepte que les chemins d'accès commençant par ./, / ou une lettre.
• La fonctionnalité d'aperçu des données n'est compatible qu'avec les tables, les déclarations ou les requêtes dont l'indicateur hasOutput est défini sur true.

Régions où le service est disponible

Gemini dans BigQuery utilise Google Cloudpour l'équilibrage de charge, ce qui lui permet de fonctionner à l'échelle mondiale. Comme Gemini dans BigQuery a un mode de fonctionnement mondial, vous ne pouvez pas choisir la région à utiliser.

Toutes les requêtes Dataform et BigQuery sont envoyées à leurs points de terminaison régionaux respectifs. Par conséquent, toutes les données et tous les codes restent dans leur région.

Gemini dans BigQuery est proposé depuis les régions suivantes :

Amériques

• Iowa (us-central1)

Europe

• Finlande (europe-north1)
• Francfort (europe-west3)

Comment l'agent Data Engineering utilise vos données

Pour générer des réponses d'agent de meilleure qualité, l'agent Data Engineering peut récupérer des données et des métadonnées supplémentaires à partir de BigQuery et de Dataplex Universal Catalog, y compris des exemples de lignes de tables BigQuery et des profils d'analyse de données générés dans Dataplex Universal Catalog. Ces données ne sont pas utilisées pour entraîner l'agent d'ingénierie des données. Elles ne sont utilisées que lors des conversations avec l'agent, en tant que contexte supplémentaire pour informer ses réponses.

Avant de commencer

Assurez-vous que Gemini dans BigQuery est activé pour votre projet Google Cloud . Pour en savoir plus, consultez Configurer Gemini dans BigQuery.

Vous devez également activer l'API Gemini Data Analytics.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'agent Data Engineering, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

• Éditeur de code Dataform (roles/dataform.codeEditor)
• Utilisateur de job BigQuery (roles/bigquery.jobuser)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

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

Générer un pipeline de données avec l'agent d'ingénierie des données

Pour utiliser l'agent d'ingénierie des données dans BigQuery, sélectionnez l'une des options suivantes :

Pipelines BigQuery

Vous pouvez utiliser l'agent d'ingénierie des données dans l'interface des pipelines BigQuery en procédant comme suit :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, cliquez sur arrow_drop_down Créer > Pipeline.

3. Sélectionnez une option pour les identifiants d'exécution, puis cliquez sur Commencer. Ces identifiants ne sont pas utilisés par l'agent, mais sont nécessaires pour exécuter le pipeline de données généré.

4. Cliquez sur Tester l'expérience de l'agent pour le pipeline de données.

5. Dans le champ Demander à l'agent, saisissez une requête en langage naturel pour générer un pipeline de données. Exemple :

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Une fois votre requête saisie, cliquez sur Envoyer.

6. L'agent d'ingénierie des données génère un pipeline de données en fonction de votre requête.

Le pipeline de données généré par l'agent d'ingénierie des données est une proposition de pipeline de données. Vous pouvez cliquer sur un nœud de pipeline pour examiner la requête SQLX générée. Pour appliquer le pipeline de données suggéré par l'agent, cliquez sur Appliquer.

Dataform

Vous pouvez utiliser l'agent d'ingénierie des données dans Dataform en procédant comme suit :

1. Accédez à la page Dataform.

   Accéder à Dataform

2. Sélectionnez un dépôt.

3. Sélectionnez ou créez un espace de travail de développement.

4. Dans l'espace de travail, cliquez sur Demander à l'agent.

5. Dans le prompt Demander à l'agent qui s'affiche, saisissez une requête en langage naturel pour générer un pipeline de données. Exemple :

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Une fois votre requête saisie, cliquez sur Envoyer.

Une fois votre requête envoyée, l'agent Data Engineering génère un pipeline de données et modifie les fichiers SQLX Dataform en fonction de votre requête. L'agent applique ces modifications directement aux fichiers de votre espace de travail.

Examiner un pipeline de données

Dans un pipeline de données généré par l'agent d'ingénierie des données, vous pouvez cliquer sur un nœud de pipeline pour l'examiner.

• L'onglet Configuration affiche la requête SQLX générée associée au nœud.
• L'onglet Aperçu des données affiche les tables d'entrée et de sortie du fichier. Vous pouvez prévisualiser la transformation de vos données via ce nœud en cliquant sur Exécuter la tâche pour exécuter la tâche avec ou sans dépendances.

Modifier un pipeline de données

Vous pouvez modifier votre pipeline de données à l'aide de l'agent Data Engineering en cliquant sur Demander à l'agent et en saisissant une requête suggérant une modification du pipeline de données.

Examinez les modifications proposées par l'agent Data Engineering, puis cliquez sur Appliquer pour les appliquer.

Vous pouvez également modifier manuellement une requête SQLX en sélectionnant un nœud de pipeline, puis en cliquant sur Ouvrir.

Créer des instructions pour l'agent Data Engineering

Les instructions de l'agent sont des instructions en langage naturel destinées à l'agent d'ingénierie des données. Elles vous permettent de stocker des instructions persistantes afin que l'agent suive un ensemble de règles personnalisées prédéfinies. Utilisez des instructions pour l'agent si vous souhaitez que les résultats de votre agent soient cohérents dans toute votre organisation, par exemple avec des conventions de dénomination ou pour appliquer un guide de style.

Vous pouvez créer un fichier de contexte GEMINI.MD en tant que fichier d'instructions pour l'agent Data Engineering. Vous pouvez créer des fichiers d'instructions d'agent à utiliser dans votre espace de travail local ou utiliser les mêmes fichiers d'instructions dans plusieurs pipelines de données à l'aide d'un dépôt externe.

Pour créer des instructions pour l'agent :

1. Sous Demander à l'agent, cliquez sur Instructions du pipeline.
2. Dans le volet Instructions pour le pipeline, cliquez sur Créer un fichier d'instructions.

3. Dans le fichier GEMINI.MD qui s'affiche, saisissez vos instructions en langage naturel.

   L'exemple suivant montre un fichier d'instructions pour l'agent avec plusieurs règles :

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Cliquez sur Enregistrer.

Pour savoir comment structurer au mieux vos fichiers d'instructions d'agent, consultez Bonnes pratiques concernant les fichiers d'instructions d'agent.

Charger les instructions de l'agent à partir d'un dépôt externe

Vous pouvez spécifier un ensemble d'instructions d'agent à réutiliser dans plusieurs pipelines de données en associant un dépôt externe :

1. Sous Demander à l'agent, cliquez sur Instructions du pipeline.
2. Sous Dépôt externe, sélectionnez Utiliser les instructions d'un dépôt externe.
3. Dans les champs fournis, spécifiez un dépôt contenant les instructions de l'agent que vous souhaitez utiliser avec votre pipeline de données.
4. Cliquez sur Enregistrer.

Importer des fichiers locaux supplémentaires comme instructions pour l'agent

Vous pouvez également importer d'autres fichiers d'instructions pour l'agent Data Engineering dans le fichier GEMINI.md à l'aide de la syntaxe @file.md. Pour en savoir plus, consultez Processeur d'importation de mémoire.

Résoudre les problèmes liés aux pipelines de données

Si vous rencontrez des erreurs lors de la génération du pipeline de données, vérifiez que vous avez rempli toutes les conditions préalables requises pour exécuter l'agent Data Engineering. Pour en savoir plus, consultez Avant de commencer.

Si le pipeline de données généré rencontre des erreurs, vous pouvez demander à l'agent d'ingénierie des données de diagnostiquer les échecs de pipeline de données et de proposer des recommandations de dépannage en procédant comme suit :

1. Dans votre pipeline ou votre espace de travail de développement, cliquez sur l'onglet Exécutions.

2. Dans la liste des exécutions, recherchez l'exécution du pipeline de données qui a échoué. Vous pouvez identifier les exécutions ayant échoué dans la colonne État de l'exécution.

   

3. Pointez sur l'icône, puis cliquez sur Enquêter. L'agent Data Engineering exécute une analyse sur l'exécution de votre pipeline de données pour détecter les éventuelles erreurs.

   

4. Une fois l'analyse terminée, l'agent Data Engineering génère un rapport dans la section Observations et hypothèses. Ce rapport inclut :

   • Observations et points de données extraits des journaux d'exécution du pipeline de données
   • Causes probables de l'échec
   • Un ensemble d'étapes ou de recommandations exploitables pour résoudre le problème identifié

Grâce au rapport de dépannage de l'agent Data Engineering, vous pouvez appliquer les recommandations manuellement. Vous pouvez également demander à l'agent Data Engineering d'appliquer la correction pour vous en procédant comme suit :

1. Copiez les suggestions du rapport de dépannage.
2. Revenir à l'agent d'ingénierie des données :
   1. Si vous utilisez des pipelines BigQuery, accédez à la page des pipelines, puis cliquez sur Demander à l'agent.
   2. Si vous utilisez Dataform, cliquez sur Demander à un agent.
3. Collez les suggestions dans la requête et demandez à l'agent d'ingénierie des données d'appliquer les corrections directement à votre pipeline de données.
4. Cliquez sur Envoyer.

Exemples de requêtes

Les sections suivantes présentent des exemples de requêtes que vous pouvez utiliser avec l'agent Data Engineering pour développer votre pipeline de données.

Regrouper des données existantes dans une nouvelle table

Avec cette requête, l'agent d'ingénierie des données utilise le schéma et les exemples pour déduire le regroupement des données par clé. L'agent configure généralement une nouvelle configuration de table avec des descriptions de table et de colonnes.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

Ajouter des vérifications de la qualité des données à une table existante

Avec cette requête, l'agent déduit des contrôles de qualité raisonnables pour la table en fonction du schéma et des exemples. Vous pouvez également ajouter des assertions subjectives à la requête.

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

Créer une colonne dérivée et ajouter des vérifications de la qualité des données à la nouvelle table

La requête suivante montre comment ajouter un tableau et une colonne, et spécifier en même temps des contrôles de qualité pour le tableau.

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

Créer des UDF dans la définition du modèle

L'agent Data Engineering peut également configurer le LDD pour créer des fonctions définies par l'utilisateur (UDF). L'agent ne créera pas la UDF définie par l'utilisateur, mais vous pourrez UDF créer en exécutant le pipeline de données. Ces UDF peuvent être utilisées dans les définitions de modèle de votre pipeline de données.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Bonnes pratiques

Les sections suivantes suggèrent des bonnes pratiques pour travailler avec l'agent Data Engineering et Dataform.

Bonnes pratiques avec l'agent Data Engineering

Utilisez les instructions de l'agent pour les demandes courantes. Si vous appliquez souvent les mêmes techniques ou si vous apportez fréquemment les mêmes corrections à l'agent, utilisez les instructions de l'agent comme emplacement centralisé pour stocker les instructions et les demandes courantes.

Donnez plus de contexte à l'agent. Vous pouvez fournir au modèle plus de contexte à partir de Dataplex Universal Catalog en associant des termes de glossaire aux tables et colonnes BigQuery, et en générant des analyses de profilage des données. Les termes du glossaire peuvent être utilisés pour taguer les colonnes qui nécessitent un contexte supplémentaire, comme les colonnes contenant des informations permettant d'identifier personnellement l'utilisateur qui nécessitent des instructions de traitement spécifiques, ou pour identifier les colonnes correspondantes avec des noms différents dans les tables. Les analyses de profil de données permettent à l'agent de mieux comprendre la distribution des données dans les colonnes d'un tableau et peuvent l'aider à créer des assertions de qualité des données plus spécifiques. Pour en savoir plus, consultez À propos du profilage de données.

Écrivez de manière claire. Énoncez votre demande clairement et évitez d'être vague. Dans la mesure du possible, fournissez des sources de données source et de destination lorsque vous posez une question, comme dans l'exemple suivant :

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Formulez des demandes directes et ciblées. Posez une question à la fois et rédigez des requêtes concises. Pour les requêtes comportant plusieurs questions, vous pouvez détailler chaque partie distincte de la question pour plus de clarté, comme dans l'exemple suivant :

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Donnez des instructions explicites et mettez en avant les termes clés. Vous pouvez mettre l'accent sur des termes ou des concepts clés dans vos requêtes et indiquer que certaines exigences sont importantes, comme dans l'exemple suivant :

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Spécifiez l'ordre des opérations. Pour les tâches ordonnées, vous pouvez structurer votre requête sous forme de liste, où les éléments listés sont divisés en petites étapes ciblées, comme dans l'exemple suivant :

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id
  3. Load the final result into the reporting.customer_orders table.

Affinez et itérez. Essayez différentes expressions et approches pour voir ce qui donne les meilleurs résultats. Si l'agent génère du code SQL non valide ou commet d'autres erreurs, guidez-le à l'aide d'exemples ou de documentation publique.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).

Bonnes pratiques concernant les fichiers d'instructions de l'agent

Créez des fichiers d'instructions pour l'agent afin de personnaliser l'agent Data Engineering en fonction de vos besoins. Lorsque vous utilisez des instructions d'agent, nous vous recommandons d'effectuer les opérations suivantes :

• Tous les chemins d'accès aux fichiers dans Dataform sont relatifs à la racine du dépôt. Utilisez des chemins relatifs pour toute syntaxe @file.md afin d'importer correctement les instructions vers GEMINI.md.
• Les fichiers importés dans GEMINI.md peuvent eux-mêmes contenir des importations, ce qui peut créer une structure imbriquée. Pour éviter une récursion infinie, GEMINI.md est limité à une profondeur d'importation maximale de cinq niveaux.
• Pour partager des instructions entre les pipelines de données, stockez-les dans un dépôt Dataform central et associez-les au dépôt Dataform de travail. Vous pouvez utiliser des instructions locales pour remplacer les règles centrales pour un comportement spécifique au pipeline.
• L'utilisation de titres et de listes dans le fichier d'instructions de l'agent peut aider à organiser et à clarifier les instructions pour l'agent Data Engineering.
• Donnez des noms de fichiers explicites et regroupez les instructions similaires dans un même fichier. Organisez les règles de manière logique par catégorie, fonctionnalité ou fonction à l'aide de titres Markdown.
• Pour éviter toute instruction contradictoire, définissez clairement les conditions spécifiques dans lesquelles chaque instruction s'applique.
• Itérez et affinez vos requêtes et votre workflow. Le comportement des agents évolue au fil du temps avec les déploiements d'agents et les mises à niveau de modèles. Nous vous recommandons donc d'itérer sur vos règles avec différentes requêtes pour identifier les points à améliorer. Synchronisez votre fichier de règles avec les modifications apportées à votre pipeline de données.

L'exemple suivant montre un fichier d'instructions d'agent nommé GEMINI.md qui utilise nos bonnes pratiques pour une utilisation efficace de l'agent Data Engineering :

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md