Syntaxe de recherche pour Knowledge Catalog

Knowledge Catalog vous permet de découvrir, de cataloguer de manière centralisée, de gérer et de comprendre les données de votre organisation. Pour trouver efficacement des éléments de données spécifiques dans votre catalogue de données, vous pouvez utiliser des requêtes de recherche puissantes. La syntaxe des requêtes de recherche inclut les éléments suivants :

  • Recherche simple : trouver des composants de données à l'aide d'un seul terme de recherche.
  • Recherche en texte libre : permet de trouver des composants de données à l'aide d'expressions ou de mots clés en langage naturel.
  • Prédicats qualifiés : affinez votre recherche à l'aide de champs de métadonnées spécifiques tels que le nom, l'emplacement, le système ou le type.
  • Recherche d'aspects : recherche d'entrées en fonction des métadonnées métier et techniques qui leur sont associées.
  • Opérateurs logiques : combinaison de plusieurs critères de recherche à l'aide des opérateurs AND, OR ou NOT pour créer des requêtes complexes. En comprenant cette syntaxe, vous pouvez rapidement trouver les données dont vous avez besoin.

Prédicats qualifiés

Utilisez un prédicat qualifié pour affiner les résultats de recherche en demandant explicitement à la recherche d'évaluer un champ de métadonnées spécifique, tel que le nom, le type ou le système d'un composant.

Vous pouvez qualifier un prédicat en le préfixant avec une clé qui limite la correspondance à une métadonnée spécifique :

  • Le signe égal (=) permet de limiter la recherche à une correspondance exacte.
  • Le signe deux-points (:) après la clé pour faire correspondre le prédicat à une sous-chaîne ou à un jeton compris dans la valeur des résultats de recherche.

La tokenisation divise le flux de texte en une série de jetons, chaque jeton correspondant généralement à un seul mot.

Exemple :

  • name:foo sélectionne les ressources dont le nom contient la sous-chaîne foo, comme foo1 et barfoo.
  • description:foo sélectionne les ressources ayant le jeton foo dans la description, comme bar et foo.
  • location=foo correspond aux ressources d'un emplacement spécifié avec foo comme nom d'emplacement.

Qualificatifs acceptés

La recherche dans le Knowledge Catalog accepte les qualificatifs suivants :

Qualificatif Description
name:x Renvoie x en tant que sous-chaîne de l'ID ou du nom à afficher de la ressource.
displayname:x Renvoie x en tant que sous-chaîne du nom à afficher de la ressource.
column:x Correspond à x en tant que sous-chaîne du nom de la colonne (ou du nom de la colonne imbriquée) dans le schéma de la ressource.
description:x Renvoie x en tant que jeton dans la description de la ressource. Exemple :
  • description:"products" affiche toutes les ressources dont la description contient le jeton products. Par exemple, "liste des produits en stock".
  • description:"prod" n'affiche pas les ressources dont la description contient le jeton products. Il affiche plutôt toutes les ressources dont la description contient le jeton prod. Par exemple, "environnement de production".
labels:bar Renvoie les ressources comportant une étiquette (avec une certaine valeur) et dont la clé d'étiquette est bar en tant que sous-chaîne.
labels=bar Renvoie les ressources comportant une étiquette (avec une certaine valeur) et dont la clé d'étiquette est égale à bar en tant que chaîne.
labels.bar:x Renvoie x en tant que sous-chaîne dans la valeur d'une étiquette avec la clé bar associée à une ressource.
labels.foo=bar Correspond aux ressources dont la clé est égale à foo et la valeur de clé est égale à bar.
type=TYPE Correspond aux ressources d'un type d'entrée spécifique ou de son alias de type. Nécessite le qualificatif =.
projectid:bar Renvoie les ressources dans les projets Google Cloud qui correspondent àbaren tant que sous-chaîne dans l'ID.
parent:x Correspond à x en tant que sous-chaîne du chemin d'accès hiérarchique d'une ressource.
system=SYSTEM Correspond aux ressources d'un système spécifié. Nécessite le qualificatif =.
location=LOCATION

