Cercare risorse in Knowledge Catalog

La ricerca in Knowledge Catalog (in precedenza Dataplex Universal Catalog) ti consente di scoprire le risorse della tua organizzazione con il supporto della ricerca in linguaggio naturale con corrispondenza semantica, ricerca per parole chiave e una sintassi di ricerca estesa.

Casi d'uso

Il seguente elenco descrive i casi d'uso comuni della ricerca, insieme a descrizioni ed esempi di query:

  • Ricerca mirata delle risorse: trova una risorsa specifica cercando parole chiave correlate al nome, alle colonne o alla descrizione della risorsa.

    Esempi di query

    • retail_transactions_2026
    • customer_id
    • column:customer_id

  • Ampia scoperta dei dati: identifica gli asset pertinenti nella tua organizzazione utilizzando query in linguaggio naturale o con parole chiave.

    Esempi di query

    • quarterly financial reports
    • ad campaign click through rates tables
    • server health metrics
    • audit logs system=bigquery

  • Recupero di asset con ambito per i workflow: enumera gli asset all'interno di un contenitore specifico, ad esempio un progetto, o con proprietà specifiche, ad esempio tipo o sistema. Questo approccio viene spesso utilizzato per i flussi di lavoro programmatici e agentici.

    Esempi di query

    • type=table projectid:banking-prod aspect:classification.tier=PII
    • system=spanner projectid:inventory-service (parent=marketing_analytics OR parent=finance_analytics)

Per accedere alla ricerca in Knowledge Catalog, hai a disposizione le seguenti opzioni:

Come funziona

La ricerca indicizza automaticamente tutto il contesto degli asset di dati gestiti in Knowledge Catalog. È incluso quanto segue:

  • Metadati inseriti automaticamente da Google Cloud origini dati come BigQuery e Cloud SQL
  • Contesto per le risorse che inserisci tramite connettori e integrazioni
  • Contesto aggiuntivo che crei per le risorse (ad esempio, che rappresenta il contesto aziendale o descrive la semantica dei dati) e acquisito sotto forma di aspetti o termini aziendali collegati.

Quando elabora la query, la ricerca applica una combinazione di corrispondenza semantica e per parole chiave. La tabella seguente descrive i tipi di query che puoi utilizzare con la ricerca di Knowledge Catalog, insieme a descrizioni ed esempi di query:

Tipo di query Utilizzo Esempi
Parola chiave singola Per la corrispondenza esatta e di sottostringa tra gli elementi dei metadati, ad esempio nome, descrizione e schema della risorsa. prd_fin_invoices_fct_v02
Parole chiave parziali e frammenti tokenizzati Corrispondenze di sottostringhe nei contenuti dei metadati, ricerca di risorse anche con termini abbreviati, parole separate o varianti di denominazione. fin transactions 2026 (corrispondenze prd_fin_transactions_fy2026_raw)
Query in linguaggio naturale Utilizza la corrispondenza semantica senza richiedere corrispondenze esatte di nomi o colonne. customer churn prediction features
Predicati strutturati Combina le query di testo libero con filtri di predicato espliciti per restringere i risultati di ricerca. audit logs system=bigquery
Sintassi estesa Per una ricerca precisa, ristretta a un ambito specifico. La sintassi estesa viene utilizzata più spesso nei casi d'uso agentici e programmatici. Per maggiori informazioni, vedi Sintassi di ricerca. (system:bigquery OR system:spanner) AND column:credit_card_number aspect:classification.tier=PII -projectid:sandbox-project

Ambito di ricerca

I risultati di ricerca in Knowledge Catalog rispettano le autorizzazioni che hai sulle risorse corrispondenti nei sistemi di origine.

Ad esempio, se hai accesso in lettura ai metadati BigQuery di un oggetto, questo viene visualizzato nei risultati di ricerca di Knowledge Catalog. Se hai accesso a una tabella BigQuery, ma non al set di dati che la contiene, la tabella viene comunque visualizzata come previsto nella ricerca del Knowledge Catalog.

Per impostazione predefinita, la ricerca è limitata alla tua organizzazione. I risultati includono solo le risorse della stessa organizzazione del progetto in cui esegui la ricerca.

I risultati di ricerca includono solo le risorse che appartengono allo stesso perimetro dei Controlli di servizio VPC del progetto in cui viene eseguita la ricerca. Quando utilizzi la consoleGoogle Cloud , questo è il progetto selezionato nella console.

Per ampliare l'ambito dei risultati di ricerca oltre le risorse all'interno del perimetro dei Controlli di servizio VPC del tuo progetto, utilizza le regole in entrata e in uscita dei Controlli di servizio VPC. Queste regole facilitano lo scambio di dati privato ed efficiente all'interno della tua organizzazione. Puoi configurare le regole in entrata e in uscita utilizzando la consoleGoogle Cloud o tramite file JSON o YAML. Fai riferimento al seguente esempio YAML e consulta la documentazione dei Controlli di servizio VPC per adattare la regola ai tuoi requisiti specifici.

