Genera insight sulla tabella

Gli insight sulle tabelle BigQuery ti consentono di comprendere rapidamente la struttura e i contenuti delle tabelle BigQuery standard, delle tabelle esterne BigQuery e delle tabelle BigLake senza scrivere query complesse. Puoi generare query SQL in base a domande in linguaggio naturale, riducendo il tempo e l'impegno necessari per scrivere le query manualmente.

Per una panoramica degli insight su tabelle e set di dati, consulta Panoramica degli insight sui dati.

Modalità per generare insight sui dati delle tabelle

Quando genera insight sulle tabelle, BigQuery offre due modalità:

Modalità Descrizione Utilizzo
Genera e pubblica (Anteprima)

Conserva gli insight sulle tabelle generati in Knowledge Catalog come aspetti dei metadati. Devi disporre delle autorizzazioni necessarie per la pubblicazione. Quando utilizzi Genera e pubblica, vengono eseguite le seguenti azioni:

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

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

Crea insight sulle tabelle, come descrizioni, domande in linguaggio naturale e query SQL on demand. Genera senza pubblicare non pubblica gli insight in Knowledge 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 insight sui dati, abilita le seguenti API nel tuo progetto: API Dataplex, API BigQuery e API Gemini per Google Cloud.

Ruoli richiesti per abilitare le API

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

Abilita le API

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

Ruoli e autorizzazioni

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

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

  • Dataplex DataScan DataViewer (roles/dataplex.dataScanDataViewer) sul progetto contenente le tabelle BigQuery per le quali vuoi visualizzare gli insight.

Per pubblicare insight sui dati in Knowledge Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM sulla 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

Genera insight per una tabella BigQuery

Per generare insight per le tabelle BigQuery, puoi utilizzare la consoleGoogle Cloud o il tipo di scansione DATA_DOCUMENTATION supportato dall'API DataScans di Knowledge Catalog. Queste scansioni generano metadati, query SQL per l'esplorazione dei dati, descrizioni degli schemi e riepiloghi a livello di tabella.

Console

Per generare insight 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 insight.

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

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

    Per generare insight senza pubblicarli in Knowledge 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 insight.

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

    La compilazione degli insight richiede alcuni minuti.

    Se sono disponibili risultati della profilazione dei dati pubblicati per la tabella, questi vengono utilizzati per generare insight. In caso contrario, gli insight vengono generati in base ai nomi e alle descrizioni delle colonne. Per saperne di più, consulta le best practice per migliorare gli insight 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 porre domande aggiuntive:

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

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

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

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

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

REST

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

  1. (Facoltativo) Crea una scansione di profilazione dei dati per la tabella
  2. Genera un'analisi dei dati di documentazione dei dati per la tabella BigQuery
  3. Controlla 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 di profilazione dei dati per la tabella

La presenza di scansioni di profilazione dei dati riduce le allucinazioni e le approssimazioni di Gemini, poiché basano l'output su valori reali presenti nei dati.

Per creare ed eseguire una scansione di profilazione dei dati, segui questi passaggi:

  1. Crea una scansione di profilazione dei dati utilizzando il metodo dataScans.create.

  2. Esegui la scansione di profilazione dei dati utilizzando il metodo dataScans.run. Attendi il completamento dell'esecuzione.

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

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

    Per saperne di più, consulta Aggiungi etichette a tabelle e viste.

Genera un'analisi dei dati della documentazione dei dati per la tabella BigQuery

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

Opzione A: scansione gestita standard (creazione + esecuzione)

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

  1. Crea un'analisi della documentazione dei dati utilizzando il metodo dataScans.create.

Puoi personalizzare l'ambito della generazione in modo da includere schema, descrizioni, query o una combinazione utilizzando il parametro generation_scopes. Facoltativamente, puoi pubblicare questi insight in Knowledge Catalog impostando il parametro catalogPublishingEnabled su true.

  • 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": {
      "generationScopes": "ALL"
      "catalogPublishingEnabled": true
    }
  }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloudin cui si trova il set di dati
    • LOCATION: la regione in cui viene eseguita l'analisi dei dati
    • DATASCAN_ID: un nome univoco che fornisci 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 le descrizioni 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": {
      "generationScopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
      "catalogPublishingEnabled": true
    }
  }'

  • 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": {
      "generationScopes": "SQL_QUERIES"
      "catalogPublishingEnabled": true
    }
  }'

  1. 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 il metodo run separatamente e consente l'eliminazione automatica della risorsa di scansione utilizzando la funzionalità di durata (TTL).

