Sintassi di ricerca per Knowledge Catalog

Le query di ricerca in Knowledge Catalog ti consentono di trovare asset di dati specifici nel tuo catalogo utilizzando la corrispondenza semantica e delle parole chiave. Combinando il linguaggio naturale, i filtri dei metadati e gli operatori logici, puoi individuare le voci pertinenti per scoprire, gestire e comprendere i dati della tua organizzazione.

Knowledge Catalog supporta anche una modalità di ricerca solo per parole chiave per la compatibilità con le versioni precedenti. Per saperne di più su questa modalità, sui relativi filtri e su come utilizzarla, consulta Ricerca solo per parole chiave.

Panoramica della sintassi delle query

Puoi creare query di ricerca di Knowledge Catalog utilizzando i seguenti componenti:

  • Ricerca semplice: trova gli asset di dati utilizzando un singolo termine di ricerca.
  • Ricerca testuale: trova gli asset di dati utilizzando frasi o parole chiave in linguaggio naturale.
  • Predicati qualificati: perfeziona la ricerca utilizzando campi di metadati specifici, come nome, località, sistema o tipo.
  • Ricerca per aspetto: cerca le voci in base ai metadati aziendali e tecnici allegati.
  • Operatori logici: combina più criteri di ricerca utilizzando gli operatori AND, OR o NOT per creare query complesse.

Predicati qualificati

Utilizza un predicato qualificato per restringere i risultati di ricerca indicando esplicitamente alla ricerca di valutare un campo di metadati specifico, ad esempio il nome, il tipo o il sistema di un asset.

Puoi qualificare un predicato aggiungendo un prefisso con una chiave che limita la corrispondenza a un metadato specifico:

  • Un segno di uguale (=) per limitare la ricerca a una corrispondenza esatta.
  • I due punti (:) dopo la chiave per far corrispondere il predicato a una sottostringa o a un token all'interno del valore nei risultati di ricerca.

La tokenizzazione suddivide il flusso di testo in una serie di token, ognuno dei quali di solito corrisponde a una singola parola.

Ad esempio:

  • name:foo seleziona le risorse con nomi che contengono la sottostringa foo, ad esempio foo1 e barfoo.
  • description:foo seleziona le risorse con il token foo nella descrizione, ad esempio bar e foo.
  • location=foo corrisponde alle risorse in una località specificata con foo come nome della località.

Qualificatori supportati

La ricerca Knowledge Catalog supporta i seguenti qualificatori:

Qualificatore Descrizione
name:x Corrisponde a x come sottostringa dell'ID risorsa o del nome visualizzato della risorsa.
displayname:x Trova x come sottostringa del nome visualizzato della risorsa.
column:x Corrisponde a x come sottostringa del nome della colonna (o del nome della colonna nidificata) nello schema della risorsa.
description:x Corrisponde a x come token nella descrizione della risorsa. Ad esempio:
  • description:"products" mostra tutte le risorse che contengono il token products nella descrizione. Ad esempio, "elenco dei prodotti nell'inventario".
  • description:"prod" non mostra le risorse che hanno il token products nella descrizione. Mostra invece tutte le risorse che contengono il token prod nella descrizione. Ad esempio, "ambiente di produzione".
labels:bar Trova le risorse che hanno un'etichetta (con un valore) e la chiave dell'etichetta ha bar come sottostringa.
labels=bar Trova le risorse che hanno un'etichetta (con un valore) e la chiave dell'etichetta è uguale a bar come stringa.
labels.bar:x Corrisponde a x come sottostringa nel valore di un'etichetta con chiave bar collegata a una risorsa.
labels.foo=bar Trova le risorse in cui la chiave è uguale a foo e il valore della chiave è uguale a bar.
type=TYPE Trova le risorse di un tipo di voce specifico o del relativo alias di tipo. Richiede il qualificatore =.
projectid:bar Trova le risorse all'interno dei progetti Google Cloud che corrispondono abarcome sottostringa nell'ID.
parent:x Corrisponde a x come sottostringa del percorso gerarchico di una risorsa.
system=SYSTEM Trova le risorse di un sistema specificato. Richiede il qualificatore =.
location=LOCATION

Trova le risorse in una località specificata con un nome esatto. Richiede il qualificatore =. Ad esempio, location=us-central1 corrisponde agli asset ospitati in Iowa.

