Cercare e visualizzare gli asset di dati con Data Catalog

Questo documento spiega come utilizzare Data Catalog per eseguire una ricerca degli asset di dati, ad esempio:

Set di dati collegati di Analytics Hub
Set di dati, tabelle, viste e modelli BigQuery
Modelli di tag Data Catalog, gruppi di voci e voci personalizzate
Lake, zone, tabelle e set di file Dataplex
Stream di dati Pub/Sub
Asset in silos di dati aziendali collegati a Data Catalog
(Anteprima): istanze e tabelle Cloud Bigtable
(Anteprima): istanze, chiavi, tabelle e viste Cloud Spanner
(Anteprima): servizi, database e tabelle Dataproc Metastore

Ambito della ricerca

Potresti avere risultati di ricerca diversi in base alle tue autorizzazioni. L'ambito dei risultati di ricerca di Data Catalog dipende dal ruolo.

Puoi esaminare i diversi tipi di ruolo e autorizzazioni IAM disponibili per Data Catalog.

Ad esempio, se disponi dell'accesso in lettura ai metadati di BigQuery, questo oggetto viene visualizzato nei risultati di ricerca di Data Catalog. Nell'elenco che segue vengono descritte le autorizzazioni minime richieste:

Per cercare una tabella, devi disporre dell'autorizzazione bigquery.tables.get per tale tabella.
Per cercare un set di dati, devi disporre dell'autorizzazione bigquery.tables.get per quel set di dati.
Per cercare i metadati per un set di dati o una tabella, devi avere il ruolo roles/bigquery.metadataViewer.

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 attualmente supportati, come Pub/Sub e lo stesso Data Catalog.

Problemi di richiamo nella ricerca

Le query di ricerca di Data Catalog non garantiscono il richiamo completo. I risultati che corrispondono alla tua query potrebbero non essere restituiti, anche nelle pagine dei risultati successive. Inoltre, i risultati restituiti (e non restituiti) possono variare se ripeti le query di ricerca. Se riscontri problemi di richiamo e non devi recuperare i risultati in un ordine specifico, valuta di impostare il parametro orderBy su default quando chiami il metodo catalog.search.

Tabelle con blocco della data

Data Catalog aggrega le tabelle con suddivisione in date in un'unica voce logica. Questa voce ha lo stesso schema dello shard della tabella con la data più recente e contiene informazioni aggregate sul numero totale di dischi rigidi. La voce deriva il proprio livello di accesso 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 hard-date non saranno visibili nella ricerca di Data Catalog, anche se sono presenti in Data Catalog e possono essere taggate.

Filtri

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

Ambito per limitare la ricerca solo agli elementi speciali.
Sistemi come BigQuery, Pub/Sub, Dataplex, Dataproc Metastore, sistemi personalizzati e Data Catalog stesso. Il sistema Data Catalog contiene set di file e voci personalizzate.
Laghi e zone provengono da Dataplex.
Tipi di dati come stream di dati, set di dati, lake, zone, set di file, modelli, tabelle, viste, servizi, database e tipi personalizzati.
In Progetti sono elencati tutti i progetti disponibili.
Nella sezione Tag sono elencati tutti i modelli di tag (e i rispettivi campi) disponibili.
I set di dati provengono da BigQuery.
I set di dati pubblici sono dati disponibili pubblicamente provenienti da BigQuery.

Puoi combinare i filtri di più sezioni per trovare gli asset che soddisfano 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, data la seguente combinazione di filtri:

Data Catalog cerca:

Set di dati BigQuery codificati con modello MyTemplate1.
Set di dati BigQuery codificati con il modello MyTemplate2.
Tabelle BigQuery contrassegnate con il modello MyTemplate1.
Tabelle BigQuery contrassegnate con il modello MyTemplate2.

Filtra per valore 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 i dati in base a valori specifici del tag. Le condizioni di filtro per il valore tag dipendono dal tipo di dati del campo tag. Ad esempio, per i campi data e ora, puoi specificare una data o un intervallo specifici.

Visibilità dei filtri

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

Come cercare gli asset di dati

Console

Per avviare una query di ricerca Dataplex nella console Google Cloud, vai alla pagina Dataplex Search.

Vai a Dataplex Search
Inserisci i termini di ricerca nella casella di ricerca oppure utilizza il riquadro Filtri per perfezionare i parametri di ricerca.

Puoi aggiungere manualmente i seguenti filtri:

In Progetti, puoi filtrare un progetto facendo clic sul pulsante AGGIUNGI PROGETTO, cercando un progetto specifico e selezionandolo, quindi fai clic su APRI.
In Tag, filtra un modello di tag facendo clic sul menu a discesa Aggiungi altri modelli di tag, cercando un modello specifico, selezionandolo e facendo clic su OK.

Inoltre, puoi:

Seleziona Includi set di dati pubblici per cercare asset di dati disponibili pubblicamente in Google Cloud oltre agli asset a tua disposizione.

Esempio di ricerca

Ad esempio, per cercare la tabella trips impostata in Configurare modelli di tag, tag, panoramiche e gestori dei dati:

Inserisci trips nella casella di ricerca e fai clic su Cerca.
Seleziona BigQuery dalla sezione Sistemi per escludere gli asset di dati con lo stesso nome che appartengono ad altri sistemi.
Seleziona l'ID progetto dalla sezione Progetti per escludere gli asset di dati da altri progetti. Se il tuo progetto non è visualizzato nella sezione, fai clic su AGGIUNGI PROGETTO e selezionalo nella finestra di dialogo.
Seleziona il Modello di tag demo dalla sezione Modelli di tag per vedere se un tag che utilizza questo modello è allegato alla tabella trips. Se questo modello non viene visualizzato nella sezione, fai clic sul menu a discesa Aggiungi altri tag, trovalo e selezionalo, quindi fai clic su OK.

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

Puoi anche effettuare le seguenti operazioni:

Filtra la ricerca aggiungendo un keyword:value ai termini di ricerca nella casella di ricerca:

Parola chiave	Descrizione
`name:`	Nome asset di dati di corrispondenza
`column:`	Corrispondenza con nome della colonna o nome della colonna nidificato
`description:`	Descrizione della tabella delle corrispondenze

Esegui una ricerca dei tag aggiungendo uno dei seguenti prefissi di parole chiave ai tag di ricerca nella casella di ricerca:

Tag	Descrizione
`tag:project-name.tag_template_name`	Nome tag di corrispondenza
`tag:project-name.tag_template_name.key`	Corrispondenza con una chiave tag
`tag:project-name.tag_template_name.key:value`	Associa la 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 precedere una parola chiave con "NOT" (tutti i caratteri CAPS richiesti) per soddisfare la negazione logica del filtro keyword:term. Puoi utilizzare anche gli operatori booleani "AND" e "OR" (tutto in maiuscolo) per combinare 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 da utilizzare in un'espressione di ricerca Data Catalog, consulta la sintassi di ricerca Data Catalog.

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Data Catalog utilizzando le librerie client. Per scoprire di più, consulta la documentazione di riferimento per l'API Java Data Catalog.

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

Visualizza su GitHub Feedback

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 nella guida rapida di Data Catalog utilizzando le librerie client. Per scoprire di più, consulta la documentazione di riferimento per l'API Node.js Data Catalog.

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

Visualizza su GitHub Feedback

// 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 nella guida rapida di Data Catalog utilizzando le librerie client. Per scoprire di più, consulta la documentazione di riferimento per l'API Python Data Catalog.

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

Visualizza su GitHub Feedback

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)

LINEA REST E CMD

REST

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

1. Cerca nel catalogo.

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

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

Metodo e URL HTTP:

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

Corpo JSON richiesta:

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

Per inviare la richiesta, espandi una delle seguenti 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 esegue automaticamente l'accesso all'interfaccia a riga di comando di gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

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)

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

$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 i dettagli della tabella

In Cloud Console, puoi utilizzare Data Catalog per visualizzare i dettagli della tabella.

Vai alla pagina di ricerca di Dataplex.

Vai a Data Catalog
Inserisci nella casella di ricerca il nome di un set di dati che contiene una tabella.

Ad esempio, se hai completato la Guida rapida, puoi cercare demo-dataset e selezionare la tabella trips.
Fai clic sulla tabella.

Si apre la pagina Dettagli tabella BigQuery.

I dettagli della tabella includono le seguenti sezioni:

Dettagli tabella BigQuery. Include informazioni come il momento della creazione, l'ora dell'ultima modifica, l'ora di scadenza, gli URL delle risorse, le etichette e così via.
Tag. Elenca i tag applicati.Puoi modificare i tag da questa pagina e visualizzare il modello di tag. Fai clic sull'icona Azioni.
Tag di schema e colonna. Elenca lo schema applicato e i relativi valori.

Aggiungi a Speciali le tue voci preferite e cercale

Se sfogli frequentemente gli stessi asset di dati, puoi includerli in un elenco personalizzato contrassegnandoli a stelle. Per farlo nell'interfaccia utente di Dataplex:

Vai alla pagina di ricerca di Dataplex e trova l'asset.

Vai a Data Catalog
Aggiungi i dati a Speciali in uno dei due modi seguenti:
- Fai clic sull'icona accanto alla voce nei risultati di ricerca.
- Fai clic sul nome della voce per aprire la relativa pagina dei dettagli, quindi fai clic sul pulsante STELLA nella barra delle azioni in alto.

Puoi aggiungere a Speciali fino a 200 voci.

Le voci aggiunte a Speciali vengono visualizzate nell'elenco Voci aggiunte a Speciali nella pagina di ricerca prima di inserire una query di ricerca nella barra di ricerca. Questo elenco è visibile solo a te.

Per cercare solo le voci aggiunte a Speciali, seleziona l'opzione Ambito > Speciali nel riquadro Filtri.

Puoi anche utilizzare i metodi corrispondenti dell'API Data Catalog per aggiungere e rimuovere da Speciali le voci. Quando cerchi gli asset, utilizza il parametro starredOnly nell'oggetto scope. Vedi il metodo catalog.search.