Rechercher et afficher des éléments de données avec Data Catalog

Ce document explique comment utiliser Data Catalog pour rechercher des éléments de données, par exemple :

Ensembles de données associés à Analytics Hub
Ensembles de données, tables, vues et modèles BigQuery
Instances, clusters et tables Bigtable (y compris les détails des familles de colonnes)
Modèles de tags, groupes d'entrées et entrées personnalisées Data Catalog
Lacs, zones, tables et ensembles de fichiers Dataplex
Les services, bases de données et tables Dataproc Metastore
Flux de données Pub/Sub
Instances, bases de données, tables et vues Spanner
Modèles, ensembles de données et ressources Vertex AI Feature Store
Éléments des silos de données d'entreprise connectés à Data Catalog

Portée de la recherche

Les résultats de recherche peuvent varier en fonction des autorisations dont vous disposez. Les résultats de recherche dans Data Catalog sont limités en fonction de votre rôle.

Vous pouvez consulter les différents types de rôles et autorisations IAM disponibles pour Data Catalog.

Par exemple, si vous disposez d'un accès en lecture aux métadonnées BigQuery pour un objet, celui-ci apparaît dans vos résultats de recherche Data Catalog. La liste suivante décrit les autorisations minimales requises:

Pour rechercher une table, vous devez disposer de l'autorisation bigquery.tables.get pour cette table.
Pour rechercher un ensemble de données, vous devez disposer de l'autorisation bigquery.datasets.get pour cet ensemble de données.
Pour rechercher des métadonnées pour un ensemble de données ou une table, vous devez disposer du rôle roles/bigquery.metadataViewer.
Pour rechercher toutes les ressources d'un projet ou d'une organisation, vous devez disposer de l'autorisation datacatalog.catalogs.searchAll. Il fonctionne pour toutes les ressources, indépendamment du système source.

Si vous avez accès à une table BigQuery, mais pas à l'ensemble de données qui la contient, la table s'affiche toujours comme prévu dans la recherche Data Catalog. La même logique d'accès s'applique à tous les systèmes compatibles tels que Pub/Sub et Data Catalog.

Rappeler les problèmes dans la recherche

Les requêtes de recherche Data Catalog ne garantissent pas un rappel complet. Les résultats correspondant à votre requête peuvent ne pas être renvoyés, même sur les pages de résultats suivantes. En outre, les résultats renvoyés (et non renvoyés) peuvent varier si vous répétez des requêtes de recherche.

Si vous rencontrez des problèmes de rappel et que vous n'avez pas besoin d'extraire les résultats dans un ordre spécifique, envisagez de définir le paramètre orderBy sur default lorsque vous appelez la méthode catalog.search.

L'utilisation de l'indicateur admin_search sur la requête de recherche garantit un rappel complet. La recherche d'administrateurs nécessite que l'autorisation datacatalog.catalogs.searchAll soit définie sur tous les projets et toutes les organisations inclus dans le champ d'application de la recherche. Lorsque vous utilisez admin_search, seul default orderBy est autorisé.

Tables segmentées par date

Data Catalog agrège les tables segmentées par date en une seule entrée logique. Cette entrée possède le même schéma que le segment de table avec la date la plus récente, et contient des informations agrégées sur le nombre total de segments. L'entrée dérive son niveau d'accès de l'ensemble de données auquel il appartient. La recherche Data Catalog n'affiche ces entrées logiques que si l'utilisateur a accès à l'ensemble de données qui les contient. Les tables segmentées par date individuelles ne sont pas visibles dans la recherche dans Data Catalog, même si elles sont présentes dans Data Catalog et peuvent être taguées.

Filtres

Les filtres vous permettent d'affiner les résultats de recherche. Tous les filtres sont regroupés en sections :

