Cercare asset di dati con Data Catalog

Questo documento descrive come utilizzare Data Catalog per cercare gli asset di dati.

Nota: questo documento descrive la ricerca in Data Catalog. Per informazioni sulla ricerca in Dataplex Catalog, consulta Cercare asset di dati in Dataplex Catalog e Differenza tra Dataplex Catalog e Data Catalog.

Puoi cercare i seguenti asset di dati:

• Set di dati collegati di Analytics Hub
• Set di dati, tabelle, viste e modelli BigQuery
• Istanze, cluster e tabelle Bigtable (inclusi i dettagli della famiglia di colonne)
• Modelli di tag, gruppi di voci e voci personalizzate di Data Catalog
• Lake, zone, tabelle e set di file Dataplex
• Servizi, database e tabelle di Dataproc Metastore
• Flussi di dati Pub/Sub
• Istanze, database, tabelle e visualizzazioni Spanner
• Modelli, set di dati e risorse Vertex AI Feature Store di Vertex AI
• Asset nei silos di dati aziendali collegati a Data Catalog

Ambito di ricerca

I risultati di ricerca potrebbero essere diversi in base alle tue autorizzazioni. I risultati di ricerca di Data Catalog sono definiti in base al tuo ruolo.

Puoi esaminare i diversi tipi di autorizzazioni e ruoli IAM disponibili per Data Catalog. Ad esempio, se hai accesso in lettura ai metadati BigQuery di un oggetto, questo viene visualizzato nei risultati di ricerca di Data Catalog.

Il seguente elenco descrive le autorizzazioni minime necessarie per eseguire la ricerca:

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

• Per cercare i metadati di un set di dati o di una tabella, devi disporre del ruolo IAM roles/bigquery.metadataViewer.

• Per cercare tutte le risorse all'interno di un progetto o di un'organizzazione, devi disporre dell'autorizzazionedatacatalog.catalogs.searchAll. Funziona per tutte le risorse indipendente dal sistema di origine.

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 di Data Catalog. La stessa logica di accesso si applica a tutti i sistemi supportati, come Pub/Sub e Data Catalog.

Problemi di richiamo nella ricerca

Le query di ricerca di Data Catalog non garantiscono un recupero completo. I risultati corrispondenti alla tua query potrebbero non essere restituiti, nemmeno nelle pagine dei risultati successive. Inoltre, se ripeti le query di ricerca, i risultati restituiti (e non restituiti) possono variare.

Se riscontri problemi di recupero e non devi recuperare i risultati in un ordine specifico, ti consigliamo di impostare il parametro orderBy su default quando chiami il metodo catalog.search.

Utilizza il flag admin_search

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

L'utilizzo del flag admin_search nella richiesta di ricerca garantisce il recupero completo. La ricerca dell'amministratore richiede l'impostazione dell'autorizzazione datacatalog.catalogs.searchAll su tutti i progetti e le organizzazioni nell'ambito di ricerca. Quando utilizzi admin_search, è consentito solo default orderBy.

Tabelle con sharding per data

Data Catalog aggrega le tabelle suddivise in parti in base alla data in un'unica voce logica. Questa voce ha lo stesso schema del frammento di tabella con la data più recente e contiene informazioni aggregate sul numero totale di frammenti. Il livello di accesso della voce deriva dal set di dati a cui appartiene. La ricerca in Data Catalog mostra queste voci logiche solo se l'utente ha accesso al set di dati che le contiene. Le singole tabelle con suddivisione in base alla data non sono visibili nella ricerca di Data Catalog, anche se sono presenti in Data Catalog e possono essere taggate.

Filtri

I filtri ti consentono di restringere i risultati di ricerca. Tutti i filtri sono raggruppati in sezioni:

• Ambito per limitare la ricerca solo agli elementi contrassegnati come speciali.
• Sistemi come BigQuery, Pub/Sub, Dataplex, Dataproc Metastore, sistemi personalizzati, Vertex AI e il Data Catalog stesso. Il sistema Data Catalog contiene set di file e voci personalizzate.
• I lake e le zone provengono da Dataplex.
• Tipi di dati come stream di dati, set di dati, lake, zone, set di file, modelli, tabelle, visualizzazioni, servizi, database e tipi personalizzati.
• Progetti elenca tutti i progetti a tua disposizione.
• In Tag sono elencati tutti i modelli di tag (e i relativi singoli campi) a tua disposizione.
• I set di dati provengono da BigQuery e Vertex AI.
• I set di dati pubblici sono dati di BigQuery disponibili pubblicamente.

Puoi combinare i filtri di più sezioni per trovare gli asset che corrispondono a almeno una condizione di ogni sezione selezionata. Più filtri selezionati all'interno di una singola sezione vengono valutati utilizzando l'operatore logico OR. Ad esempio, considera la seguente combinazione di filtri:

Esempio che mostra come combinare i filtri di più sezioni.

Data Catalog cerca quanto segue:

• Set di dati BigQuery taggati con il modello MyTemplate1.

• Set di dati BigQuery taggati con il modello MyTemplate2.

• Tabelle BigQuery taggate con il modello MyTemplate1.

• Tabelle BigQuery taggate con il modello MyTemplate2.

Filtra per valore del tag

I filtri Tag ti consentono di eseguire query sugli asset taggati utilizzando un modello specifico. Puoi utilizzare il menu Personalizza per perfezionare ulteriormente i risultati e filtrare in base a valori specifici dei tag. Le condizioni di filtro del valore del tag dipendono dal tipo di dati del campo del tag. Ad esempio, per i campi data/ora e numerici, puoi specificare una data specifica o un intervallo.

Visibilità dei filtri

I filtri visualizzati in ogni sezione dipendono dalla query corrente nella casella Cerca. L'intero insieme di risultati di ricerca potrebbe includere voci che corrispondono alla query corrente, ma i filtri corrispondenti a queste voci potrebbero non essere visualizzati nel riquadro Filtri.

Nota: se modifichi i filtri selezionati, i set di filtri non vengono aggiornati. Ad esempio, se selezioni il sistema BigQuery nella sezione Sistemi, i filtri Tipo di dati non si restringono ai tipi di dati specifici di BigQuery, come Tabella, Visualizzazione e Set di dati.

Ricerca di asset di dati

Console

Console

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

   Vai alla pagina Cerca di Dataplex

2. Per Scegli la piattaforma di ricerca, seleziona Data Catalog come modalità di ricerca.

3. Nel campo di ricerca, inserisci la query o utilizza il riquadro Filtri per perfezionare i parametri di ricerca.

   Puoi aggiungere manualmente i seguenti filtri:

   • In Progetti, aggiungi un filtro dei progetti. Fai clic su Aggiungi progetto, cerca e seleziona un progetto specifico e fai clic su Apri.
   • In Tag, aggiungi un filtro per i modelli di tag. Fai clic sul menu Aggiungi altri modelli di tag, cerca e seleziona un modello specifico e fai clic su Ok.

   Per cercare asset di dati disponibili pubblicamente in Google Cloud, oltre agli asset a tua disposizione, seleziona Includi set di dati pubblici.

Inoltre, puoi:

• Filtra la ricerca aggiungendo keyword:value ai termini di ricerca nel campo di ricerca:

  Parola chiave	Descrizione
  name:	Nome dell'asset di dati corrispondenti
  column:	Corrisponde al nome della colonna o al nome della colonna nidificata
  description:	Descrizione della tabella delle corrispondenze

• Esegui una ricerca dei tag aggiungendo uno dei seguenti prefissi di parola chiave dei tag ai termini di ricerca nel campo di ricerca:

  Tag	Descrizione
  tag:project-name.tag_template_name	Corrisponde al nome del tag
  tag:project-name.tag_template_name.key	Abbinare una chiave tag
  tag:project-name.tag_template_name.key:value	Abbina coppia di tag key:string value

Suggerimenti per le espressioni di ricerca