Gli asset BigQuery Omni supportano questo qualificatore utilizzando il nome della località BigQuery Omni. Ad esempio, location=aws-us-east-1 corrisponde agli asset BigQuery Omni in Virginia settentrionale.

createtime

Trova le risorse create entro, prima o dopo una determinata data, un timestamp o un tempo relativo in giorni. Per i formati e gli operatori supportati, consulta Filtri temporali.
updatetime

Trova le risorse aggiornate entro, prima o dopo una determinata data, un timestamp o un tempo relativo in giorni. Per i formati e gli operatori supportati, consulta Filtri temporali.

Qualificatori di corrispondenza esatta

Le chiavi del predicato type, system, location e la ricerca per aspetto (escluso has) supportano solo il qualificatore di corrispondenza esatta (=), non il qualificatore di sottostringa (:).

Utilizza la seguente sintassi di corrispondenza esatta per questi predicati:

Chiave del predicato Sintassi corretta Sintassi errata
type type=table (o type=view, type=dataset) type:table o type:tab
system system=bigquery (o system=spanner) system:bigquery o system:big
location location=us-central1 (o location=europe-west1) location:us-central1 o location:us

Qualificatori di sottostringhe

I predicati come name, displayname, column, projectid e parent supportano la corrispondenza delle sottostringhe con il qualificatore dei due punti (:):

  • name:transactions corrisponde alle risorse il cui ID o nome visualizzato contiene transactions. Ad esempio, daily_transactions_raw e transactions_v2.
  • column:customer_id corrisponde alle risorse con un nome di colonna contenente customer_id.
  • projectid:prod corrisponde alle risorse nei progetti il cui ID contiene prod. Ad esempio: finance-prod-2026.

Filtri data/ora

Puoi filtrare le risorse in base alla data e ora di creazione (createtime) o alla data e ora dell'ultimo aggiornamento (updatetime).

Operatori e formati supportati

  • Operatori supportati: :, =, <, >, <=, >=, =>, =<
  • Giorni relativi (-Nd): filtra in base a un numero relativo di giorni nel passato (ad esempio -30d, -7d, -1d).
  • Date di calendario (YYYY-MM-DD o YYYY/MM/DD): filtra in base a una data specifica in GMT/UTC.
  • Timestamp completi (YYYY-MM-DDTHH:MM:SS o YYYY-MM-DDTHH:MM:SSZ): filtra in base a un timestamp preciso in GMT/UTC. Sono supportati anche i timestamp parziali, come YYYY-MM-DDTHH:MM o YYYY-MM-DDTHH.

Sintassi del filtro temporale

La tabella seguente illustra la sintassi del filtro temporale:

Categoria di formati Sintassi valida Sintassi non valida Descrizione
Unità di tempo relative
  • createtime>-30d (ultimi 30 giorni)
  • createtime<=-7d (7 giorni fa o prima)
  • updatetime=-1d (giorno precedente)
  • updatetime>=-90d
  • createtime>-24h
  • createtime>-60m
  • createtime>-2w
  • createtime>30d
  • Per il tempo relativo sono supportate solo unità di giorni negative (-Nd).
  • Le unità più brevi (ore h, minuti m) e quelle più lunghe (settimane w, mesi m) non sono supportate.
  • Gli offset positivi senza un segno meno iniziale (-) non sono validi.
Date del calendario
  • 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
  • Le date devono essere nel formato YYYY-MM-DD o YYYY/MM/DD.
  • I formati con un ordine dei componenti non standard (ad esempio DD-MM-YYYY o MM/DD/YYYY) o con i nomi dei mesi non sono validi.
Timestamp e fusi orari
  • 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
  • Tutti i timestamp vengono valutati in GMT/UTC.
  • Gli scostamenti del fuso orario non GMT (ad esempio -08:00 o +05:30) e le abbreviazioni del fuso orario (ad esempio EST o PST) non sono supportati.
Intervalli di ora del giorno
  • 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 sintassi dell'intervallo di ora del giorno non è supportata.
  • Utilizza invece confronti separati dei limiti inferiore e superiore con stringhe di data e ora complete.
Date in linguaggio naturale
  • createtime=-1d
  • createtime>-30d
  • createtime:yesterday
  • createtime:"last week"
  • createtime:today
  • Le frasi di date in linguaggio naturale non sono supportate nei qualificatori createtime o updatetime.
  • Utilizza la sintassi dei giorni relativi (-1d, -7d) o date esplicite.

