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

Ce document explique comment utiliser l'agent d'ingénierie des données dans BigQuery et Dataform pour créer et modifier des pipelines de données.

L'agent d'ingénierie des données vous permet de créer, de modifier et de gérer des pipelines de données pour charger et traiter des données dans BigQuery. Avec l'agent d'ingénierie des données, vous pouvez utiliser des requêtes en langage naturel pour générer des pipelines de données à partir de différentes sources de données ou adapter des pipelines de données existants à vos besoins en matière d'ingénierie des données.

L'agent génère et organise le code du pipeline de données directement dans les dépôts Dataform. L'agent fonctionne dans l'espace de travail Dataform. Les pipelines Dataform sont donc automatiquement disponibles pour l'agent.

Pour obtenir d'autres exemples de requêtes que vous pouvez utiliser avec l'agent d'ingénierie des données, consultez Exemples de requêtes.

Vous pouvez également utiliser l'API de l'agent d'ingénierie des données, qui utilise le protocole A2A, pour interagir avec l'agent.

Limites

L'agent d'ingénierie des données présente les limites suivantes :

• L'agent d'ingénierie des données n'est pas compatible avec les commandes en langage naturel pour les types de fichiers suivants :
  • Notebooks
  • Préparation des données
• L'agent d'ingénierie des données ne peut pas exécuter de pipelines. Vous devez examiner, exécuter ou planifier des pipelines.
• L'agent d'ingénierie des données ne peut pas rechercher de liens Web ni d'URL fournis dans des instructions ou des requêtes directes.
• Lors de l'importation de fichiers dans un fichier d'instructions d'agent, la syntaxe d'importation @ n'est compatible qu'avec les chemins 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.
• L'agent d'ingénierie des données est soumis aux limitations générales de la technologie d'IA.

Avant de commencer

Avant d'utiliser l'agent d'ingénierie des données, suivez les étapes de cette section.

Activer Gemini dans BigQuery

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

Activer les API requises

Remarque : Si vous ne disposez pas des autorisations nécessaires pour activer les API, demandez à l'administrateur de votre projet de le faire pour vous depuis le tableau de bord "API et services ". L'administrateur de votre projet peut également vous attribuer le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin) dans la Google Cloud console afin de vous autoriser à activer et désactiver les API pour le projet actuel.

Console

Activez les API suivantes dans la Google Cloud console pour le Google Cloud projet que vous utilisez avec l'API Conversational Analytics.

Activer l'API Gemini Data Analytics

Activer Gemini pour l' Google Cloud API

Activer l'API BigQuery

**Conseil** : Une fois que vous avez activé une API, actualisez la Google Cloud page de la console pour vérifier qu'elle est activée.

gcloud

Pour activer l'API Gemini Data Analytics, Gemini pour Google Cloud l'API et l'API BigQuery, utilisez Google Cloud CLI et exécutez les commandes gcloud services enable suivantes :

gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID
gcloud services enable cloudaicompanion.googleapis.com --project=PROJECT_ID
gcloud services enable bigquery.googleapis.com --project=PROJECT_ID

Remplacez PROJECT_ID par l'ID de votre Google Cloud projet.

Rôles requis

Pour obtenir l'autorisation nécessaire pour utiliser l'agent d'ingénierie des données, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

• Éditeur de code Dataform (roles/dataform.codeEditor)
• Utilisateur de tâche BigQuery (roles/bigquery.jobUser)
• Utilisateur sans état du chat des analyses de données Gemini (roles/geminidataanalytics.dataAgentStatelessUser)

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

Ce rôle prédéfini contient l' geminidataanalytics.locations.useDataEngineeringAgent autorisation, qui est requise pour utiliser l'agent d'ingénierie des données.

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

Prérequis pour l'intégration de Knowledge Catalog

Pour obtenir l'autorisation nécessaire pour intégrer l'agent d'ingénierie des données à Knowledge Catalog, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l' geminidataanalytics.locations.useDataEngineeringAgent autorisation, qui est requise pour intégrer l'agent d'ingénierie des données à Knowledge Catalog.

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

Vous devez également activer l'API Knowledge Catalog.

Chiffrer les données avec des clés Cloud Key Management Service

Vous pouvez chiffrer les données au niveau de l'ensemble de données ou du projet avec les clés Cloud Key Management Service par défaut gérées par le client dans BigQuery. Pour en savoir plus, consultez Définir une clé par défaut pour un ensemble de données et Définir une clé par défaut pour un projet.

Vous pouvez chiffrer le code du pipeline au niveau du projet en définissant une clé Cloud Key Management Service Dataform par défaut.

Configurer des périmètres VPC Service Controls

Si vous utilisez VPC Service Controls, vous devez configurer le périmètre pour protéger Dataform, BigQuery et l'API Conversational Analytics. Pour en savoir plus, consultez Dataform, BigQuery, et API Conversational Analytics.

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 Essayer 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. Par 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 que vous avez saisi une requête, 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.

L'agent d'ingénierie des données génère un brouillon 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 à 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 la requête Demander à l'agent qui s'affiche, saisissez une requête en langage naturel pour générer un pipeline de données. Par 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 que vous avez saisi une requête, cliquez sur Envoyer.

Une fois votre requête envoyée, l'agent d'ingénierie des données 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 à vos fichiers d'espace de travail.

Modifier un pipeline de données