Crea e attiva l'analisi 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": {
    "generationScopes": "ALL",
    "catalogPublishingEnabled": true
  }
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progetto Google Cloudin cui si trova il set di dati
  • LOCATION: la regione in cui viene eseguita l'analisi dei dati
  • DATASCAN_ID: un nome univoco che fornisci 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
  • TTL_TIME: la durata in secondi dopo la quale la risorsa di scansione deve essere eliminata automaticamente (ad esempio, 3600 per un'ora)

Controlla lo stato della scansione della documentazione dei dati

Verifica 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

Genera insight per una tabella esterna BigQuery

Gli insight dei dati BigQuery supportano la generazione di insight per le tabelle esterne di BigQuery con dati in Cloud Storage. Tu e il account di servizio Knowledge Catalog per il progetto corrente dovete disporre del ruolo Storage Object Viewer (roles/storage.objectViewer) sul bucket Cloud Storage che contiene i dati. Per saperne di più, consulta Aggiungi un'entità a una policy a livello di bucket.

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

Genera insight per una tabella BigLake

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

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

    Abilita l'API BigQuery Connection

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

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

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

  4. Per generare insight, segui le istruzioni descritte nella sezione Genera 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 tue esigenze e poi salvarle nei metadati della tabella. Le descrizioni salvate vengono utilizzate per generare insight futuri.

Lingua di generazione del controllo

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

Quando generi insight, Gemini interpreta questa istruzione e produce i metadati nella lingua richiesta. Questo meccanismo funziona perché Gemini utilizza le descrizioni delle tabelle esistenti come contesto durante la generazione di nuove descrizioni.

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

Genera descrizioni

Per generare descrizioni di tabelle e colonne, segui questi passaggi:

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

  2. Fai clic sulla scheda Schema.

  3. Fai clic su Visualizza le 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, segui questi passaggi:

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

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

    2. Modifica le descrizioni delle colonne in base alle tue esigenze e poi 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 la generazione di insight sui dati

Per migliorare la precisione degli insight generati, segui questi consigli:

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

  • Basare gli insight sulla profilazione. Se le descrizioni non sono disponibili, assicurati che una scansione di profilazione sia collegata a ogni tabella del set di dati per facilitare la fondatezza degli insight generati.

  • Definisci esplicitamente le regole. Includi eventuali relazioni o logica di business utilizzate dal modulo degli insight per influenzare la generazione delle relazioni nella descrizione della rispettiva tabella.

Basare gli insight sui risultati della profilazione dei dati

Nell'AI generativa, il grounding è la capacità di collegare l'output del modello a fonti di informazioni verificabili. Puoi basare gli insight generati sulla tabella 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 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 BigQuery e Knowledge Catalog della console Google Cloud . Insights utilizza i risultati della profilazione dei dati per creare query più accurate e pertinenti nel seguente modo:

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

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

Senza le scansioni di profilazione dei dati, si verifica quanto segue:

  • Le query generate hanno maggiori probabilità di includere clausole imprecise o di 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 campionamento e filtrare righe e colonne. Dopo aver eseguito una nuova scansione di profilazione dei dati, rigenera gli insight.

Anche la qualità degli insight sul set di dati migliora in modo significativo se le tabelle nel set di dati hanno risultati di profilazione dei dati.

Aggiungi una descrizione della tabella

Le descrizioni dettagliate delle tabelle che descrivono ciò che vuoi analizzare nella tabella possono aiutare Gemini in BigQuery a produrre insight più pertinenti sia per gli insight sulle tabelle che per quelli sui set di dati. Dopo aver aggiunto una descrizione della tabella, rigenera gli insight.

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

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 verrà utilizzata per generare insight futuri.

Aggiungi una descrizione della colonna

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

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

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 vengono utilizzate per generare insight futuri.

Gestisci gli insight generati

Dopo aver generato gli insight per una tabella, puoi gestirli, aggiornarli o eliminarli in Knowledge Catalog. Per saperne di più, consulta Gestisci gli insight sulle tabelle.

Passaggi successivi