Generare approfondimenti sulla tabella

Questo documento descrive come generare approfondimenti sulle tabelle per le tabelle BigQuery, le tabelle BigLake e le tabelle esterne. Gli approfondimenti sulle tabelle ti aiutano a comprendere i dati all'interno di una singola tabella generando domande in linguaggio naturale e query SQL in base ai metadati della tabella.

Gli approfondimenti sulle tabelle possono aiutarti ad accelerare l'esplorazione dei dati consentendoti di comprendere rapidamente la struttura e i contenuti di una tabella nuova o sconosciuta senza scrivere query complesse. Puoi anche generare query SQL in base a domande in linguaggio naturale, il che riduce il tempo e l'impegno necessari per scrivere query manualmente. Gli approfondimenti sulle tabelle possono anche aiutare gli utenti non SQL a comprendere e analizzare i dati tramite queste query in linguaggio naturale.

Per una panoramica degli approfondimenti su tabelle e set di dati, vedi Panoramica degli approfondimenti sui dati.

Modalità per generare insight sui dati delle tabelle

Quando genera approfondimenti sulle tabelle, BigQuery fornisce due modalità:

Modalità Descrizione Utilizzo
Genera e pubblica (anteprima)

Conserva gli approfondimenti sulla tabella generati in Dataplex Universal Catalog come aspetti dei metadati. Devi disporre delle autorizzazioni necessarie per pubblicare. Quando utilizzi Genera e pubblica, si verificano le seguenti azioni:

  • Memorizza le descrizioni di tabelle e colonne in Dataplex Universal Catalog.
  • Acquisisce query e domande suggerite come aspetti riutilizzabili.
  • Rende gli approfondimenti pubblicati accessibili a tutti gli utenti che dispongono dell'accesso appropriato a Dataplex Universal Catalog, garantendo la condivisione delle conoscenze dell'organizzazione.
  • Consente di modificare e salvare le descrizioni direttamente in Dataplex Universal Catalog.

Utilizza questa modalità per la documentazione dei dati a livello aziendale che persiste ed è riutilizzabile oppure quando crei flussi di lavoro di governance basati sul catalogo.
Genera senza pubblicare

Crea approfondimenti sulle tabelle, come descrizioni, domande in linguaggio naturale e query SQL on demand. Genera senza pubblicare non pubblica gli insight in Dataplex Universal Catalog.

Utilizza questa modalità per un'esplorazione rapida e ad hoc per evitare di sovraccaricare il catalogo.

Prima di iniziare

Gli insight sui dati vengono generati utilizzando Gemini in BigQuery. Per iniziare a generare insight, devi prima configurare Gemini in BigQuery.

Abilita API

Per utilizzare gli approfondimenti sui dati, abilita le seguenti API nel tuo progetto: API Dataplex, API BigQuery e API Gemini in Google Cloud.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Per saperne di più sull'abilitazione dell'API Gemini for Google Cloud, vedi Abilita l'API Gemini for Google Cloud in un progetto Google Cloud .

Ruoli e autorizzazioni

Per creare, gestire e recuperare approfondimenti sui dati, chiedi all'amministratore di concederti i seguenti ruoli IAM (Identity and Access Management):

Per ottenere l'accesso di sola lettura agli approfondimenti generati, chiedi all'amministratore di concederti il seguente ruolo IAM:

Per pubblicare gli approfondimenti sui dati in Dataplex Universal Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM per la risorsa:

Per abilitare le API, chiedi all'amministratore di concederti il seguente ruolo 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. Per vedere quali sono esattamente le autorizzazioni richieste per generare insight, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • dataplex.datascans.create
  • dataplex.datascans.get
  • dataplex.datascans.getData
  • dataplex.datascans.run

Generare insight per una tabella BigQuery

Per generare approfondimenti per le tabelle BigQuery, puoi utilizzare la consoleGoogle Cloud o il tipo di scansione DATA_DOCUMENTATION supportato dall'API DataScans del catalogo universale Dataplex. Queste scansioni generano metadati, query SQL per l'esplorazione dei dati, descrizioni dello schema e riepiloghi a livello di tabella.

Console