Filtri per etichetta

Utilizza il predicato labels per filtrare le risorse in base alle etichette associate. Puoi filtrare per chiave etichetta, valore etichetta o entrambi:

Pattern di query Esempio Descrizione
labels=KEY labels=environment Trova le risorse che hanno un'etichetta con la chiave esatta environment, indipendentemente dal suo valore.
labels:KEY_SUBSTRING labels:tier Trova le risorse con una chiave di etichetta contenente tier come sottostringa (ad esempio service_tier o storage_tier).
labels.KEY=VALUE labels.env=prod Trova le risorse in cui la chiave dell'etichetta è env e il suo valore è esattamente prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Trova le risorse con la chiave di etichetta owner in cui il valore contiene analytics come sottostringa (ad esempio analytics-team o data-analytics).
Più etichette (AND) labels.env=prod labels.data_tier=tier1 Trova le risorse a cui sono associate entrambe le etichette env=prod e data_tier=tier1.
In combinazione con il sistema e il tipo system=bigquery type=table labels.env=prod labels.confidentiality=high Corrisponde alle tabelle BigQuery etichettate con env=prod e confidentiality=high.

Puoi utilizzare la sintassi delle query per cercare le voci in base agli aspetti allegati.

La corrispondenza della sottostringa tenta di trovare una corrispondenza con un numero limitato di aspetti. Se non riesci a trovare la voce utilizzando un frammento del percorso, utilizza il percorso completo per restringere la ricerca e aumentare il richiamo.

Qualificatore Descrizione
aspect:x
o
has:x		 Corrisponde a x come sottostringa del percorso completo del tipo di aspetto di un aspetto collegato alla voce, nel formato projectid.location.ASPECT_TYPE_ID
aspect=x
o
has=x		 Corrisponde a x come percorso completo del tipo di aspetto di un aspetto collegato alla voce, nel formato projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

Cerca i valori dei campi di aspetto. Corrisponde a x come sottostringa del percorso completo del tipo di aspetto e del nome del campo di un aspetto collegato alla voce, nei seguenti formati:

  • Sintassi per i tipi di aspetto di sistema:

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

    Ad esempio, le seguenti query corrispondono alle voci in cui il valore del campo type nell'aspetto bigquery-dataset è default:

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

  • Sintassi per i tipi di aspetto personalizzati:

    • Se l'aspetto viene creato nella regione globale: PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
    • Se l'aspetto viene creato in una regione specifica: PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME

    Ad esempio, le seguenti query corrispondono alle voci in cui il valore del campo is-enrolled nell'aspetto employee-info è true.

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

    L'elenco degli operatori supportati dipende dal tipo di campo nell'aspetto, come segue:

    • Stringa: = (corrispondenza esatta)
    • Tutti i tipi di numeri: =, :, <, >, <=, >=, =>, =<
    • Enum: =
    • Data e ora: come per i numeri, ma i valori da confrontare vengono trattati come date e ore anziché come numeri
    • Boolean: =

Solo i campi di primo livello dell'aspetto sono ricercabili.

Operatori logici

Una query può combinare più predicati utilizzando operatori logici. Nota: gli operatori logici AND, OR e NOT sono sensibili alle maiuscole e devono essere scritti in lettere maiuscole.

Operatore AND

Se separi più termini di ricerca o predicati con uno spazio, viene applicato l'operatore logico AND, il che significa che non devi scriverlo esplicitamente.

Gli esempi seguenti mostrano come creare query con l'operatore AND.

  • Cerca tabelle BigQuery

    system=bigquery type=table

  • Cerca risorse nel progetto banking-prod con una colonna denominata customer_id

    projectid:banking-prod column:customer_id

  • Se necessario, puoi utilizzare l'operatore esplicito AND:

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

Operatore OR

Utilizza l'operatore OR per trovare una corrispondenza con una qualsiasi delle condizioni. Quando combini OR con altri criteri, utilizza le parentesi ( ) per raggruppare le espressioni e definire la precedenza.

Gli esempi seguenti mostrano come creare query con l'operatore OR.

  • Cerca tabelle e viste BigQuery

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

  • Cerca tabelle in più sistemi

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

  • Cerca voci nei set di dati di marketing o finanziari

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

