Utilizzare l'agente di data engineering per creare e modificare pipeline di dati

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per fornire feedback o porre domande su questa funzionalità di anteprima, contatta [e-mail]

L'agente di data engineering ti consente di utilizzare Gemini in BigQuery per creare, modificare e gestire pipeline di dati per caricare ed elaborare i dati in BigQuery. Con l'agente di data engineering, puoi utilizzare prompt in linguaggio naturale per generare pipeline di dati da varie origini dati o adattare le pipeline di dati esistenti in base alle tue esigenze di data engineering. L'agente di data engineering ha le seguenti funzionalità:

• Linguaggio naturale per la creazione di pipeline: l'agente utilizza Gemini per comprendere i tuoi dati e interpretare le istruzioni in linguaggio semplice. Puoi utilizzare istruzioni in linguaggio semplice per chiedere all'agente di data engineering di creare o modificare le pipeline di dati.

• Integrazione di Dataform: l'agente genera e organizza il codice della pipeline necessario in file SQLX all'interno di un repository Dataform. L'agente opera nell'area di lavoro Dataform, quindi le pipeline Dataform sono disponibili automaticamente per l'agente.

• Istruzioni personalizzate per l'agente: crea istruzioni per l'agente in linguaggio semplice per definire regole personalizzate per l'agente di data engineering. Le istruzioni dell'agente sono persistenti in tutta l'organizzazione e possono essere utili per applicare regole a livello di organizzazione, come convenzioni di denominazione o guide di stile.

• Convalida della pipeline: l'agente convalida il codice generato per assicurarsi che le pipeline di dati siano funzionali.

Puoi utilizzare prompt in linguaggio naturale con l'agente di data engineering per creare file SQLX di tabelle, viste, asserzioni, dichiarazioni e operazioni. Ad esempio, puoi utilizzare l'agente di data engineering per:

• Caricare dati da origini dati esterne come Cloud Storage in vari formati, ad esempio CSV, AVRO o PARQUET.
• Creare o utilizzare routine BigQuery esistenti (funzioni definite dall'utente) per eseguire analisi e trasformazioni personalizzate sui dati.
• Definire linee guida riutilizzabili per l'agente in linguaggio naturale.

Per altri esempi di prompt che puoi utilizzare con l'agente di data engineering, consulta Prompt di esempio.

Limitazioni

L'agente di data engineering presenta le seguenti limitazioni:

• L'agente di data engineering è un'offerta pre-GA e non è destinato all'uso in produzione.
• L'agente di data engineering non supporta i comandi in linguaggio naturale per i seguenti tipi di file:
  • Notebooks
  • Preparazione dei dati
  • JavaScript all'interno di qualsiasi SQLx
• L'agente di data engineering non può eseguire pipeline. Gli utenti devono esaminare ed eseguire o pianificare le pipeline.
• L'agente di data engineering non può convalidare SQL che dipende da risorse intermedie inesistenti senza l'invocazione completa della pipeline (attivata dall'utente).
• L'agente di data engineering non può cercare link web o URL forniti tramite istruzioni o prompt diretti.
• Quando importi file in un file di istruzioni dell'agente, la sintassi di importazione @ supporta solo i percorsi che iniziano con ./, / o una lettera.
• La funzionalità di anteprima dei dati è supportata solo per tabelle, dichiarazioni o query con il flag hasOutput impostato su true.

Aree geografiche supportate

Gemini in BigQuery viene fornito dalle seguenti regioni:

Americhe

• Iowa (us-central1)

Europa

• Finlandia (europe-north1)
• Francoforte (europe-west3)

Modificare la regione di trattamento

Puoi modificare la regione di trattamento per l'agente di data engineering utilizzando una delle seguenti opzioni:

Pipeline BigQuery

Se utilizzi le pipeline BigQuery, puoi aggiornare la regione di trattamento impostando la regione predefinita per gli asset di codice. Per saperne di più, consulta Impostare la regione predefinita per gli asset di codice.

Se la regione predefinita non è impostata, l'agente di data engineering tratta i dati a livello globale.

Dataform

Se utilizzi Dataform, puoi aggiornare la regione di elaborazione modificando il valore defaultLocation nel file delle impostazioni del workflow Dataform o workflow_settings.yaml. Per saperne di più, consulta Configurare le impostazioni del flusso di lavoro Dataform.

Se il valore defaultLocation non è impostato, l'agente di data engineering tratta i dati a livello globale.

In che modo l'agente di data engineering utilizza i tuoi dati

Per produrre risposte di qualità superiore, l'agente di data engineering può recuperare dati e metadati aggiuntivi da BigQuery e Dataplex Universal Catalog, incluse righe di esempio dalle tabelle BigQuery e profili di scansione dei dati generati in Dataplex Universal Catalog. Questi dati non vengono utilizzati per addestrare l'agente di data engineering e vengono utilizzati solo durante le conversazioni dell'agente come contesto aggiuntivo per informare le risposte dell'agente.

Prima di iniziare

Assicurati che Gemini in BigQuery sia abilitato per il tuo Google Cloud progetto. Per saperne di più, consulta Configurare Gemini in BigQuery.

Devi anche abilitare l'API Gemini Data Analytics.

Ruoli necessari per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare l'agente di data engineering, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Editor di codice Dataform (roles/dataform.codeEditor)
• Utente job BigQuery (roles/bigquery.jobuser)

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.

Generare una pipeline di dati con l'agente di data engineering

Per utilizzare l'agente di data engineering in BigQuery, seleziona una delle seguenti opzioni:

Pipeline BigQuery

Puoi utilizzare l'agente di data engineering nell'interfaccia delle pipeline BigQuery procedendo nel seguente modo:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, fai clic su arrow_drop_down Crea nuovo > Pipeline.

3. Seleziona un'opzione per le credenziali di esecuzione e fai clic su Inizia. Queste credenziali non vengono utilizzate dall'agente, ma sono necessarie per eseguire la pipeline di dati generata.

4. Fai clic su Prova l'esperienza dell'agente per la pipeline di dati.

5. Nel campo Chiedi all'agente, inserisci un prompt in linguaggio naturale per generare una pipeline di dati. Ad esempio:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Dopo aver inserito un prompt, fai clic su Invia.

6. L'agente di data engineering genera una pipeline di dati in base al prompt.

La pipeline di dati generata dall'agente di data engineering è una bozza proposta di una pipeline di dati. Puoi fare clic su un nodo della pipeline per esaminare la query SQLX generata. Per applicare la pipeline di dati suggerita dall'agente, fai clic su Applica.

Dataform

Puoi utilizzare l'agente di data engineering in Dataform procedendo nel seguente modo:

1. Vai alla pagina Dataform.

   Vai a Dataform

2. Seleziona un repository.

3. Seleziona o crea un'area di lavoro di sviluppo.

4. Nell'area di lavoro, fai clic su Chiedi all'agente.

5. Nel prompt Chiedi all'agente visualizzato, inserisci un prompt in linguaggio naturale per generare una pipeline di dati. Ad esempio:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Dopo aver inserito un prompt, fai clic su Invia.

Una volta inviato il prompt, l'agente di data engineering genera una pipeline di dati e modifica i file SQLX di Dataform in base al prompt. L'agente applica queste modifiche direttamente ai file dell'area di lavoro.

Esaminare una pipeline di dati

In una pipeline di dati generata dall'agente di data engineering, puoi fare clic su un nodo della pipeline per esaminarlo.

• La scheda Configurazione mostra la query SQLX generata associata al nodo.
• La scheda Anteprima dati mostra la tabella di input e output del file. Puoi visualizzare un'anteprima della trasformazione dei dati tramite questo nodo facendo clic su Esegui attività per eseguire l'attività con o senza dipendenze.

Modificare una pipeline di dati

Puoi modificare la pipeline di dati utilizzando l'agente di data engineering facendo clic su Chiedi all'agente e inserendo un prompt che suggerisce una modifica alla pipeline di dati.

Esamina le modifiche proposte dall'agente di data engineering, quindi fai clic su Applica per applicarle.

Puoi anche modificare manualmente una query SQLX selezionando un nodo della pipeline e poi facendo clic su Apri.

Creare istruzioni per l'agente di data engineering

Le istruzioni dell'agente sono istruzioni in linguaggio naturale per l'agente di data engineering che ti consentono di archiviare istruzioni persistenti in modo che l'agente segua un insieme di regole personalizzate e predefinite. Utilizza le istruzioni dell'agente se vuoi che i risultati dell'agente siano coerenti in tutta l'organizzazione, ad esempio con le convenzioni di denominazione o per applicare una guida di stile.

Puoi creare un file di contesto GEMINI.MD come file di istruzioni dell'agente per l'agente di data engineering. Puoi creare file di istruzioni dell'agente da utilizzare nel tuo workspace locale oppure puoi utilizzare gli stessi file di istruzioni in più pipeline di dati utilizzando un repository esterno.

Per creare istruzioni dell'agente:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. Nel riquadro Istruzioni per la pipeline, fai clic su Crea file di istruzioni.

3. Nel file GEMINI.MD visualizzato, inserisci le istruzioni in linguaggio naturale.

   L'esempio seguente mostra un file di istruzioni dell'agente con diverse regole:

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Fai clic su Salva.

Per informazioni su come strutturare al meglio i file di istruzioni dell'agente, consulta Best practice per i file di istruzioni dell'agente.

Caricare le istruzioni dell'agente da un repository esterno

Puoi specificare un insieme di istruzioni dell'agente da riutilizzare in più pipeline di dati collegando un repository esterno:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. In Repository esterno, seleziona Usa le istruzioni del repository esterno.
3. Nei campi forniti, specifica un repository che contiene le istruzioni dell'agente che vuoi utilizzare con la pipeline di dati.
4. Fai clic su Salva.

Importare altri file locali come istruzioni dell'agente

Puoi anche importare altri file di istruzioni per l'agente di data engineering nel file GEMINI.md utilizzando la sintassi @file.md. Per saperne di più, consulta Processore di importazione della memoria.

Risolvere i problemi relativi agli errori della pipeline di dati

Se riscontri errori durante la generazione della pipeline di dati, verifica di aver completato tutti i prerequisiti necessari per eseguire l'agente di data engineering. Per saperne di più, consulta Prima di iniziare.

Se la pipeline di dati generata riscontra errori, puoi chiedere all'agente di data engineering di diagnosticare eventuali errori della pipeline di dati e proporre consigli per la risoluzione dei problemi seguendo questi passaggi:

1. Nella pipeline o nell'area di lavoro di sviluppo, fai clic sulla scheda Esecuzioni.

2. Nell'elenco delle esecuzioni, trova l'esecuzione della pipeline di dati non riuscita. Puoi identificare le esecuzioni non riuscite nella colonna Stato dell'esecuzione.

   

3. Passa il mouse sopra l'icona, quindi fai clic su Analizza. L'agente di data engineering esegue un'analisi sull'esecuzione della pipeline di dati per rilevare eventuali errori.

   

4. Al termine dell'analisi, l'agente di data engineering genera un report nella sezione Osservazioni e ipotesi. Questo report include:

   • Osservazioni e punti dati estratti dai log di esecuzione della pipeline di dati
   • Cause probabili dell'errore
   • Un insieme di passaggi o consigli pratici per risolvere il problema identificato

Con il report di risoluzione dei problemi dell'agente di data engineering, puoi implementare manualmente i consigli. Puoi anche chiedere all'agente di data engineering di applicare la correzione seguendo questi passaggi:

1. Copia i suggerimenti nel report di risoluzione dei problemi.
2. Torna all'agente di data engineering:
   1. Se utilizzi le pipeline BigQuery, vai alla pagina delle pipeline e poi fai clic su Chiedi all'agente.
   2. Se utilizzi Dataform, fai clic su Chiedi all'agente.
3. Incolla i suggerimenti nel prompt e chiedi all'agente di data engineering di apportare le correzioni direttamente alla pipeline di dati.
4. Fai clic su Invia.

Prompt di esempio

Le sezioni seguenti mostrano alcuni prompt di esempio che puoi utilizzare con l'agente di data engineering per sviluppare la pipeline di dati.

Aggregare i dati esistenti in una nuova tabella

Con questo prompt, l'agente di data engineering utilizza lo schema e gli esempi per dedurre il raggruppamento dei dati per chiave. In genere, l'agente configura una nuova tabella con descrizioni di tabelle e colonne.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

Aggiungere controlli di qualità dei dati a una tabella esistente

Con questo prompt, l'agente deduce controlli di qualità ragionevoli per la tabella in base allo schema e agli esempi. Puoi anche aggiungere alcune asserzioni di opinione come parte del prompt.

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

Creare una nuova colonna derivata e aggiungere controlli di qualità dei dati alla nuova tabella

Il seguente prompt mostra come aggiungere una tabella e una colonna e specificare contemporaneamente i controlli di qualità per la tabella.

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

Creare funzioni definite dall'utente come parte della definizione del modello

L'agente di data engineering può anche configurare il DDL per creare funzioni definite dall'utente. Anche se l'agente non creerà effettivamente la funzione definita dall'utente, puoi crearla eseguendo la pipeline di dati. Queste funzioni definite dall'utente possono essere utilizzate nelle definizioni dei modelli nella pipeline di dati.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Best practice

Le sezioni seguenti suggeriscono le best practice per lavorare con l'agente di data engineering e Dataform.

Best practice con l'agente di data engineering

Utilizza le istruzioni dell'agente per le richieste comuni. Se applichi spesso determinate tecniche o se apporti spesso le stesse correzioni all'agente, utilizza le istruzioni dell'agente come posizione centralizzata per archiviare istruzioni e richieste comuni.

Fornisci all'agente più contesto. Puoi fornire all'agente un contesto aggiuntivo da Dataplex Universal Catalog collegando i termini del glossario a tabelle e colonne BigQuery e generando scansioni del profilo dei dati. I termini del glossario possono essere utilizzati per taggare le colonne che richiedono un contesto aggiuntivo, ad esempio le colonne contenenti informazioni che consentono l'identificazione personale (PII) che richiedono istruzioni di gestione speciali, o per identificare le colonne corrispondenti con nomi diversi nelle tabelle. Le scansioni del profilo dei dati forniscono all'agente una migliore comprensione della distribuzione dei dati all'interno delle colonne di una tabella e possono aiutarlo a creare asserzioni di qualità dei dati più specifiche. Per saperne di più, consulta Informazioni sulla profilazione dei dati.

Scrivi con chiarezza. Indica chiaramente la tua richiesta ed evita di essere vago. Se possibile, fornisci le origini dati di origine e di destinazione quando inserisci un prompt, come mostrato nell'esempio seguente:

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Fornisci richieste dirette e con ambito specifico. Fai una domanda alla volta e mantieni i prompt concisi. Per i prompt con più di una domanda, puoi elencare ogni parte distinta della domanda per migliorare la chiarezza, come mostrato nell'esempio seguente:

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Fornisci istruzioni esplicite ed enfatizza i termini chiave. Puoi aggiungere enfasi ai termini o ai concetti chiave nei prompt ed etichettare determinati requisiti come importanti, come mostrato nell'esempio seguente:

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Specifica l'ordine delle operazioni. Per le attività ordinate, puoi strutturare il prompt in elenchi, in cui gli elementi elencati sono suddivisi in passaggi piccoli e mirati, come mostrato nell'esempio seguente:

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id
  3. Load the final result into the reporting.customer_orders table.

Perfeziona ed esegui l'iterazione. Continua a provare frasi e approcci diversi per vedere quali producono i risultati migliori. Se l'agente genera SQL non valido o altri errori, guidalo utilizzando esempi o documentazione pubblica.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).

Best practice per i file di istruzioni dell'agente

Crea file di istruzioni dell'agente per personalizzare l'agente di data engineering in base alle tue esigenze. Quando utilizzi le istruzioni dell'agente, ti consigliamo di:

• Tutti i percorsi dei file in Dataform sono relativi alla radice del repository. Utilizza i percorsi relativi per qualsiasi sintassi @file.md per importare correttamente le istruzioni in GEMINI.md.
• I file importati in GEMINI.md possono a loro volta contenere importazioni, che possono creare una struttura nidificata. Per evitare la ricorsione infinita, GEMINI.md ha una profondità di importazione massima di cinque livelli.
• Per condividere le istruzioni tra le pipeline di dati, archiviale in un repository Dataform centrale e collegale al repository Dataform di lavoro. Puoi utilizzare le istruzioni locali per sostituire le regole centrali per un comportamento specifico della pipeline.
• L'utilizzo di intestazioni ed elenchi nel file di istruzioni dell'agente può aiutarti a organizzare e chiarire le istruzioni per l'agente di data engineering.
• Assegna nomi di file significativi e raggruppa le istruzioni simili in un file. Organizza le regole in modo logico per categoria, funzionalità o funzionalità utilizzando le intestazioni Markdown.
• Per evitare istruzioni in conflitto, definisci chiaramente le condizioni specifiche in cui si applica ogni istruzione.
• Esegui l'iterazione e perfeziona i prompt e il flusso di lavoro. Il comportamento dell'agente cambia nel tempo con i rollout dell'agente e gli upgrade del modello, pertanto ti consigliamo di eseguire l'iterazione delle regole con prompt diversi per identificare le aree che potrebbero richiedere miglioramenti. Mantieni il file delle regole sincronizzato con eventuali modifiche alla pipeline di dati.

L'esempio seguente mostra un file di istruzioni dell'agente denominato GEMINI.md che utilizza le nostre best practice per un utilizzo efficace dell'agente di data engineering:

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md