Syntaxe de recherche pour Knowledge Catalog

Les requêtes de recherche dans Knowledge Catalog vous permettent de trouver des éléments de données spécifiques dans votre catalogue à l'aide de la correspondance sémantique et de la correspondance des mots clés. En combinant le langage naturel, les filtres de métadonnées et les opérateurs logiques, vous pouvez localiser les entrées pertinentes pour découvrir, gérer et comprendre les données de votre organisation.

Knowledge Catalog est également compatible avec un mode de recherche par mots clés uniquement pour assurer la rétrocompatibilité. Pour en savoir plus sur ce mode, ses filtres et son utilisation, consultez Recherche par mots clés uniquement.

Présentation de la syntaxe des requêtes

Vous pouvez créer des requêtes de recherche Knowledge Catalog à l'aide des composants suivants :

  • Recherche simple : recherchez des éléments de données à l'aide d'un seul terme de recherche.
  • Recherche en texte libre : recherchez des éléments 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 : recherchez des entrées en fonction des métadonnées métier et techniques qui leur sont associées.
  • Opérateurs logiques : combinez plusieurs critères de recherche à l'aide des opérateurs AND, OR ou NOT pour créer des requêtes complexes.

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 qu'un nom, un type ou un système d'asset.

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

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

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

Exemple :

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

Qualificatifs acceptés

La recherche Knowledge Catalog est compatible avec les qualificatifs suivants :

Qualificatif Description
name:x Correspond à x en tant que sous-chaîne de l'ID de ressource ou du nom à afficher de la ressource.
displayname:x Correspond à 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 Correspond à 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. Au lieu de cela, elle affiche toutes les ressources dont la description contient le jeton prod. Par exemple, "environnement de production".
labels:bar Correspond aux ressources qui ont un libellé (avec une certaine valeur) et dont la clé de libellé contient bar en tant que sous-chaîne.
labels=bar Correspond aux ressources qui ont un libellé (avec une certaine valeur) et dont la clé de libellé est égale à bar sous forme de chaîne.
labels.bar:x Correspond à 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 dont 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 Correspond aux ressources des projets Google Cloud qui correspondent à bar en tant que sous-chaîne dans l'ID.
parent:x Correspond à x en tant que sous-chaîne du chemin hiérarchique d'une ressource.
system=SYSTEM Correspond aux ressources d'un système spécifié. Nécessite le qualificatif =.
location=LOCATION

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

Les éléments 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 éléments BigQuery Omni situés en Virginie du Nord.

createtime

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

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

Qualificatifs de correspondance exacte

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

Utilisez la syntaxe de correspondance 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 sont compatibles avec la correspondance de sous-chaîne avec le qualificatif deux-points (:) :

  • name:transactions correspond aux ressources dont l'ID ou le nom à afficher contient 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 par heure de dernière mise à jour (updatetime).

Opérateurs et formats compatibles

  • Opérateurs compatibles : :, =, <, >, <=, >=, =>, =<
  • 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 au format GMT/UTC.
  • Horodatages complets (YYYY-MM-DDTHH:MM:SS ou YYYY-MM-DDTHH:MM:SSZ) : filtrez par horodatage précis au format 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 non valide Description
Unités de temps relatives
  • createtime>-30d (30 derniers jours)
  • createtime<=-7d (il y a 7 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 l'heure relative.
  • 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 (-) 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 respecter le 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 les 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 (comme -08:00 ou +05:30) et les abréviations de fuseau horaire (comme 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 plage horaire n'est pas acceptée.
  • Utilisez plutôt des comparaisons de limites inférieure et supérieure distinctes avec des chaînes de date et d'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 qualificatifs createtime ou updatetime.
  • Utilisez la syntaxe de jour relative (-1d, -7d) ou des dates explicites.

Filtres par libellé

Utilisez le prédicat labels pour filtrer les ressources en fonction des étiquettes associées. Vous pouvez filtrer par clé de libellé, par valeur de libellé ou par les deux :

Schéma de requête Exemple Description
labels=KEY labels=environment Correspond aux ressources qui ont une étiquette 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é d'étiquette est env et dont la valeur est exactement prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Correspond aux 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 auxquelles les libellés env=prod et data_tier=tier1 sont associés.
Combiné avec le système et le type system=bigquery type=table labels.env=prod labels.confidentiality=high Correspond aux tables BigQuery associées aux libellés 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 des types d'aspects 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 des types d'aspects personnalisés :

    • Si l'aspect est créé dans la région globale : 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 compatibles dépend du type de champ de l'aspect, comme suit :

    • Chaîne : = (mot clé exact)
    • Tous les types de nombres : =, :, <, >, <=, >=, =>, =<
    • Enum : =
    • Date et heure : identique à la comparaison de nombres, mais les valeurs à comparer sont traitées comme des dates et heures 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. 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 financiers

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

Opérateur NOT

Vous pouvez annuler un prédicat en le faisant précéder de NOT en majuscules ou d'un - (tiret).

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

  • Rechercher toutes les tables, sauf celles d'un projet de bac à sable

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

  • Rechercher 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 à l'un des noms de colonnes (OR)

    column:(customer_id|user_id|client_id)

Règle de caractère générique

La syntaxe de recherche de Knowledge Catalog n'accepte pas 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, il est traité comme un caractère littéral plutôt que comme un caractère générique de correspondance de modèle.

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

  • Compatible : name:_masked : utilise le qualificatif de correspondance de sous-chaîne : pour rechercher toutes les ressources dont le nom contient _masked, par exemple customer_records_masked ou transactions_masked.
  • Non compatible : name:*_masked : * 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 d'ordre commercial, 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 rechercher des 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'entourez pas l'intégralité de la question 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 mélanger des arbres booléens complexes et imbriqués avec des parenthèses dans le champ de 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, l'analyseur risque de ne pas la comprendre.

    • 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 arbitrairement, sauf s'ils font partie de la valeur.

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

Étapes suivantes