Fait correspondre les ressources d'un emplacement spécifié avec un nom exact. Nécessite le qualificatif =. Par exemple, location=us-central1 correspond aux composants hébergés dans l'Iowa.

Les composants BigQuery Omni sont compatibles avec ce qualificatif en utilisant le nom de l'emplacement BigQuery Omni. Par exemple, location=aws-us-east-1 correspond aux composants BigQuery Omni en Virginie du Nord.

createtime

Recherche les ressources qui ont été créées pendant, avant ou après une date, un code temporel ou une heure relative en jours donnés. Pour connaître les formats et les opérateurs acceptés, consultez Filtres temporels.
updatetime

Recherche les ressources qui ont été mises à jour pendant, avant ou après une date, un code temporel ou une heure relative en jours donnés. Pour connaître les formats et les opérateurs acceptés, consultez Filtres temporels.

Qualificateurs de correspondance exacte

Les clés de prédicat type, system, location et la recherche d'aspect (à l'exclusion de has) n'acceptent que le qualificatif de correspondance exacte (=), et non le qualificatif de sous-chaîne (:).

Utilisez la syntaxe d'expression exacte suivante pour ces prédicats :

Clé de prédicat Syntaxe correcte Syntaxe incorrecte
type type=table (ou type=view, type=dataset) type:table ou type:tab
system system=bigquery (ou system=spanner) system:bigquery ou system:big
location location=us-central1 (ou location=europe-west1) location:us-central1 ou location:us

Qualificatifs de sous-chaîne

Les prédicats tels que name, displayname, column, projectid et parent acceptent la correspondance de sous-chaîne avec le qualificatif deux-points (:) :

  • name:transactions correspond aux ressources dont l'ID ou le nom à afficher contiennent transactions. Par exemple, daily_transactions_raw et transactions_v2.
  • column:customer_id correspond aux ressources dont le nom de colonne contient customer_id.
  • projectid:prod correspond aux ressources des projets dont l'ID contient prod. Par exemple, finance-prod-2026.

Filtres temporels

Vous pouvez filtrer les ressources par heure de création (createtime) ou heure de la dernière mise à jour (updatetime).

Opérateurs et formats acceptés

  • Opérateurs acceptés : :, =, <, >, <=, >=, =>, =<
  • Jours relatifs (-Nd) : filtrez par un nombre relatif de jours dans le passé (par exemple, -30d, -7d, -1d).
  • Dates dans l'agenda (YYYY-MM-DD ou YYYY/MM/DD) : filtrez par date spécifique en GMT/UTC.
  • Codes temporels complets (YYYY-MM-DDTHH:MM:SS ou YYYY-MM-DDTHH:MM:SSZ) : filtrez par code temporel précis en GMT/UTC. Les codes temporels partiels, tels que YYYY-MM-DDTHH:MM ou YYYY-MM-DDTHH, sont également acceptés.

Syntaxe du filtre temporel

Le tableau suivant explique la syntaxe du filtre temporel :

Catégorie de format Syntaxe valide Syntaxe incorrecte Description
Unités de temps relatives
  • createtime>-30d (30 derniers jours)
  • createtime<=-7d (il y a sept jours ou plus)
  • updatetime=-1d (jour précédent)
  • updatetime>=-90d
  • createtime>-24h
  • createtime>-60m
  • createtime>-2w
  • createtime>30d
  • Seules les unités de jour négatives (-Nd) sont acceptées pour le temps relatif.
  • Les unités plus courtes (heures h, minutes m) et plus longues (semaines w, mois m) ne sont pas acceptées.
  • Les décalages positifs sans signe moins au début (-) ne sont pas valides.