• Racchiudi l'espressione di ricerca tra virgolette ("search terms") se contiene spazi.

• Puoi anteporre una parola chiave a "NON" (tutto in maiuscolo) per ottenere la negazione logica del filtro keyword:term. Puoi anche utilizzare gli operatori booleani "AND" e "OR" (obbligatorio in maiuscolo) per combinare le espressioni di ricerca.

  Ad esempio:NOT column:term elenca tutte le colonne tranne quelle che corrispondono al termine specificato. Per un elenco di parole chiave e altri termini che puoi utilizzare in un'espressione di ricerca di Data Catalog, consulta la sintassi di ricerca di Data Catalog.

Esempio di ricerca

Prendi in considerazione un esempio in cui vuoi cercare la tabella trips che hai configurato in Collega i tag a una tabella BigQuery utilizzando Data Catalog:

1. Nel campo di ricerca, inserisci trips e fai clic su Cerca.

2. Nel riquadro Filtri, seleziona quanto segue:

   • Nella sezione Sistemi, seleziona BigQuery per escludere gli asset dati con lo stesso nome che appartengono ad altri sistemi.
   • Nella sezione Progetti, seleziona il tuo ID progetto per escludere gli asset di dati da altri progetti. Se il progetto non viene visualizzato, fai clic su Aggiungi progetto e selezionalo.
   • Nella sezione Tag, seleziona Modello di tag demo per verificare se un tag che utilizza questo modello è associato alla tabella trips. Se questo modello non viene visualizzato, fai clic su Aggiungi altri modelli di tag, cerca e seleziona il modello di tag e fai clic su OK.

Con tutti i filtri selezionati, i risultati di ricerca contengono una sola voce: la tabella trips di BigQuery nel progetto con un tag associato che utilizza il modello Demo Tag Template.

Nota: per visualizzare l'anteprima dei contenuti di una tabella BigQuery, nel risultato di ricerca fai clic su accanto alla tabella.

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java riportate nella guida rapida all'utilizzo di Data Catalog con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Data Catalog Java.

Per autenticarti in Data Catalog, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.DataCatalogClient.SearchCatalogPagedResponse;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest.Scope;
import com.google.cloud.datacatalog.v1.SearchCatalogResult;
import java.io.IOException;

// Sample to search catalog
public class SearchAssets {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String query = "type=dataset";
    searchCatalog(projectId, query);
  }

  public static void searchCatalog(String projectId, String query) throws IOException {
    // Create a scope object setting search boundaries to the given organization.
    // Scope scope = Scope.newBuilder().addIncludeOrgIds(orgId).build();

    // Alternatively, search using project scopes.
    Scope scope = Scope.newBuilder().addIncludeProjectIds(projectId).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Search the catalog.
      SearchCatalogRequest searchCatalogRequest =
          SearchCatalogRequest.newBuilder().setScope(scope).setQuery(query).build();
      SearchCatalogPagedResponse response = dataCatalogClient.searchCatalog(searchCatalogRequest);

      System.out.println("Search results:");
      for (SearchCatalogResult result : response.iterateAll()) {
        System.out.println(result);
      }
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js riportate nella guida rapida all'utilizzo di Data Catalog con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Data Catalog Node.js.

Per autenticarti in Data Catalog, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function searchAssets() {
  // Search data assets.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project'; // Google Cloud Platform project

  // Set custom query.
  const query = 'type=lake';

  // Create request.
  const scope = {
    includeProjectIds: [projectId],
    // Alternatively, search using Google Cloud Organization scopes.
    // includeOrgIds: [organizationId],
  };

  const request = {
    scope: scope,
    query: query,
  };

  const [result] = await datacatalog.searchCatalog(request);

  console.log(`Found ${result.length} datasets in project ${projectId}.`);
  console.log('Datasets:');
  result.forEach(dataset => {
    console.log(dataset.relativeResourceName);
  });
}
searchAssets();

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python riportate nella guida rapida all'utilizzo di Data Catalog con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Data Catalog Python.

Per autenticarti in Data Catalog, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

from google.cloud import datacatalog_v1

datacatalog = datacatalog_v1.DataCatalogClient()

# TODO: Set these values before running the sample.
project_id = "project_id"

# Set custom query.
search_string = "type=dataset"
scope = datacatalog_v1.types.SearchCatalogRequest.Scope()
scope.include_project_ids.append(project_id)

# Alternatively, search using organization scopes.
# scope.include_org_ids.append("my_organization_id")

search_results = datacatalog.search_catalog(scope=scope, query=search_string)

print("Results in project:")
for result in search_results:
    print(result)

REST e riga di comando

REST

Se non hai accesso alle librerie client di Cloud per il tuo linguaggio o se vuoi testare l'API utilizzando le richieste REST, consulta i seguenti esempi e la documentazione dell'API REST Data Catalog.

1. Cerca nel catalogo.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• organization-id: ID organizzazione Google Cloud
• project-id: ID progetto Google Cloud

Metodo HTTP e URL:

POST https://datacatalog.googleapis.com/v1/catalog:search

Corpo JSON della richiesta:

{
  "query":"trips",
  "scope":{
    "includeOrgIds":[
      "organization-id"
    ]
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datacatalog.googleapis.com/v1/catalog:search"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/catalog:search" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "results":[
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
"relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry1-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/taxi_trips"
    },
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
      "relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry2-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/tlc_yellow_trips_2018"
    }
  ]
}

