Sintassi di ricerca per Knowledge Catalog

Knowledge Catalog consente di scoprire, catalogare centralmente, gestire e comprendere i dati della tua organizzazione. Per trovare in modo efficiente asset di dati specifici all'interno del tuo data catalog, puoi utilizzare query di ricerca efficaci. La sintassi delle query di ricerca include:

  • Ricerca semplice: ricerca di asset di dati utilizzando un singolo termine di ricerca.
  • Ricerca a testo libero: ricerca di asset di dati utilizzando frasi o parole chiave in linguaggio naturale.
  • Predicati qualificati: perfezionamento della ricerca utilizzando campi di metadati specifici come nome, posizione, sistema o tipo.
  • Ricerca per aspetto: ricerca di voci in base ai metadati tecnici e aziendali allegati.
  • Operatori logici: combinano più criteri di ricerca utilizzando gli operatori AND, OR o NOT per creare query complesse. Comprendendo questa sintassi, puoi individuare rapidamente i dati di cui hai bisogno.

Predicati qualificati

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

Puoi qualificare un predicato anteponendogli 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 divide il flusso di testo in una serie di token, ciascuno dei quali corrisponde in genere 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 posizione specificata con foo come nome della posizione.

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 Corrisponde a 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 hanno il token products nella descrizione. Ad esempio, "elenco dei prodotti in inventario".
  • description:"prod" non mostra le risorse che hanno il token products nella descrizione. Mostra invece tutte le risorse che hanno il token prod nella descrizione. Ad esempio, "ambiente di produzione".
labels:bar Corrisponde alle risorse che hanno un'etichetta (con un determinato valore) e la chiave di etichetta ha bar come sottostringa.
labels=bar Corrisponde alle risorse che hanno un'etichetta (con un valore) e la chiave di 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 Corrisponde alle risorse in cui la chiave è uguale a foo e il valore della chiave è uguale a bar.
type=TYPE Corrisponde alle risorse di un tipo di voce specifico o al relativo alias di tipo. Richiede il qualificatore =.
projectid:bar Trova le risorse all'interno dei progetti Google Cloud che corrispondono a bar come sottostringa nell'ID.
parent:x Corrisponde a x come sottostringa del percorso gerarchico di una risorsa.
system=SYSTEM Corrisponde alle risorse di un sistema specificato. Richiede il qualificatore =.
location=LOCATION

Corrisponde alle risorse in una posizione 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 del Nord.

createtime

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

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

Qualificatori per la corrispondenza esatta

Le chiavi predicato type, system, location e la ricerca di aspetti (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 sottostringa

I predicati come name, displayname, column, projectid e parent supportano la corrispondenza di sottostringhe con il qualificatore 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 temporali

Puoi filtrare le risorse in base all'ora di creazione (createtime) o all'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 del 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, ad esempio YYYY-MM-DDTHH:MM o YYYY-MM-DDTHH.

Sintassi del filtro temporale

La tabella seguente spiega 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 le unità di giorno 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 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 ordine dei componenti non standard (ad esempio DD-MM-YYYY o MM/DD/YYYY) o 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 offset 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 tempo della giornata non è supportata.
  • Utilizza invece confronti separati per il limite inferiore e quello 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 data 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 in base alla chiave di etichetta, al valore o a entrambi:

Pattern di query Esempio Descrizione
labels=KEY labels=environment Corrisponde alle risorse che hanno un'etichetta con la chiave esatta environment, indipendentemente dal suo valore.
labels:KEY_SUBSTRING labels:tier Corrisponde alle risorse con una chiave di etichetta contenente tier come sottostringa (ad esempio service_tier o storage_tier).
labels.KEY=VALUE labels.env=prod Trova la corrispondenza con le risorse in cui la chiave di etichetta è env e il suo valore è esattamente prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Corrisponde alle 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 Corrisponde alle risorse a cui sono associate le etichette env=prod e data_tier=tier1.
Combinato con sistema e 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 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 allegato 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 allegato alla voce, nel formato projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

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

  • Sintassi per i tipi di aspetto del 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
    • Valore booleano: =

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 in maiuscolo.

AND operatore

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

Gli esempi riportati di seguito mostrano come creare query con l'operatore AND.

  • Cercare 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

OR operatore

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

Gli esempi riportati di seguito mostrano come creare query con l'operatore OR.

  • Cercare tabelle e viste BigQuery

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

  • Cercare 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)

NOT operatore

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

Gli esempi riportati di seguito mostrano come creare query con l'operatore NOT.

  • Trovare tutte le tabelle, tranne quelle in un progetto sandbox

    • Utilizzare 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, usa | (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 qualsiasi dei nomi di più colonne (OR)

    column:(customer_id|user_id|client_id)

Norme relative ai caratteri jolly

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

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

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

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

Parentesi tonde

Le parentesi nelle query di ricerca hanno funzioni tecniche specifiche. Se utilizzi in modo eccessivo le parentesi o le applichi a query in linguaggio naturale, puoi confondere il parser di ricerca e ridurre la qualità dei risultati.

Linguaggio naturale semplice

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

Find customer orders containing email addresses

Sintassi del predicato abbreviato

Le parentesi sono molto efficaci se utilizzate con le chiavi predicato per elencare più condizioni OR eAND in un formato compatto.

  • Raggruppa le chiavi dei predicati con OR (|)

    • Cerca voci presenti in uno qualsiasi dei progetti elencati utilizzando (|)

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

    • Cerca voci che si trovano in uno qualsiasi 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 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, generando risultati di bassa pertinenza.

    • Errato: (Show me datasets about US population by state)
    • Corretto: 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'intento del linguaggio naturale. Se la query è troppo complessa con parentesi e blocchi logici espliciti, il parser non riesce a interpretarla.

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

  • Non aggiungere spazi in modo arbitrario, a meno che non facciano parte del valore.

    • Errato: column:( email | id )
    • Corretto: column:(email|id).

Passaggi successivi