Dates dans l'agenda
  • createtime:2025-01-15
  • createtime>2025-01-01
  • createtime<=2025-06-30
  • createtime:2025/01/15
  • createtime:2025-01
  • createtime:2025
  • createtime:15-01-2025
  • createtime:Jan-15-2025
  • createtime:01/15/2025
  • Les dates doivent être au format YYYY-MM-DD ou YYYY/MM/DD.
  • Les formats dont l'ordre des composants n'est pas standard (comme DD-MM-YYYY ou MM/DD/YYYY) ou qui contiennent des noms de mois ne sont pas valides.
Horodatages et fuseaux horaires
  • createtime:2025-01-15T05:30:00
  • createtime>2025-01-15T05:30:00Z
  • createtime:2025-01-15T05:30
  • createtime:2025-01-15T05:30:00-08:00
  • createtime:2025-01-15T05:30:00 EST
  • createtime:2025-01-15T05:30:00+05:30
  • Tous les codes temporels sont évalués en GMT/UTC.
  • Les décalages de fuseau horaire non GMT (tels que -08:00 ou +05:30) et les abréviations de fuseau horaire (telles que EST ou PST) ne sont pas acceptés.
Plages horaires
  • createtime>=2025-01-15T09:00:00 createtime<=2025-01-15T17:00:00
  • createtime:09:00:00..17:00:00
  • createtime:09:00-17:00
  • La syntaxe de la plage horaire n'est pas acceptée.
  • Utilisez plutôt des comparaisons distinctes des limites inférieure et supérieure avec des chaînes date-heure complètes.
Dates en langage naturel
  • createtime=-1d
  • createtime>-30d
  • createtime:yesterday
  • createtime:"last week"
  • createtime:today
  • Les expressions de date en langage naturel ne sont pas acceptées dans les qualificateurs createtime ni updatetime.
  • Utilisez la syntaxe des jours relatifs (-1d, -7d) ou des dates explicites.

Filtres par libellé

Utilisez le prédicat labels pour filtrer les ressources par libellés associés. Vous pouvez filtrer par clé d'étiquette, par valeur d'étiquette ou par les deux :

Schéma de requête Exemple Description
labels=KEY labels=environment Correspond aux ressources qui possèdent un libellé avec la clé exacte environment, quelle que soit sa valeur.
labels:KEY_SUBSTRING labels:tier Correspond aux ressources dont la clé d'étiquette contient tier en tant que sous-chaîne (par exemple, service_tier ou storage_tier).
labels.KEY=VALUE labels.env=prod Correspond aux ressources dont la clé de libellé est env et dont la valeur est exactement prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Renvoie les ressources dont la clé d'étiquette est owner et dont la valeur contient analytics en tant que sous-chaîne (par exemple, analytics-team ou data-analytics).
Plusieurs libellés (ET) labels.env=prod labels.data_tier=tier1 Correspond aux ressources associées aux libellés env=prod et data_tier=tier1.
Combiné avec le système et le type system=bigquery type=table labels.env=prod labels.confidentiality=high Correspond aux tables BigQuery libellées avec env=prod et confidentiality=high.

Vous pouvez utiliser la syntaxe de requête pour rechercher des entrées en fonction des aspects qui leur sont associés.

La correspondance de sous-chaîne tente de faire correspondre un nombre limité d'aspects. Si vous ne trouvez pas l'entrée à l'aide d'un fragment du chemin d'accès, utilisez le chemin d'accès complet pour affiner la recherche et augmenter le rappel.

Qualificatif Description
aspect:x
ou
has:x		 Correspond à x en tant que sous-chaîne du chemin d'accès complet au type d'aspect d'un aspect associé à l'entrée, au format projectid.location.ASPECT_TYPE_ID
aspect=x
ou
has=x		 Correspond à x en tant que chemin d'accès complet au type d'aspect d'un aspect associé à l'entrée, au format projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

