Établir un contexte de données de base avec Knowledge Catalog

Knowledge Catalog (anciennement Dataplex Universal Catalog) vous permet d'associer des métadonnées structurées et des définitions métier claires directement à vos éléments de données. En fournissant ce contexte, vous rendez vos données détectables, vous renforcez la confiance des utilisateurs et vous ancrez les agents IA.

Dans ce tutoriel destiné aux gestionnaires de données et aux analystes métier, vous allez suivre des étapes basées sur l'interface utilisateur pour créer des termes métier et un contexte de métadonnées standards avant d'automatiser ces workflows. Vous découvrirez également comment les concepts clés de Knowledge Catalog fonctionnent ensemble.

Objectifs

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

• Créez une source unique de vérité pour les termes métier avec un glossaire d'entreprise.
• Structurez et organisez les métadonnées avec des types d'aspects.
• Associez des métadonnées aux éléments de données avec des aspects.
• Utilisez la recherche Knowledge Catalog pour trouver exactement ce dont vous avez besoin à l'aide de ces nouvelles métadonnées structurées.

Avant de commencer

Avant de commencer, procédez comme suit :

• Sélectionnez un projet Google Cloud pour ce tutoriel.
• Vérifiez que la facturation est activée pour votre projet.

Configurer votre environnement

Ce tutoriel utilise Cloud Shell, un environnement de ligne de commande qui s'exécute dans le cloud.

1. Dans la console Google Cloud , cliquez sur Activer Cloud Shell dans la barre d'outils en haut à droite. Le provisionnement et la connexion à l'environnement prennent quelques instants.

2. Dans Cloud Shell, définissez vos variables PROJECT_ID et LOCATION afin que toutes les futures commandes ciblent votre projet Google Cloud spécifique.

   export PROJECT_ID=$(gcloud config get-value project)
   gcloud config set project $PROJECT_ID
   export LOCATION="us-central1"
   

   Remarque : Les sessions Cloud Shell expirent parfois. Avant d'exécuter des scripts shell, vous pouvez vérifier vos variables d'environnement en exécutant echo $PROJECT_ID. Si la commande renvoie une ligne vide, réexécutez les commandes d'exportation de cette étape de configuration de l'environnement.

3. Activez les services Google Cloud nécessaires.

   gcloud services enable \
     dataplex.googleapis.com \
     bigquery.googleapis.com 
   

Créer un ensemble de données BigQuery et préparer des exemples de données

Utilisez le code suivant pour créer un ensemble de données BigQuery et charger des exemples de transactions CSV dans une table. Une fois la table créée, Knowledge Catalog la découvre et crée une entrée pour elle dans le catalogue.