Per generare approfondimenti per una tabella BigQuery, devi accedere alla voce della tabella in BigQuery utilizzando BigQuery Studio.

  1. Nella console Google Cloud , vai a BigQuery Studio.

    Vai a BigQuery Studio

  2. Nel riquadro Explorer, seleziona il progetto, il set di dati e poi la tabella per cui vuoi generare approfondimenti.

  3. Fai clic sulla scheda Approfondimenti. Se la scheda è vuota, significa che gli approfondimenti per questa tabella non sono ancora stati generati.

  4. Per generare insight e pubblicarli in Dataplex Universal Catalog, fai clic su Genera e pubblica (Anteprima).

    Per generare insight senza pubblicarli in Dataplex Universal Catalog, fai clic su Genera senza pubblicare.

    Per saperne di più sulle differenze tra le modalità Genera e pubblica e Genera senza pubblicare, consulta Modalità di generazione degli approfondimenti.

  5. Seleziona una regione per generare insight e fai clic su Genera.

    Il completamento dei dati degli approfondimenti richiede alcuni minuti.

    Se sono disponibili risultati della profilazione dei dati pubblicati per la tabella, questi vengono utilizzati per generare approfondimenti. In caso contrario, gli approfondimenti vengono generati in base ai nomi e alle descrizioni delle colonne. Per saperne di più, consulta le best practice per migliorare gli approfondimenti generati.

  6. Nella scheda Insight, esplora le domande in linguaggio naturale generate.

  7. Per visualizzare la query SQL che risponde a una domanda, fai clic sulla domanda.

  8. Per aprire una query in BigQuery, fai clic su Copia in Query.

  9. Per fare domande aggiuntive:

    1. Fai clic su Fai una domanda aggiuntiva. La query si apre in un nuovo data canvas.

    2. Fai clic su Esegui, poi su Esegui query su questi risultati.

    3. Per porre una domanda di follow-up, inserisci un prompt nel campo Linguaggio naturale o modifica l'SQL nell'editor query.

  10. Per generare un nuovo insieme di query, fai clic su Genera approfondimenti e attiva di nuovo la pipeline.

Dopo aver generato insight per una tabella, chiunque disponga dell'autorizzazione dataplex.datascans.getData e dell'accesso alla tabella può visualizzarli.

REST

Per generare insight in modo programmatico, utilizza l'API DataScans di Dataplex Universal Catalog. A questo scopo, completa i seguenti passaggi:

  1. (Facoltativo) Crea una scansione del profilo di dati per la tabella
  2. Genera una scansione dei dati di documentazione dei dati per la tabella BigQuery
  3. Controllare lo stato della scansione della documentazione dei dati
  4. Pubblica i risultati della scansione della documentazione dei dati nella tabella BigQuery

(Facoltativo) Crea una scansione del profilo di dati per la tabella

La presenza di scansioni dei profili dei dati riduce le allucinazioni e le approssimazioni di Gemini, in quanto basano l'output su valori reali presenti nei dati.

Per creare ed eseguire una scansione del profilo dei dati:

  1. Crea una scansione del profilo di dati utilizzando il metodo dataScans.create.

  2. Esegui la scansione del profilo dati utilizzando il metodo dataScans.run. Attendi il completamento dell'esecuzione.

  3. Pubblica i risultati della scansione nella tabella BigQuery allegando le seguenti etichette di profilazione dei dati alla tabella:

    • dataplex-dp-published-scan:DATASCAN_ID
    • dataplex-dp-published-project:PROJECT_ID
    • dataplex-dp-published-location:LOCATION

    Per saperne di più, vedi Aggiungere etichette a tabelle e viste.

Genera una scansione dei dati di documentazione dei dati per la tabella BigQuery

Puoi scegliere di eseguire una scansione gestita standard o una scansione semplificata una tantum.

Opzione A: scansione gestita standard (crea + esegui)

Utilizza questo metodo se vuoi gestire la risorsa di scansione nel tempo.

  1. Crea una scansione dei dati di documentazione dei dati utilizzando il metodo dataScans.create. Puoi personalizzare l'ambito della generazione per includere schema, descrizioni, query o una combinazione utilizzando il parametro generation_scopes:

    • Per generare lo schema, le descrizioni delle tabelle e le query SQL, lascia data_documentation_spec vuoto o imposta generation_scopes su ALL. Ad esempio:

      gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "ALL"
  }
}'

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID del tuo progetto Google Cloud in cui si trova il set di dati
      • LOCATION: la regione in cui viene eseguita la scansione dei dati
      • DATASCAN_ID: un nome univoco fornito per questa scansione
      • DATASET_ID: l'ID del set di dati BigQuery sottoposto a scansione
      • TABLE_ID: l'ID della tabella BigQuery sottoposta a scansione

    • Per generare lo schema, le descrizioni delle tabelle e delle colonne, senza query SQL, imposta generation_scopes su TABLE_AND_COLUMN_DESCRIPTIONS. Ad esempio:

      gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
  }
}'

    • Per generare query SQL senza descrizioni, imposta generation_scopes su SQL_QUERIES. Ad esempio:

      gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "SQL_QUERIES"
  }
}'

  2. Avvia il job di scansione della documentazione dei dati utilizzando il metodo dataScans.run.

    Ad esempio:

    gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans/DATASCAN_ID:run

    Questa richiesta restituisce un ID job univoco insieme allo stato iniziale.