Recherche des valeurs de champ d'aspect. Correspond à x en tant que sous-chaîne du chemin d'accès complet au type d'aspect et au nom de champ d'un aspect associé à l'entrée, dans les formats suivants :

  • Syntaxe pour les types d'aspect système :

    • ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME

    Par exemple, les requêtes suivantes correspondent aux entrées où la valeur du champ type dans l'aspect bigquery-dataset est default :

    • bigquery-dataset.type=default
    • dataplex-types.bigquery-dataset.type=default
    • dataplex-types.global.bigquery-dataset.type=default

  • Syntaxe pour les types d'aspects personnalisés :

    • Si l'aspect est créé dans la région "global" : PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
    • Si l'aspect est créé dans une région spécifique : PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME

    Par exemple, les requêtes suivantes correspondent aux entrées où la valeur du champ is-enrolled dans l'aspect employee-info est true.

    • example-project.us-central1.employee-info.is-enrolled=true
    • example-project.employee-info.is-enrolled=true

    La liste des opérateurs acceptés dépend du type de champ dans l'aspect, comme suit :

    • Chaîne : = (correspondance exacte)
    • Tous les types de nombres : =, :, <, >, <=, >=, =>, =<
    • Enum : =
    • Date/Heure : identique à la comparaison de nombres, mais les valeurs à comparer sont traitées comme des valeurs de date et heure au lieu de nombres.
    • Booléen : =

Seuls les champs de premier niveau de l'aspect peuvent faire l'objet d'une recherche.

Opérateurs logiques

Une requête peut combiner plusieurs prédicats à l'aide d'opérateurs logiques. Remarque : Les opérateurs logiques AND, OR et NOT sont sensibles à la casse et doivent être en majuscules.

Opérateur AND

Si vous séparez plusieurs termes de recherche ou prédicats par un espace, l'opérateur logique AND est implicite. Vous n'avez donc pas besoin de l'écrire explicitement.

Les exemples suivants montrent comment créer des requêtes avec l'opérateur AND.

  • Rechercher des tables BigQuery

    system=bigquery type=table

  • Rechercher des ressources dans le projet banking-prod avec une colonne nommée customer_id

    projectid:banking-prod column:customer_id

  • Si nécessaire, vous pouvez utiliser l'opérateur AND explicite :

    system=bigquery AND type=table AND location=us-central1

Opérateur OR

Utilisez l'opérateur OR pour faire correspondre l'une des conditions multiples. Lorsque vous combinez OR avec d'autres critères, utilisez des parenthèses ( ) pour regrouper les expressions et définir la priorité.

Les exemples suivants montrent comment créer des requêtes avec l'opérateur OR.

  • Rechercher des tables et des vues BigQuery

    system=bigquery (type=table OR type=view)

  • Rechercher des tables dans plusieurs systèmes

    (system=bigquery OR system=spanner) type=table

  • Rechercher des entrées dans des ensembles de données marketing ou financières

    system=bigquery (parent:marketing_analytics OR parent:finance_analytics)

Opérateur NOT

Vous pouvez annuler un prédicat en le préfixant avec NOT en majuscules ou un - (tiret).

Les exemples suivants montrent comment créer des requêtes avec l'opérateur NOT.

  • Rechercher tous les tableaux, à l'exception de ceux qui se trouvent dans un projet sandbox

    • Utiliser l'opérateur NOT
    type=table NOT projectid:sandbox-project
    • Utiliser un tiret
    type=table -projectid:sandbox-project

  • Recherchez toutes les ressources BigQuery dont le nom ne contient pas test

    system=bigquery -name:test

Syntaxe abrégée