Portée pour limiter la recherche aux éléments favoris uniquement
Des systèmes tels que BigQuery, Pub/Sub, Dataplex, Dataproc Metastore, les systèmes personnalisés, Vertex AI et Data Catalog. Le système Data Catalog contient des ensembles de fichiers et des entrées personnalisées.
Les lacs et les zones proviennent de Dataplex.
Types de données tels que les flux de données, les ensembles de données, les lacs, les zones, les ensembles de fichiers, les modèles, les tables, les vues, les services, les bases de données et les types personnalisés.
L'onglet Projets répertorie tous les projets disponibles.
L'onglet Balises liste tous les modèles de balises (et leurs champs individuels) à votre disposition.
Les ensembles de données proviennent de BigQuery et de Vertex AI.
Les ensembles de données publics sont des données publiques provenant de BigQuery.

Vous pouvez combiner des filtres de plusieurs sections pour trouver des éléments qui correspondent à au moins une condition de chaque section sélectionnée. Plusieurs filtres sélectionnés dans une même section sont évalués à l'aide de l'opérateur logique "OR". Par exemple, avec la combinaison de filtres suivante:

Data Catalog recherche les éléments suivants:

Ensembles de données BigQuery tagués avec le modèle MyTemplate1.
Ensembles de données BigQuery tagués avec le modèle MyTemplate2.
Tables BigQuery taguées avec le modèle MyTemplate1.
Tables BigQuery taguées avec le modèle MyTemplate2.

Filtrer par valeur de tag

Les filtres Tags vous permettent de rechercher des éléments tagués à l'aide d'un modèle spécifique. Vous pouvez utiliser le menu Personnaliser pour affiner les résultats et filtrer par valeurs de balise spécifiques. Les conditions de filtre de valeur de tag dépendent du type de données du champ de tag. Par exemple, pour les champs de type "Date/Heure" et de nombre, vous pouvez spécifier une date ou une plage spécifique.

Visibilité des filtres

Les filtres affichés dans chaque section dépendent de la requête actuelle dans le champ de recherche. L'ensemble des résultats de recherche peut inclure des entrées qui correspondent à la requête actuelle, mais les filtres correspondants peuvent ne pas s'afficher dans le panneau Filtres.

Rechercher des éléments de données

Console

Pour lancer une requête de recherche Dataplex dans la console Google Cloud, accédez à la page Recherche Dataplex.

Accéder à page de "Recherche" de Dataplex
Dans le champ de recherche, saisissez votre requête ou utilisez le panneau Filtres pour affiner les paramètres de recherche.

Vous pouvez ajouter manuellement les filtres suivants :

Pour ajouter un filtre de projet, dans Projets, cliquez sur le bouton AJOUTER UN PROJET, recherchez un projet spécifique, sélectionnez-le, puis cliquez sur OUVRIR.
Dans Balises, un filtre de modèle de tag vous est proposé. Pour ce faire, cliquez sur la liste déroulante Ajouter des modèles de tag, recherchez un modèle spécifique, sélectionnez-le, puis cliquez sur OK.

Vous pouvez en outre effectuer l'opération suivante :

Cochez la case Inclure des ensembles de données publics pour rechercher des éléments de données disponibles publiquement dans Google Cloud en plus des éléments disponibles.

Exemple de recherche

Par exemple, pour rechercher la table trips que vous avez configurée dans Configurer les modèles de balise, les balises, les présentations et les responsables des données:

Saisissez trips dans le champ de recherche, puis cliquez sur Rechercher.
Sélectionnez BigQuery dans la section Systems (Systèmes) pour exclure les éléments de données portant le même nom qui appartiennent à d'autres systèmes.
Sélectionnez l'ID de votre projet dans la section Projets pour exclure des éléments de données d'autres projets. Si votre projet ne s'affiche pas dans la section, cliquez sur AJOUTER UN PROJET et sélectionnez-le dans la boîte de dialogue.
Sélectionnez Modèle de tag de démonstration dans la section Modèles de tag pour voir si une balise qui utilise ce modèle est associée à la table trips. Si ce modèle ne s'affiche pas dans la section, cliquez sur le menu déroulant Ajouter des balises, recherchez-le et sélectionnez-le, puis cliquez sur OK.