Operatore NOT

Puoi negare un predicato anteponendo NOT in maiuscolo o un - (trattino).

Gli esempi seguenti mostrano come creare query con l'operatore NOT.

  • Trova tutte le tabelle, ad eccezione di quelle in un progetto sandbox

    • Utilizza l'operatore NOT
    type=table NOT projectid:sandbox-project
    • Usa il trattino
    type=table -projectid:sandbox-project

  • Trova tutte le risorse BigQuery che non contengono test nel nome

    system=bigquery -name:test

Sintassi abbreviata

Se vuoi utilizzare la sintassi abbreviata, utilizza | (barra verticale) per gli operatori OR e , (virgola) per gli operatori AND tra parentesi. Questa sintassi abbreviata funziona per i predicati qualificati.

  • Cerca in più ID progetto

    • Utilizza l'operatore OR:
    projectid:(finance-prod|sales-prod|analytics-prod)
    • Utilizza le parentesi:
    projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

  • Cerca voci corrispondenti a più nomi di colonne (AND)

    column:(customer_id,transaction_date,amount)

  • Cerca voci corrispondenti a uno o più nomi di colonne (OR)

    column:(customer_id|user_id|client_id)

Policy con caratteri jolly

La sintassi di ricerca di Knowledge Catalog non supporta i caratteri jolly, come * o ?, nelle stringhe di query o nei predicati.

Se includi un asterisco (*) o un punto interrogativo (?) in una query, questo viene trattato come un carattere letterale anziché come un carattere jolly per la corrispondenza di pattern.

Ad esempio, per cercare tabelle i cui nomi terminano con _masked:

  • Supportato: name:_masked : utilizza il qualificatore di corrispondenza della sottostringa : per trovare tutte le risorse il cui nome contiene _masked, ad esempio customer_records_masked o transactions_masked.
  • Non supportato: name:*_masked: * viene trattato come un carattere letterale, non come un carattere jolly del pattern.

Parentesi tonde

Le parentesi nelle query di ricerca hanno funzioni tecniche specifiche. Se utilizzi troppo le parentesi o le applichi a query in linguaggio naturale, puoi confondere l'analizzatore sintattico della ricerca e peggiorare la qualità dei risultati.

Linguaggio naturale semplice

Quando poni una domanda sull'attività, passa la query in testo normale. Non racchiuderlo tra parentesi. Ad esempio, scrivi:

Find customer orders containing email addresses

Sintassi del predicato abbreviata

Le parentesi sono molto efficaci se utilizzate con le chiavi dei predicati per elencare più condizioniOR eAND in un formato compatto.

  • Raggruppa le chiavi dei predicati con OR (|)

    • Cerca le voci che si trovano in uno dei progetti elencati utilizzando (|)

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

    • Cerca le voci che si trovano in uno dei progetti elencati utilizzando (OR)

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

  • Raggruppa le chiavi dei predicati con AND (,)

    • Cerca le voci che contengono tutte le colonne specificate utilizzando (,)
    column:(customer_id, order_date, total_amount)
    • Cerca le voci che contengono tutte le colonne specificate utilizzando (AND)
    column:customer_id AND column:order_date AND column:total_amount

Puoi combinare una query in linguaggio naturale con filtri compatti.

Ad esempio, per trovare le tabelle che specificano gli utenti attivi mensili, ma limitare la ricerca ai progetti specificati, utilizza la seguente query:

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

Best practice per l'utilizzo delle parentesi

  • Non racchiudere l'intera domanda tra parentesi, perché il motore semantico potrebbe trattare le parentesi come caratteri letterali, restituendo risultati di scarsa pertinenza.

    • Non corretto: (Show me datasets about US population by state)
    • Risposta corretta: Show me datasets about US population by state

  • Evita di combinare alberi booleani complessi e nidificati con parentesi all'interno del campo del linguaggio naturale. La Ricerca è ottimizzata per l'intent del linguaggio naturale. Se la query viene complicata eccessivamente con parentesi e blocchi logici espliciti, il parser si confonde.

    • Non corretto: (revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
    • Risposta corretta: revenue data system=bigquery projectid:(data-warehouse|analytical-tier)

  • Non aggiungere spazi arbitrariamente, a meno che non facciano parte del valore.

    • Non corretto: column:( email | id )
    • Corretto: column:(email|id).

Passaggi successivi