Opzione B: scansione una tantum (semplificata)

Utilizza questo metodo per avviare e completare una scansione in una singola chiamata API. Questo metodo elimina la necessità di chiamare separatamente il metodo run e consente l'eliminazione automatica della risorsa di scansione utilizzando la funzionalità Time to Live (TTL).

Crea e attiva la scansione utilizzando il metodo dataScans.create. Ad esempio:

gcurl -X POST \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?\
dataScanId=DATASCAN_ID" \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/\
    tables/TABLE_ID"
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": { "generation_scopes": "ALL" },
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud in cui si trova il set di dati
  • LOCATION: la regione in cui viene eseguita la scansione dei dati
  • DATASCAN_ID: un nome univoco fornito per questa scansione
  • DATASET_ID: l'ID del set di dati BigQuery sottoposto a scansione
  • TABLE_ID: l'ID della tabella BigQuery in fase di scansione
  • TTL_TIME: la durata in secondi dopo la quale la risorsa di scansione deve essere eliminata automaticamente (ad esempio, 3600 per un'ora)

Controllare lo stato dell'analisi della documentazione dei dati

Controlla il completamento dell'esecuzione del job di scansione utilizzando il metodo dataScans.get.

Utilizza l'ID job per recuperare lo stato del job. Ad esempio:

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN_ID/jobs/JOB_ID

Il job viene completato quando lo stato è SUCCEEDED o FAILURE.

Pubblica i risultati della scansione della documentazione dei dati nella tabella BigQuery

Per pubblicare i risultati della scansione nella tabella BigQuery, collega alla tabella le seguenti etichette di documentazione dei dati:

  • dataplex-data-documentation-published-scan:DATASCAN_ID
  • dataplex-data-documentation-published-project:PROJECT_ID
  • dataplex-data-documentation-published-location:LOCATION

Generare approfondimenti per una tabella esterna BigQuery

BigQuery Data Insights supporta la generazione di insight per le tabelle esterne BigQuery con dati in Cloud Storage. Tu e il account di servizio Dataplex Universal Catalog per il progetto attuale dovete disporre del ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) sul bucket Cloud Storage che contiene i dati. Per saperne di più, consulta Aggiungere un principal a una policy a livello di bucket.

Per generare approfondimenti per una tabella esterna BigQuery, segui le istruzioni descritte nella sezione Generare approfondimenti per una tabella BigQuery di questo documento.

Genera insight per una tabella BigLake

Per generare approfondimenti per una tabella BigLake, segui questi passaggi:

  1. Attiva l'API BigQuery Connection nel tuo progetto.

    Abilita l'API BigQuery Connection

  2. Crea una connessione BigQuery. Per saperne di più, consulta Gestire le connessioni.

  3. Concedi il ruolo IAM Visualizzatore oggetti Storage (roles/storage.objectViewer) al account di servizio corrispondente alla connessione BigQuery che hai creato.

    Puoi recuperare l'ID account di servizio dai dettagli della connessione.

  4. Per generare insight, segui le istruzioni descritte nella sezione Generare insight per una tabella BigQuery di questo documento.

Genera descrizioni di tabelle e colonne

Gemini in BigQuery genera automaticamente le descrizioni di tabelle e colonne quando generi insight sui dati. Puoi modificare queste descrizioni in base alle necessità e poi salvarle nei metadati della tabella. Le descrizioni salvate vengono utilizzate per generare insight futuri.

Controllare la lingua di generazione

Puoi guidare Gemini a generare descrizioni di tabelle e colonne in una lingua specifica. Per farlo, aggiungi una breve direttiva (ad esempio, "Genera descrizioni di tabelle e colonne utilizzando la lingua francese") alla descrizione esistente della tabella prima di generare gli approfondimenti sui dati.

Quando generi insight, Gemini interpreta questa direttiva e produce i metadati nella lingua richiesta. Questo meccanismo funziona perché Gemini utilizza le descrizioni delle tabelle esistenti come contesto quando ne genera di nuove.

Per un elenco delle lingue supportate, consulta Lingue supportate da Gemini.

Genera descrizioni

Per generare descrizioni di tabelle e colonne:

  1. Genera approfondimenti seguendo le istruzioni descritte nella sezione pertinente di questo documento:

  2. Fai clic sulla scheda Schema.

  3. Fai clic su Visualizza descrizioni delle colonne.

    Vengono visualizzate la descrizione della tabella e le descrizioni delle colonne generate.

  4. Per modificare e salvare la descrizione della tabella generata:

    1. Nella sezione Descrizione tabella, fai clic su Salva nei dettagli.

    2. Per sostituire la descrizione attuale con quella generata, fai clic su Copia descrizione suggerita.

    3. Modifica la descrizione della tabella in base alle tue esigenze, quindi fai clic su Salva nei dettagli.

      La descrizione della tabella viene aggiornata immediatamente.

  5. Per modificare e salvare le descrizioni delle colonne generate:

    1. Nella sezione Descrizioni delle colonne, fai clic su Salva nello schema.

      Le descrizioni delle colonne generate vengono inserite nel campo Nuova descrizione per ogni colonna.

    2. Modifica le descrizioni delle colonne in base alle tue esigenze, quindi fai clic su Salva.

      Le descrizioni delle colonne vengono aggiornate immediatamente.

  6. Per chiudere il riquadro di anteprima, fai clic su Chiudi.