Pour modifier votre pipeline de données, cliquez sur Demander à l'agent, puis saisissez une requête suggérant une modification du pipeline de données.

Examinez les modifications proposées par l'agent d'ingénierie des données, 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.

Examiner un pipeline de données

Vous pouvez cliquer sur un nœud de pipeline dans un pipeline de données généré par l'agent d'ingénierie des données 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 la table d'entrée et de sortie du fichier. Vous pouvez prévisualiser votre transformation de 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.

Résoudre les erreurs de pipeline 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 tous les prérequis pour exécuter l'agent d'ingénierie des données. Pour plus d'informations, consultez Avant de commencer.

Exécuter une investigation Gemini Cloud Assist

Aperçu

Cette fonctionnalité est soumise 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 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.

Pour résoudre d'autres problèmes liés aux pipelines, vous pouvez utiliser l'agent d'ingénierie des données pour effectuer une analyse des causes profondes et suggérer des recommandations de dépannage.

Cette fonctionnalité utilise les investigations Gemini Cloud Assist (aperçu) et n'est disponible que pour les utilisateurs disposant d'un contrat d'assistance Premium. Pour en savoir plus sur l'activation des investigations Gemini Cloud Assist, consultez Résoudre les problèmes liés aux investigations Gemini Cloud Assist.

Vous pouvez utiliser l'agent d'ingénierie des données pour résoudre les erreurs de pipeline de données 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 ayant échoué. Vous pouvez identifier les exécutions ayant échoué dans la colonne État.

   

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

   

4. Une fois l'analyse terminée, l'agent d'ingénierie des données génère un rapport dans la section Observations et hypothèses. Le rapport comprend les éléments suivants :

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

Grâce au rapport de dépannage de l'agent d'ingénierie des données, vous pouvez mettre en œuvre manuellement les recommandations. Vous pouvez également demander à l'agent d'ingénierie des données d'appliquer le correctif pour vous en procédant comme suit :

1. Copiez les suggestions du rapport de dépannage.
2. Revenez à 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 à l'agent.
3. Collez les suggestions dans la requête, puis demandez à l'agent d'ingénierie des données d'appliquer les correctifs directement à votre pipeline de données.
4. Cliquez sur Envoyer.

Créer des instructions pour l'agent

Les instructions pour 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 l'agent soient cohérents dans toute votre organisation, par exemple avec des conventions d'attribution de noms ou pour appliquer un guide de style.

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

Pour créer des instructions pour l'agent, procédez comme suit :

1. Sous Demander à l'agent, cliquez sur Instructions pour le 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 pour l'agent, consultez Bonnes pratiques concernant les fichiers d'instructions pour l'agent.

Charger des instructions pour l'agent à partir d'un dépôt externe

Pour réutiliser un ensemble d'instructions pour l'agent dans plusieurs pipelines de données, associez un dépôt externe :

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

Exemples de requêtes

Les sections suivantes fournissent des exemples de requêtes que vous pouvez utiliser avec l'agent d'ingénierie des données 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 colonne.

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

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

Cette requête montre comment ajouter une table et une colonne, et spécifier des vérifications de la qualité de la table en même temps :

  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 fonctions définies par l'utilisateur dans le cadre de la définition du modèle

L'agent d'ingénierie des données peut également configurer le LDD pour créer des fonctions définies par l'utilisateur. Bien que l'agent ne crée pas réellement la UDF, vous pouvez UDF créer en exécutant le pipeline de données. Ces fonctions définies par l'utilisateur 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

Pour améliorer les résultats lorsque vous utilisez l'agent d'ingénierie des données et Dataform, nous vous recommandons de procéder comme suit :

Utilisez des instructions pour l'agent pour les requêtes courantes. Si vous appliquez couramment certaines techniques ou si vous apportez fréquemment les mêmes corrections à l'agent, utilisez des instructions pour l'agent comme emplacement centralisé pour stocker les instructions et les requêtes courantes.

Utilisez des plans d'agent. Les plans d'agent peuvent être utiles pour décomposer les tâches complexes du pipeline. Les plans d'agent peuvent également vous montrer les hypothèses et les intentions de l'agent. Nous vous recommandons donc de les examiner pour vous assurer que le contexte approprié est fourni à l'agent.

Après avoir examiné un plan, vous pouvez le modifier en demandant à l'agent d'ingénierie des données de vous faire part de ses commentaires et de ses modifications. Exemple :

In the plan, ensure that all of the intermediate tables are views.

Dans certains cas, il peut être utile de demander à l'agent de générer un plan qui n'a pas besoin de votre approbation explicite. Le fait de créer le plan d'agent oblige l'agent d'ingénierie des données à décomposer ses actions, ce qui conduit souvent à de meilleurs résultats. Vous pouvez forcer l'agent à générer un plan et à l'exécuter automatiquement. Exemple :

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

É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 y êtes invité, comme illustré 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.

Fournissez des requêtes directes et ciblées. Posez une question à la fois et soyez concis. Pour les requêtes comportant plusieurs questions, détaillez chaque partie distincte de la question pour améliorer la clarté, comme illustré 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).

Fournissez des instructions explicites et mettez l'accent sur les termes clés. Vous pouvez mettre l'accent sur les termes ou concepts clés de vos requêtes et marquer certaines exigences comme importantes, comme illustré 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, structurez votre requête dans des listes, où les éléments listés sont divisés en petites étapes ciblées, comme illustré 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 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).