Une entrée est la représentation d'un élément de données dans Knowledge Catalog. Il s'agit d'un enregistrement dans le catalogue auquel vous pouvez associer des métadonnées. Au lieu d'ajouter du contexte à la table BigQuery (ou de l'enrichir) directement, vous l'ajoutez à son entrée dans Knowledge Catalog.

# Create the BigQuery Dataset in the us-central1 region
bq --location=$LOCATION mk --dataset \
    --description "Sample retail data for foundational data context tutorial" \
    $PROJECT_ID:retail_data

# Create a temporary CSV file with the sample data
echo "transaction_id,user_email,gmv,transaction_date
1001,[e-mail],150.50,2025-08-28
1002,[e-mail],75.00,2025-08-28" > /tmp/transactions.csv

# Load the data from the temporary CSV file into a BigQuery table
bq load \
    --source_format=CSV \
    --autodetect \
    retail_data.transactions \
    /tmp/transactions.csv

# (Optional) Clean up the temporary file
rm /tmp/transactions.csv

Exécutez une requête SELECT pour vérifier votre configuration :

bq query --nouse_legacy_sql "SELECT * FROM retail_data.transactions"

Exemple de résultat :

+----------------+------------------+-------+------------------+
| transaction_id |    user_email    |  gmv  | transaction_date |
+----------------+------------------+-------+------------------+
|           1001 | [e-mail] | 150.5 |       2025-08-28 |
|           1002 | [e-mail] |  75.0 |       2025-08-28 |
+----------------+------------------+-------+------------------+

Remarque : Vous n'avez pas besoin d'enregistrer ni d'importer manuellement la table dans Knowledge Catalog. Knowledge Catalog ingère automatiquement les métadonnées techniques des tables BigQuery et crée des entrées.

Établir des termes communs avec un glossaire d'entreprise

Un bon contexte de données repose sur des définitions claires qui répondent à des questions telles que "Que signifie ce nom de colonne ?" Par exemple, un développeur ne devrait pas avoir à deviner si une colonne nommée gmv correspond à la valeur marchande brute ou si elle inclut les taxes et les retours. Un glossaire d'entreprise crée une source unique de vérité pour ces définitions dans l'ensemble de votre organisation. Lorsque des collaborateurs ou des agents IA analysent vos données, ils héritent de ce contexte métier précis. Les définitions partagées permettent d'aligner les métriques entre les équipes (finance, ventes, opérations, etc.) et d'éviter les hallucinations des agents IA.

Pour créer un glossaire et définir votre premier terme, procédez comme suit :

1. Dans la console Google Cloud , accédez à la page Glossaires de Knowledge Catalog.

   Accéder à Glossaires

2. Cliquez sur Créer un glossaire d'entreprise.

3. Saisissez les informations suivantes :

   • Display name (Nom à afficher) : Retail Business Glossary
   • Emplacement : us-central1 (Iowa)

4. Cliquez sur Créer.

5. Cliquez sur Créer une catégorie.

6. Nommez la catégorie Sales Metrics, puis cliquez sur Créer.

7. Sélectionnez la catégorie Métriques de ventes, puis cliquez sur Ajouter un terme.

8. Nommez le terme Gross Merchandise Value, puis cliquez sur Créer.

9. Cliquez sur le terme valeur marchande brute pour ouvrir sa page d'informations.

10. Cliquez sur Ajouter à côté de Présentation. Saisissez les informations suivantes : The total value of merchandise sold over a given period of time before the deduction of any fees or expenses. This is a key indicator of e-commerce business growth.

11. Cliquez sur Enregistrer.

Vous avez maintenant créé un terme de glossaire que vous pouvez associer à des entrées de données dans votre organisation.

Définir des métadonnées techniques avec un type d'aspect

Lorsque vous travaillez avec des données, vous devez souvent répondre à des questions telles que "À qui appartient cet ensemble de données défectueux ?" ou "Cette table est-elle approuvée pour utilisation ?". Les tags de métadonnées non structurés tentent de répondre à ces questions, mais ils deviennent rapidement obsolètes ou incohérents. Par exemple, une table peut être taguée owner:bob et une autre steward:[e-mail]. Pour organiser vos métadonnées à grande échelle, vous avez besoin d'un schéma cohérent.

C'est là qu'interviennent les types d'aspects. Un type d'aspect est un modèle de métadonnées qui vous permet de définir des règles claires et des champs obligatoires. En exigeant des champs standards tels que des adresses e-mail valides pour les intendants des données, les scripts en aval peuvent valider et protéger automatiquement vos métadonnées.

Pour créer un type d'aspect, procédez comme suit :

1. Dans la console Google Cloud , accédez à l'onglet Types d'aspects de Knowledge Catalog sur la page Types de métadonnées.

   Accéder à "Types d'aspects"

2. Dans l'onglet Personnalisé, cliquez sur Créer.

3. Saisissez les informations suivantes :

   • Display name (Nom à afficher) : Data Asset Context
   • Emplacement : us-central1 (Iowa)

4. Dans la section Modèle, cliquez sur Ajouter un champ pour créer les trois champs suivants :

   • Champ 1 :

     • Display name (Nom à afficher) : Data Steward
     • Type : Text
     • Obligatoire : cochez la case.
     • Type de texte : Plain text

   • Champ 2 (cliquez sur Ajouter un champ) :

     • Display name (Nom à afficher) : Data Sensitivity
     • Type : Enum
     • Is Required (Obligatoire) : laissez l'option facultative.
     • Valeurs : ajoutez Public, Internal et Confidential.

   • Champ 3 (cliquez sur Ajouter un champ) :

     • Display name (Nom à afficher) : Last Review Date
     • Is Required (Obligatoire) : laissez l'option facultative.
     • Type : Date and time

5. Cliquez sur Enregistrer.

Vous disposez maintenant d'un type d'aspect pour les champs de métadonnées liés à la gouvernance des données, tels que l'intendant des données, le niveau de sensibilité et la date d'examen. Dans la section suivante, vous allez appliquer ce schéma à une entrée de table en associant un aspect avec des valeurs spécifiques pour ces champs.

Enrichir une entrée avec un contexte commercial et technique

Les noms de colonnes sont souvent abrégés ou ambigus. Associer une colonne à un terme de votre glossaire d'entreprise permet d'obtenir une définition claire et cohérente. Dans cette étape, vous allez enrichir l'entrée de la table retail_data.transactions en associant le terme Gross Merchandise Value à une colonne nommée gmv et en associant un aspect à l'entrée de la table à l'aide de votre type d'aspect.

Associer une colonne à un terme métier

Pour clarifier ce qu'est la colonne gmv dans retail_data.transactions, associez-la à votre terme Gross Merchandise Value.

1. Dans la console Google Cloud , accédez à la page Rechercher de Knowledge Catalog.

   Accéder à la recherche

2. Cliquez sur Filtres pour ouvrir le panneau Filtres.

3. Dans le champ Champ d'application, sélectionnez Projet actuel.

4. Recherchez retail_data.transactions, puis cliquez sur la table de transactions renvoyée.

5. Cliquez sur l'onglet Schéma.

6. Cochez la case à côté de la colonne gmv, puis cliquez sur Ajouter un terme métier.

7. Sélectionnez Gross Merchandise Value.

Associer un aspect à l'entrée de la table

En plus d'associer des termes métier à des colonnes, vous pouvez associer un aspect à une entrée de table pour capturer des métadonnées au niveau de la table, telles que la propriété et la sensibilité des données.

Un aspect est une instance d'un type d'aspect, avec des valeurs spécifiques pour les champs de métadonnées. Lorsque vous associez un aspect à une entrée, Knowledge Catalog vérifie les informations que vous fournissez par rapport au schéma défini dans le type d'aspect pour garantir la cohérence.

Pour définir la propriété et la sensibilité de la table retail_data.transactions, associez l'aspect Data Asset Context :

1. Dans l'onglet Détails de la page d'entrée retail_data.transactions, cliquez sur Ajouter à côté de Aspects facultatifs.
2. Sélectionnez Data Asset Context dans la liste.

3. Saisissez des valeurs dans les champs :

   • Responsable des données : [e-mail]
   • Sensibilité des données : sélectionnez Interne.
   • Last Review Date (Date du dernier examen) : sélectionnez la date du jour.

4. Cliquez sur Enregistrer.

En enrichissant votre exemple de données de transactions de vente au détail, vous avez établi une base solide de contexte de données dans Knowledge Catalog.

Rechercher des entrées à l'aide de métadonnées enrichies

Vous pouvez désormais utiliser la recherche Knowledge Catalog pour trouver des entrées en fonction du contexte commercial que vous avez configuré. Par exemple, vous pouvez rechercher tous les éléments présentant un niveau de sensibilité spécifique ou rechercher un terme de votre glossaire pour découvrir les tables sous-jacentes.

Remarque : Knowledge Catalog propose deux expériences de recherche distinctes avec des syntaxes différentes : Langage naturel (assisté par l'IA) et Mot clé (correspondance structurée/exacte). Ce tutoriel se concentre sur le langage naturel.

1. Dans la console Google Cloud , accédez à la page Rechercher de Knowledge Catalog.

   Accéder à la recherche

2. Cliquez sur Filtres pour ouvrir le panneau Filtres.

3. Dans le champ Champ d'application, sélectionnez Projet actuel.

4. Dans la barre de recherche, saisissez Find tables where the Data Asset Context aspect has Internal sensitivity..

5. Votre table retail_data.transactions devrait s'afficher dans la liste des résultats.

6. Effacez le contenu de la barre de recherche et saisissez Find tables with the Gross Merchandise Value term attached..

7. La table retail_data.transactions devrait à nouveau s'afficher dans les résultats, car sa colonne gmv est directement liée à ce terme métier.

Lorsque vous connectez un agent IA à Knowledge Catalog, il hérite automatiquement de ces métadonnées enrichies. Par exemple, lorsque vous demandez à un agent de récupérer des métriques de ventes internes, il lit l'aspect "Sensibilité des données" (que vous avez défini sur "Interne") et le terme de glossaire "valeur marchande brute" associé. Ce contexte partagé aide l'agent à vérifier ses sources de données, à respecter les règles d'accès et à éviter les hallucinations.

Effectuer un nettoyage

Pour éviter que des frais ne vous soient facturés, supprimez les ressources que vous avez créées dans ce tutoriel.

Supprimer l'exemple d'ensemble de données

Pour supprimer l'exemple d'ensemble de données BigQuery et toutes ses tables, utilisez la commande suivante. Cette action est irréversible.

Avertissement : Cette commande de suppression récursive ne demande pas de confirmation. Pour éviter toute perte accidentelle de données due à des variables d'environnement incorrectes, vérifiez l'ID de votre projet et le nom de votre ensemble de données avant d'exécuter la commande.

# Re-run these exports if your Cloud Shell session timed out
export PROJECT_ID=$(gcloud config get-value project)

# Manually type this command to confirm you are deleting the correct dataset
bq rm -r -f --dataset $PROJECT_ID:retail_data

Supprimer les artefacts Knowledge Catalog

1. Dans la console Google Cloud , accédez à l'onglet Types d'aspects de Knowledge Catalog sur la page Types de métadonnées.

   Accéder à "Types d'aspects"

2. Sélectionnez le type d'aspect Data Asset Context, puis cliquez sur Supprimer.

3. Dans la console Google Cloud , accédez à la page Glossaires de Knowledge Catalog.

   Accéder à Glossaires

   Remarque : Vous devez supprimer tous les termes et catégories avant de pouvoir supprimer le glossaire lui-même.

4. Sélectionnez le terme Gross Merchandise Value, puis cliquez sur Supprimer.

5. Sélectionnez la catégorie Sales Metrics, puis cliquez sur Supprimer.

6. Sélectionnez Retail Business Glossary, puis cliquez sur Supprimer.

Étapes suivantes

Pour en savoir plus sur la curation de catalogues et la création d'agents avec Knowledge Catalog, consultez les ressources suivantes :

• Gérer les aspects et enrichir les métadonnées : découvrez comment définir des schémas personnalisés et associer des métadonnées structurées dans Gérer les aspects et enrichir les métadonnées.
• Gérer les glossaires d'entreprise : découvrez comment établir un vocabulaire standardisé pour votre organisation dans Gérer un glossaire d'entreprise.
• Gouverner avec Terraform : découvrez comment provisionner des types d'aspects et des glossaires personnalisés à l'aide de Terraform.
• Utiliser des termes de glossaire à grande échelle : effectuez un enrichissement groupé des métadonnées à l'aide de fichiers JSON, comme décrit dans À propos de l'importation et de l'exportation de glossaires et de liens d'entrée.
• Enrichir les métadonnées avec des agents : créez un agent IA pour extraire le contexte et enrichir vos éléments de données dans Créer un agent pour enrichir vos métadonnées.
• Découvrir d'autres cas d'utilisation : découvrez d'autres workflows et scénarios personnalisables dans Cas d'utilisation.