Best practice per generare approfondimenti sui dati

Per migliorare la precisione degli approfondimenti generati, segui i seguenti consigli:

  • Fornisci descrizioni complete. Assicurati che sia le tabelle che le colonne all'interno del set di dati abbiano descrizioni chiare e dettagliate.

  • Approfondimenti sul terreno con la profilazione. Se le descrizioni non sono disponibili, assicurati che a ogni tabella del set di dati sia collegata una scansione di profilazione per facilitare la fondatezza degli approfondimenti generati.

  • Definisci esplicitamente le regole. Includi eventuali relazioni o logica aziendale che il modulo approfondimenti utilizza per influenzare la generazione di relazioni all'interno della descrizione della tabella corrispondente.

Informazioni di base per i risultati della profilazione dei dati

Nell'AI generativa, il grounding è la capacità di collegare l'output del modello a fonti di informazione verificabili. Puoi basare gli insight generati sulle tabelle sui risultati della profilazione dei dati. La profilazione dei dati analizza le colonne delle tabelle BigQuery e identifica le caratteristiche statistiche comuni, come i valori tipici dei dati e la distribuzione dei dati.

Quando crei una scansione di profilazione dei dati per una tabella, puoi scegliere di pubblicare i risultati della scansione nelle pagine di BigQuery e Dataplex Universal Catalog nella console Google Cloud . Approfondimenti utilizza i risultati della profilazione dei dati per creare query più accurate e pertinenti eseguendo le seguenti operazioni:

  1. Analizza i risultati della profilazione dei dati per identificare pattern, tendenze o outlier interessanti nei dati.

  2. Genera query incentrate su questi pattern, tendenze o valori anomali per scoprire informazioni.

  3. Convalida le query generate in base ai risultati della profilazione dei dati per garantire che le query restituiscano risultati significativi.

Senza le scansioni di profilazione dei dati, si verificano le seguenti situazioni:

  • Le query generate hanno maggiori probabilità di includere clausole imprecise o produrre risultati privi di significato.

  • Le descrizioni delle colonne generate si basano solo sul nome della colonna.

Assicurati che la scansione di profilazione dei dati per la tabella sia aggiornata e che i risultati siano pubblicati in BigQuery.

Puoi modificare le impostazioni di profilazione dei dati per aumentare le dimensioni del campione e filtrare righe e colonne. Dopo aver eseguito una nuova scansione di profilazione dei dati, rigenera gli approfondimenti.

La qualità degli approfondimenti sul set di dati migliora in modo significativo anche se le tabelle del set di dati contengono risultati di profilazione dei dati.

Aggiungere una descrizione della tabella

Descrizioni dettagliate delle tabelle che descrivono cosa vuoi analizzare nella tabella possono aiutare Gemini in BigQuery a produrre approfondimenti più pertinenti sia per la tabella sia per il set di dati. Dopo aver aggiunto una descrizione della tabella, rigenera gli approfondimenti.

Ad esempio, potresti aggiungere la seguente descrizione a una tabella telco_churn come quella utilizzata in Esempio di approfondimenti sui dati delle tabelle:

This table tracks customer churn data, including subscription details, tenure,
and service usage, to predict customer churn behavior.

Se salvi la descrizione della tabella generata da Gemini, questa descrizione viene utilizzata per generare approfondimenti futuri.

Aggiungere una descrizione della colonna

Le descrizioni delle colonne che spiegano cosa rappresenta ogni colonna o come una colonna si relaziona a un'altra possono migliorare la qualità degli approfondimenti sia per le tabelle che per i set di dati. Dopo aver aggiornato le descrizioni delle colonne nella tabella, rigenera gli approfondimenti.

Ad esempio, puoi aggiungere le seguenti descrizioni a colonne specifiche di una tabella telco_churn come quella utilizzata in Esempio di approfondimenti sui dati delle tabelle:

Per la colonna tenure:

The number of months the customer has been with the service.

Per la colonna churn:

Whether the customer has stopped using the service. TRUE indicates the customer
no longer uses the service, FALSE indicates the customer is active.

Se salvi le descrizioni delle colonne generate da Gemini, queste descrizioni vengono utilizzate per generare insight futuri.

Passaggi successivi