Si vous souhaitez utiliser la syntaxe abrégée, utilisez | (barre verticale) pour les opérateurs OR et , (virgule) pour les opérateurs AND entre parenthèses. Cette syntaxe abrégée fonctionne pour les prédicats qualifiés.

  • Rechercher dans plusieurs ID de projet

    • Utilisez l'opérateur OR :
    projectid:(finance-prod|sales-prod|analytics-prod)
    • Utilisez des parenthèses :
    projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

  • Rechercher des entrées correspondant à plusieurs noms de colonnes (AND)

    column:(customer_id,transaction_date,amount)

  • Rechercher des entrées correspondant à plusieurs noms de colonnes (OR)

    column:(customer_id|user_id|client_id)

Règlement sur les caractères génériques

La syntaxe de recherche de Knowledge Catalog n'est pas compatible avec les caractères génériques, tels que * ou ?, dans les chaînes de requête ou les prédicats.

Si vous incluez un astérisque (*) ou un point d'interrogation (?) dans une requête, ils sont traités comme des caractères littéraux plutôt que comme des caractères génériques de correspondance de modèle.

Par exemple, pour rechercher les tables dont le nom se termine par _masked :

  • Accepté : name:_masked : utilise le qualificatif de correspondance de sous-chaîne : pour trouver toutes les ressources dont le nom contient _masked, comme customer_records_masked ou transactions_masked.
  • Non compatible : name:*_masked : le * est traité comme un caractère littéral, et non comme un caractère générique de modèle.

Parenthèses

Les parenthèses dans les requêtes de recherche ont des fonctions techniques spécifiques. Si vous utilisez trop de parenthèses ou si vous les appliquez à des requêtes en langage naturel, vous risquez de perturber l'analyseur de recherche et de dégrader la qualité des résultats.

Langage naturel simple

Lorsque vous posez une question sur une entreprise, transmettez la requête en texte brut. Ne l'entourez pas de parenthèses. Par exemple, écrivez :

Find customer orders containing email addresses

Syntaxe abrégée des prédicats

Les parenthèses sont très efficaces lorsqu'elles sont utilisées avec des clés de prédicat pour lister plusieurs conditions OR et AND dans un format compact.

  • Regrouper les clés de prédicat avec OR (|)

    • Recherchez les entrées résidant dans l'un des projets listés à l'aide de (|).

      projectid:(finance-prod|finance-test|analytics-raw)

    • Recherchez les entrées résidant dans l'un des projets listés à l'aide de (OR).

    projectid:finance-prod OR projectid:finance-test OR projectid:finance-raw

  • Regrouper les clés de prédicat avec AND (,)

    • Recherchez les entrées contenant toutes les colonnes spécifiées à l'aide de (,).
    column:(customer_id, order_date, total_amount)
    • Recherchez les entrées contenant toutes les colonnes spécifiées à l'aide de (AND).
    column:customer_id AND column:order_date AND column:total_amount

Vous pouvez combiner une requête en langage naturel avec des filtres compacts.

Par exemple, pour trouver les tables spécifiant les utilisateurs actifs par mois, mais limiter la recherche aux projets spécifiés, utilisez la requête suivante :

monthly active users type=table projectid:(data-warehouse|analytical-tier)

Bonnes pratiques pour l'utilisation des parenthèses

  • N'encadrez pas la question entière de parenthèses, car le moteur sémantique pourrait les traiter comme des caractères littéraux, ce qui entraînerait des résultats peu pertinents.

    • Incorrect : (Show me datasets about US population by state)
    • Correct : Show me datasets about US population by state

  • Évitez de combiner des arbres booléens complexes et imbriqués avec des parenthèses dans le champ en langage naturel. La recherche est optimisée pour l'intention en langage naturel. Si vous compliquez trop la requête avec des parenthèses et des blocs logiques explicites, vous risquez de dérouter l'analyseur.

    • Incorrect : (revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
    • Correct : revenue data system=bigquery projectid:(data-warehouse|analytical-tier)

  • N'ajoutez pas d'espaces de manière arbitraire, sauf s'ils font partie de la valeur.

    • Incorrect : column:( email | id )
    • Correct : column:(email|id).

Étapes suivantes