egressPolicies:
  - egressFrom:
      identityType: ANY_USER_ACCOUNT
    egressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids under which the search is performed.
      resources:
      - projects/SEARCH_PROJECT_ID
ingressPolicies:
  - ingressFrom:
      identityType: ANY_USER_ACCOUNT
      sources:
      - accessLevel: '*'
    ingressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids to expose in search results.
      resources:
      - projects/INGRESS_PROJECT_ID

Per saperne di più sui ruoli Identity and Access Management che devi utilizzare per la ricerca in Knowledge Catalog, consulta Ruoli IAM per Knowledge Catalog.

Isolare i risultati di ricerca per ambiente utilizzando i Controlli di servizio VPC

Per isolare i risultati di ricerca di Knowledge Catalog tra ambienti come sviluppo, test e produzione, configura perimetri dei Controlli di servizio VPC separati per ogni ambiente. Assegna sia i progetti che contengono gli asset di dati sia i progetti utilizzati per eseguire le ricerche al perimetro dell'ambiente corrispondente. Le ricerche eseguite da un progetto all'interno di un perimetro specifico restituiranno risultati solo per gli asset che si trovano anche all'interno dello stesso perimetro.

Limitazioni del ritiro nella ricerca

Le query di ricerca di Knowledge Catalog non garantiscono il recupero completo, il che significa che la ricerca potrebbe non restituire risultati corrispondenti alla query. Inoltre, i risultati restituiti (e non restituiti) potrebbero variare se ripeti le query di ricerca.

Per eseguire query su tutti i metadati di Knowledge Catalog, puoi esportarli in Cloud Storage ed eseguire query da BigQuery. Per saperne di più, consulta Esportare i metadati.

Prima di iniziare

Prima di eseguire la ricerca, assicurati di disporre dei ruoli richiesti e di aver abilitato l'API necessaria.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per cercare voci e accedere ai risultati di ricerca in Knowledge Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Le autorizzazioni sui risultati di ricerca vengono controllate indipendentemente dal progetto selezionato.

I risultati di ricerca in Knowledge Catalog sono limitati in base al tuo ruolo. Per cercare un asset in Knowledge Catalog, devi disporre delle autorizzazioni per accedere alla risorsa corrispondente nel sistema di origine. Per saperne di più, consulta la sezione Ambito di ricerca di questo documento.

Ad esempio, per cercare set di dati, tabelle, viste e modelli BigQuery, devi disporre delle rispettive autorizzazioni per queste voci. Per ulteriori informazioni, vedi Autorizzazioni BigQuery.

Il seguente elenco descrive le autorizzazioni minime richieste:

  • Per cercare una tabella, devi disporre dell'autorizzazione bigquery.tables.get per quella tabella.
  • Per cercare un set di dati, devi disporre dell'autorizzazione bigquery.datasets.get per quel set di dati.

Come altro esempio, per cercare istanze, database, schemi, tabelle e viste Cloud SQL, devi disporre delle rispettive autorizzazioni per queste voci. Per saperne di più, consulta Ruoli e autorizzazioni di Cloud SQL.

Abilita l'API

Abilitare l'API Dataplex.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Cerca risorse

Console

Per cercare risorse, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Ricerca di Knowledge Catalog.

    Vai a Cerca

  2. Se vedi il prompt del pulsante Prova la ricerca in linguaggio naturale, fai clic. Per impostazione predefinita, è selezionata la ricerca in linguaggio naturale.

  3. Nel campo Trova risorse tra i progetti con il linguaggio naturale, inserisci la query e poi fai clic su Invio.

  4. Per perfezionare la ricerca, fai clic su Filtri. Per l'elenco dei filtri disponibili, vedi Filtri.

  5. Per visualizzare ulteriori informazioni sulla risorsa cercata, fai clic sul nome della risorsa nei risultati di ricerca. Viene visualizzata la pagina dei dettagli della voce.

Google Cloud CLI

Per cercare risorse, utilizza il comando gcloud dataplex entries search:

gcloud dataplex entries search 'foo' \
  --project=PROJECT_ID \
  [--semantic-search]

Sostituisci PROJECT_ID con l'ID del progetto Google Cloud .

C#

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Knowledge Catalog per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Knowledge Catalog C#.

Per eseguire l'autenticazione in Knowledge Catalog, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

using Google.Api.Gax;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dataplex.V1;
using System;

public sealed partial class GeneratedCatalogServiceClientSnippets
{
    /// <summary>Snippet for SearchEntries</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SearchEntriesRequestObject()
    {
        // Create client
        CatalogServiceClient catalogServiceClient = CatalogServiceClient.Create();
        // Initialize request argument(s)
        SearchEntriesRequest request = new SearchEntriesRequest
        {
            LocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            Query = "",
            OrderBy = "",
            Scope = "",
            SemanticSearch = false,
        };
        // Make the request
        PagedEnumerable<SearchEntriesResponse, SearchEntriesResult> response = catalogServiceClient.SearchEntries(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (SearchEntriesResult item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (SearchEntriesResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (SearchEntriesResult item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<SearchEntriesResult> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (SearchEntriesResult item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}