Visualizza dettagli della tabella

Utilizza Data Catalog per visualizzare i dettagli della tabella.

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

   Vai a Ricerca in Data Catalog

2. Per Scegli la piattaforma di ricerca, seleziona Data Catalog come modalità di ricerca.

3. Nella casella di ricerca, inserisci il nome di un set di dati contenente una tabella.

   Ad esempio, se hai completato la procedura di Collega i tag a una tabella BigQuery utilizzando Data Catalog, puoi cercare demo-dataset e selezionare la tabella trips.

4. Fai clic sulla tabella.

   Viene visualizzata la pagina dei dettagli della tabella BigQuery.

I dettagli della tabella includono le seguenti sezioni:

• Dettagli della tabella BigQuery. Sono incluse informazioni come data e ora di creazione, data e ora dell'ultima modifica, data e ora di scadenza, URL delle risorse ed etichette.

• Tag. Elenca i tag applicati.Puoi modificare i tag da questa pagina e visualizzare il modello di tag. Fai clic sull'icona Azioni.

• Tag schema e colonna. Elenca lo schema applicato e i relativi valori.

Contrassegnare come speciali le voci preferite e cercarle

Se consulti spesso gli stessi asset di dati, puoi includerne le voci in un elenco personalizzato contrassegnandole con una stella.

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

   Vai a Ricerca in Data Catalog

2. Per Scegli la piattaforma di ricerca, seleziona Data Catalog come modalità di ricerca.

3. Trova la risorsa e aggiungi una stella alla relativa voce in uno dei due modi seguenti:

   • Fai clic su accanto alla voce nei risultati di ricerca.
   • Fai clic sul nome della voce per aprire la relativa pagina dei dettagli e poi fai clic sul pulsante STAR nella barra delle azioni in alto.

Puoi aggiungere a Speciali fino a 200 voci.

Le voci contrassegnate vengono visualizzate nell'elenco Voci contrassegnate nella pagina di ricerca prima che tu inserisca una query di ricerca nella barra di ricerca. Questo elenco è visibile solo a te.

Per cercare solo le voci contrassegnate come speciali, seleziona Speciali nel riquadro Filtri, nella sezione Ambito.

Puoi anche utilizzare i metodi corrispondenti dell'API Data Catalog per aggiungere e rimuovere le stelle dalle voci. Quando cerchi asset, utilizza il parametro starredOnly nell'oggetto scope. Per ulteriori informazioni, consulta il metodo catalog.search.

Passaggi successivi

• Comprendi la sintassi di ricerca per Data Catalog.

• Scopri come cercare risorse in Dataplex Catalog.