Avec tous les filtres sélectionnés, les résultats de la recherche ne contiennent qu'une seule entrée : la table BigQuery trips de votre projet avec un tag associé qui utilise Demo Tag Template.

Vous pouvez également effectuer les opérations suivantes :

Filtrez votre recherche en ajoutant keyword:value à vos termes de recherche dans le champ de recherche:

Mot clé	Description
`name:`	Correspond au nom de l'élément de données
`column:`	Correspond au nom de la colonne ou de la colonne imbriquée
`description:`	Correspond à la description du tableau

Effectuez une recherche par tag en ajoutant l'un des préfixes de mot clé de tag suivants à vos termes de recherche dans le champ de recherche:

Tag	Description
`tag:project-name.tag_template_name`	Correspond au nom du tag
`tag:project-name.tag_template_name.key`	Correspond à la clé du tag
`tag:project-name.tag_template_name.key:value`	Correspond à la paire `key:string value` du tag

Conseils pour les expressions de recherche

Placez votre expression de recherche entre guillemets ("search terms") si elle contient des espaces.
Vous pouvez faire précéder un mot clé de "NOT" (obligatoirement en MAJUSCULES) pour correspondre à la négation logique du filtre keyword:term. Vous pouvez également utiliser les opérateurs booléens "AND" et "OR" (obligatoirement en MAJUSCULES) pour combiner des expressions de recherche.

Par exemple:NOT column:term répertorie toutes les colonnes, à l'exception de celles qui correspondent au terme spécifié. Pour obtenir la liste des mots clés et d'autres termes que vous pouvez utiliser dans une expression de recherche Data Catalog, consultez la page Syntaxe de recherche Data Catalog.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration de Java dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Java.

Pour vous authentifier auprès de Data Catalog, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.DataCatalogClient.SearchCatalogPagedResponse;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest.Scope;
import com.google.cloud.datacatalog.v1.SearchCatalogResult;
import java.io.IOException;

// Sample to search catalog
public class SearchAssets {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String query = "type=dataset";
    searchCatalog(projectId, query);
  }

  public static void searchCatalog(String projectId, String query) throws IOException {
    // Create a scope object setting search boundaries to the given organization.
    // Scope scope = Scope.newBuilder().addIncludeOrgIds(orgId).build();

    // Alternatively, search using project scopes.
    Scope scope = Scope.newBuilder().addIncludeProjectIds(projectId).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Search the catalog.
      SearchCatalogRequest searchCatalogRequest =
          SearchCatalogRequest.newBuilder().setScope(scope).setQuery(query).build();
      SearchCatalogPagedResponse response = dataCatalogClient.searchCatalog(searchCatalogRequest);

      System.out.println("Search results:");
      for (SearchCatalogResult result : response.iterateAll()) {
        System.out.println(result);
      }
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Node.js.

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function searchAssets() {
  // Search data assets.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project'; // Google Cloud Platform project

  // Set custom query.
  const query = 'type=lake';

  // Create request.
  const scope = {
    includeProjectIds: [projectId],
    // Alternatively, search using Google Cloud Organization scopes.
    // includeOrgIds: [organizationId],
  };

  const request = {
    scope: scope,
    query: query,
  };

  const [result] = await datacatalog.searchCatalog(request);

  console.log(`Found ${result.length} datasets in project ${projectId}.`);
  console.log('Datasets:');
  result.forEach(dataset => {
    console.log(dataset.relativeResourceName);
  });
}
searchAssets();

Python

Avant d'essayer cet exemple, suivez les instructions de configuration de Python dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Python.

from google.cloud import datacatalog_v1

datacatalog = datacatalog_v1.DataCatalogClient()

# TODO: Set these values before running the sample.
project_id = "project_id"

# Set custom query.
search_string = "type=dataset"
scope = datacatalog_v1.types.SearchCatalogRequest.Scope()
scope.include_project_ids.append(project_id)

# Alternatively, search using organization scopes.
# scope.include_org_ids.append("my_organization_id")

search_results = datacatalog.search_catalog(scope=scope, query=search_string)

print("Results in project:")
for result in search_results:
    print(result)

API REST et ligne de commande

REST

Si vous n'avez pas accès aux bibliothèques clientes cloud pour votre langage ou si vous souhaitez tester l'API à l'aide de requêtes REST, consultez les exemples suivants et la documentation API REST de Data Catalog.

1. Rechercher dans le catalogue

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

organization-id: ID de l'organisation GCP
project-id : ID du projet GCP

Méthode HTTP et URL :

POST https://datacatalog.googleapis.com/v1/catalog:search

Corps JSON de la requête :

{
  "query":"trips",
  "scope":{
    "includeOrgIds":[
      "organization-id"
    ]
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter gcloud auth list pour vérifier le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: project-id" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://datacatalog.googleapis.com/v1/catalog:search"

PowerShell (Windows)

Enregistrez le corps de la requête dans un fichier nommé request.json et exécutez la commande suivante:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/catalog:search" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "results":[
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
"relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry1-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/taxi_trips"
    },
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
      "relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry2-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/tlc_yellow_trips_2018"
    }
  ]
}

Afficher les détails de la table

Dans la console Cloud, vous pouvez utiliser Data Catalog pour afficher les détails de la table.

Accédez à la page de recherche de Dataplex.

Accéder à Data Catalog
Dans le champ de recherche, saisissez le nom d'un ensemble de données contenant une table.

Par exemple, si vous avez suivi le guide de démarrage rapide, vous pouvez rechercher demo-dataset et sélectionner la table trips.
Cliquez sur le tableau.

La page Détails de la table BigQuery s'ouvre.

Les détails du tableau comprennent les sections suivantes:

Détails de la table BigQuery. Elles incluent des informations telles que l'heure de création, l'heure de la dernière modification, l'heure d'expiration, les URL des ressources, les libellés, etc.
Tags : Répertorie les balises appliquées.Vous pouvez modifier les balises à partir de cette page et afficher le modèle de tag. Cliquez sur l'icône Actions.
Tags de colonne et de schéma. Répertorie le schéma appliqué et ses valeurs.

Ajoutez vos entrées préférées à vos favoris et recherchez-les

Si vous parcourez fréquemment les mêmes éléments de données, vous pouvez inclure leurs entrées dans une liste personnalisée en les marquant avec des étoiles. Pour ce faire, procédez comme suit dans l'interface utilisateur de Dataplex:

Accédez à la page de recherche Dataplex et recherchez votre asset.

Accéder à Data Catalog
Activez le suivi de l'entrée de l'une des deux manières suivantes:
- Cliquez sur l'icône à côté de l'entrée dans les résultats de recherche.
- Cliquez sur le nom de l'entrée pour ouvrir sa page d'informations, puis sur le bouton AJOUTER AUX FAVORIS sur la barre d'action en haut.

Vous pouvez ajouter jusqu'à 200 entrées aux favoris.

Les entrées suivies apparaissent dans la liste Entrées suivies sur la page de recherche avant que vous ne saisissiez une requête dans la barre de recherche. Cette liste n'est visible que par vous.

Pour rechercher uniquement les entrées ajoutées aux favoris, sélectionnez l'option Champ d'application > Suivis dans le panneau Filtres.

Vous pouvez également utiliser les méthodes correspondantes de l'API Data Catalog pour activer ou désactiver le suivi d'entrées. Lorsque vous recherchez des éléments, utilisez le paramètre starredOnly dans l'objet scope. Consultez la méthode catalogue.search.