QueryData per AlloyDB utilizzando Gemini Data Analytics

1. Introduzione

Questo codelab fornisce una guida su come iniziare a utilizzare QueryData per AlloyDB e utilizzarlo per generare istruzioni SQL accurate e prevedibili dall'input in linguaggio naturale nelle applicazioni agentiche.

Prerequisiti

• Una conoscenza di base della console Google Cloud
• Competenze di base nell'interfaccia a riga di comando e in Cloud Shell

Cosa imparerai a fare

• Come creare un cluster AlloyDB e importare dati di esempio
• Come attivare l'API di accesso ai dati di AlloyDB
• Come attivare QueryData per AlloyDB
• Come generare modelli
• Come utilizzare la ricerca con facet
• Come utilizzare QueryData con gli agenti AI

Che cosa ti serve

• Un account Google Cloud e un progetto Google Cloud
• Un browser web come Chrome che supporta la console Google Cloud e Cloud Shell

2. Configurazione e requisiti

Configurazione del progetto

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

In alternativa, puoi premere G e poi S. Questa sequenza attiverà Cloud Shell se ti trovi nella console Google Cloud o utilizza questo link.

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Prima di iniziare

Abilita l'API

Tieni presente che alcune risorse che attivi comportano dei costi. In circostanze normali, se l'istanza AlloyDB e la VM di calcolo vengono eliminate al termine del lab, il costo di tutte le risorse non supererà i 5 $. Ti consigliamo di controllare la fatturazione e assicurarti che l'esercizio sia accettabile per te.

Per utilizzare AlloyDB, Compute Engine, servizi di rete e Vertex AI, devi abilitare le rispettive API nel tuo progetto Google Cloud.

All'interno del terminale Cloud Shell, assicurati che l'ID progetto sia configurato:

gcloud config get-value project

Dovresti vedere l'ID progetto nell'output:

student@cloudshell:~ (test-project-001-402417)$ gcloud config get-value project
Your active configuration is: [cloudshell-23188]
test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$

Imposta la variabile di ambiente PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

Attiva tutti i servizi necessari:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com

Output previsto:

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. Esegui il deployment di AlloyDB

Crea il cluster AlloyDB e l'istanza principale. Puoi eseguirne il deployment utilizzando uno script preparato che eseguirà il deployment di tutte le risorse necessarie oppure puoi farlo passo dopo passo seguendo la documentazione.

Eseguire il deployment di AlloyDB utilizzando lo script automatizzato

Questo approccio utilizza uno script automatizzato per il deployment del cluster AlloyDB e fornisce le informazioni necessarie per iniziare a lavorare con le risorse di cui è stato eseguito il deployment.

Lo script è progettato per funzionare con la rete predefinita in cui crea i componenti necessari per l'IP privato di AlloyDB. Se hai una configurazione di rete personalizzata e prevedi di utilizzare nomi e allocazioni di cluster diversi, utilizza una guida della documentazione di AlloyDB.

Nel terminale Cloud Shell, esegui il comando per clonare lo script di deployment dal repository.

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-querydata"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

Esegui lo script di deployment.

./deploy_alloydb.sh --public-ip

L'esecuzione dello script richiede un po' di tempo, in genere circa 5-7 minuti, e il deployment del cluster AlloyDB e di un'istanza principale con IP pubblico e privato. L'IP pubblico è disponibile solo per le reti autorizzate o utilizzando il proxy di autenticazione AlloyDB. Per saperne di più sull'IP pubblico, consulta la documentazione. Come output, lo script deve fornire informazioni sul cluster AlloyDB di cui è stato eseguito il deployment. Tieni presente che la password sarà diversa. Registrala da qualche parte per un uso futuro.

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------
 

Puoi anche visualizzare il nuovo cluster e l'istanza primaria nella console web.

5. Prepara il database

Per utilizzare le funzioni e gli operatori di AI, devi abilitare l'integrazione di Vertex AI, l'API di accesso ai dati e creare un database per il set di dati di esempio.

Concedere le autorizzazioni necessarie ad AlloyDB

Aggiungi le autorizzazioni Vertex AI al service agent AlloyDB.

Apri un'altra scheda di Cloud Shell utilizzando il segno "+" in alto.

Nella nuova scheda di Cloud Shell, esegui:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Output console previsto:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:[e-mail]
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1
 

Abilita l'API Data Access

Devi abilitare l'API Data Access sul cluster AlloyDB per poter utilizzare gli strumenti MCP come execute_sql.

Nella stessa scheda del terminale, esegui.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

Abilita l'autenticazione IAM

Utilizzeremo l'autenticazione IAM per i nostri strumenti agentici e sarà necessario abilitare l'autenticazione IAM sull'istanza e aggiungerti come utente del database. Prima di attivare l'autenticazione IAM a livello di istanza, attendi il completamento del passaggio precedente di attivazione dell'API di accesso ai dati. Lo stato dell'istanza deve essere verde.

Iniziamo attivando IAM a livello di istanza. Nella stessa scheda del terminale, esegui.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags password.enforce_complexity=on,alloydb.iam_authentication=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Aggiungiti come utente AlloyDB:

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED

Chiudi la scheda con il comando di esecuzione "exit":

exit

Connettersi ad AlloyDB Studio

Nei capitoli seguenti, tutti i comandi SQL che richiedono la connessione al database possono essere eseguiti in AlloyDB Studio. T

Vai alla pagina Cluster in AlloyDB per PostgreSQL.

Apri l'interfaccia della console web per il cluster AlloyDB facendo clic sull'istanza principale.

Quindi, fai clic su AlloyDB Studio a sinistra:

Scegli il database postgres e l'autenticazione IAM. A questo punto, fai clic sul pulsante "Autentica".

Si aprirà l'interfaccia di AlloyDB Studio. Per eseguire i comandi nel database, fai clic sulla scheda "Query senza titolo" a destra.

Si apre l'interfaccia in cui puoi eseguire i comandi SQL

Crea database

Guida rapida alla creazione di database.

Nell'editor di AlloyDB Studio, esegui questo comando.

Crea database:

CREATE DATABASE quickstart_db

Output previsto:

Statement executed successfully

Connettiti a quickstart_db

Verifica che il database sia stato creato connettendoti. Riconnettiti allo studio utilizzando il pulsante per cambiare utente/database.

Seleziona il nuovo database quickstart_db dall'elenco a discesa e utilizza la stessa autenticazione IAM.

Si aprirà una nuova connessione in cui potrai lavorare con gli oggetti del database quickstart_db. Qui potrai esaminare lo schema e i dati importati e lavorare con i set di contesto QueryData.

6. Dati di esempio

Ora devi creare oggetti nel database e caricare i dati. Utilizzerai un set di dati fittizio della società di spedizioni Cymbal. Contiene dati fittizi su merci, camion, richieste e viaggi in camion, nonché su autisti fittizi.

Crea un bucket di archiviazione

Utilizzerai Google SDK (gcloud) per importare i dati dal repository clonato nel database AlloyDB. A questo scopo, devi creare un bucket Cloud Storage e concedere l'accesso al service account AlloyDB. In alternativa, puoi sempre provare a farlo utilizzando la console web, come descritto nella documentazione.

Nel terminale Google Cloud Shell esegui:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

Carica dati

Il passaggio successivo consiste nel caricare i dati. Il dump SQL compresso si trova nella cartella del repository clonato. Il seguente comando presuppone che tu abbia utilizzato la tua home directory come punto di partenza quando hai clonato il repository nel passaggio precedente durante la creazione del cluster AlloyDB.

Copia il dump SQL compresso nel nuovo bucket di archiviazione:

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

Quindi, carica i dati nel database quickstart_db:

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

Il comando caricherà il set di dati di esempio nel database quickstart_db. Puoi verificare le tabelle e i record utilizzando AlloyDB Studio.

7. Utilizzare Data Agent

Iniziamo da un agente AI di esempio creato utilizzando Google ADK per Python e connettendoci alla nostra istanza AlloyDB utilizzando MCP Toolbox per i database.

Installa MCP Toolbox per database

MCP Toolbox for Databases è un progetto open source che fornisce il supporto MCP per più motori di database, tra cui AlloyDB per PostgreSQL. Puoi leggere informazioni su MCP Toolbox nella documentazione.

Devi scaricare l'ultima versione del software per la tua piattaforma. Per l'ultima versione, consulta la pagina delle release. Il seguente esempio mostra come scaricare la versione 31 di MCP Toolbox in Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
export VERSION=0.31.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Devi preparare un file di configurazione per la toolbox. Nella directory corrente è presente un file tools.yaml.example di esempio e prepareremo il file tools.yaml sostituendo due segnaposto con l'ID progetto e la regione.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    tools.yaml.example > tools.yaml

Avvia MCP Toolbox for Databases

Ora puoi avviare la casella degli strumenti MCP con il file di configurazione preparato.

Apri una nuova scheda in Google Cloud Shell premendo il pulsante "+" nella parte superiore dell'interfaccia di Google Cloud Shell.

Nella nuova scheda, passa alla directory con il file binario della toolbox e il file di configurazione tools.yaml e avvia il server MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config tools.yaml

Nell'output dovresti vedere "Server ready to serve!" (Server pronto a servire), simile a quanto segue.

2026-03-30T10:28:03.614374-04:00 INFO "Initialized 1 sources: cymbal-logistics-sql-source"
2026-03-30T10:28:03.614517-04:00 INFO "Initialized 0 authServices: "
2026-03-30T10:28:03.614531-04:00 INFO "Initialized 0 embeddingModels: "
2026-03-30T10:28:03.614657-04:00 INFO "Initialized 2 tools: execute_sql_tool, list_cymbal_logistics_schemas_tool"
2026-03-30T10:28:03.614711-04:00 INFO "Initialized 1 toolsets: default"
2026-03-30T10:28:03.614723-04:00 INFO "Initialized 0 prompts: "
2026-03-30T10:28:03.614779-04:00 INFO "Initialized 1 promptsets: default"
2026-03-30T10:28:03.616214-04:00 INFO "Server ready to serve!"

Controlla il codice sorgente dell'agente

Nella prima scheda della cartella del repository clonato, esamina il codice dell'agente utilizzando l'editor di Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/agent.py

Nell'agente è presente una sezione per il server MCP di Google Cloud per AlloyDB. Forniamo un endpoint come MCP_SERVER_URL, autenticazione, ID progetto e lo aggiungiamo al set di strumenti MCP.

MCP_SERVER_URL = "http://127.0.0.1:5000"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

mcp_toolset = ToolboxToolset(
    server_url=MCP_SERVER_URL,
)

Nel codice dell'agente, il set di strumenti MCP è incluso come parametro tools per l'agente. Inoltre, i nomi del cluster e dell'istanza, la regione e il database sono variabili per il prompt dell'agente.

MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    """,
    tools=[mcp_toolset],
)

Dopo aver esaminato il codice, torna al terminale premendo il pulsante "Apri terminale" in alto a destra nella finestra dell'editor.

Avvia l'agente

Ora puoi avviare l'agente in modalità interattiva utilizzando l'interfaccia web di Google ADK. L'interfaccia web dell'ADK offre un modo pratico per testare e risolvere i problemi relativi ai flussi di lavoro degli agenti.

Innanzitutto, installiamo tutti i pacchetti richiesti per Python utilizzando il gestore di pacchetti uv.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
uv sync

Una volta installati tutti i pacchetti, devi aggiungere un file .env alla directory dell'agente per indicare di utilizzare Vertex AI per tutte le comunicazioni con i modelli di AI.

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

A questo punto, puoi avviare l'agente.

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Dovresti vedere un output simile al seguente con l'endpoint come http://127.0.0.1:8000 .

Puoi fare clic su questo URL in Cloud Shell e si aprirà una finestra di anteprima in una scheda separata del browser, in cui scegli data_agent dall'elenco a discesa a sinistra.

Nell'interfaccia web dell'ADK puoi pubblicare le tue domande in basso a destra e visualizzare il flusso di esecuzione completo, incluse le tracce per ogni passaggio sul lato destro.

8. Testare NL2SQL senza QueryData per AlloyDB

L'agente ti consente di porre domande in formato libero utilizzando il linguaggio naturale e utilizzerà MCP Toolbox per database come strumento per rispondere alle domande. Le domande vengono pubblicate in basso a destra e la risposta con tutte le chiamate agli strumenti viene visualizzata in alto.

Stai lavorando con i dati operativi di una società di spedizioni che contiene informazioni su richieste di spedizione, camion, autisti e viaggi effettuati dagli autisti. La prima domanda riguarda il numero di viaggi eseguiti a febbraio 2026.

Nel campo di immissione in basso a destra, digita quanto segue e premi Invio.

Hello, can you tell me how many trips we've done in February?

L'agente eseguirà più chiamate di strumenti per identificare le tabelle giuste nello schema utilizzando list_cymbal_logistics_schemas_tool e execute_sql_tool eseguendo le varie istruzioni SQL per ottenere i dati corretti.

Alla fine produrrà il risultato corretto dopo aver creato la query appropriata ed eseguita sul database.

Abbiamo completato 108 viaggi a febbraio 2026. Dai nostri dati risulta che non sono stati programmati o completati viaggi a febbraio 2025.

Puoi vedere cosa fa ogni chiamata allo strumento facendo clic sull'esecuzione dello strumento. Ad esempio, ecco la query eseguita per ottenere i risultati.

Prova altre richieste semplici utilizzando l'interfaccia web dell'ADK e scopri come esegue query diverse per ottenere i risultati.

Interrompi l'agente premendo ctrl+c nel terminale. Puoi chiudere la scheda del browser con l'interfaccia web dell'ADK.

Puoi anche interrompere MCP Toolbox nella seconda scheda premendo la stessa scorciatoia da tastiera ctrl+c e chiudere la seconda scheda.

Nel passaggio successivo creeremo il contesto QueryData per migliorare la risposta e le prestazioni di NL2SQL.

9. Crea QueryData ContextSet

Nel passaggio precedente hai visto che il modello di AI ha effettuato più chiamate allo schema informativo del database per capire quali tabelle e colonne utilizzare per creare la query SQL. Per migliorare le prestazioni, l'accuratezza e rendere il risultato più prevedibile, aggiungeremo il contesto QueryData che definisce quale query deve essere eseguita in risposta a una determinata richiesta.

Crea modelli mirati

QueryData ContextSet è un file JSON con modelli di query e sfaccettature che forniscono i dati e le indicazioni necessari al modello di AI per utilizzare la query SQL o le parti di query SQL corrette per raggiungere gli obiettivi richiesti in base ai pattern di query e alla struttura dei dati.

Si parte da un modello mirato. Crea un file utilizzando un editor di Cloud Shell. Nel terminale Cloud Shell, esegui.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

e inserisci il modello per la query in linguaggio naturale che abbiamo utilizzato nel capitolo precedente: "Quanti viaggi abbiamo effettuato a febbraio?"

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a given month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ]
}

Quindi scarica il modello sul tuo computer da Cloud Shell utilizzando il pulsante di download.

Carica set di contesti QueryData

Per utilizzare i nostri set di contesti QueryData, dobbiamo caricarli nel nostro database.

Apri AlloyDB Studio. Nel riquadro a sinistra in basso vedrai QueryData Context e tre puntini.

Fai clic sui tre puntini e scegli Crea contesto. Si aprirà una finestra di dialogo in cui inserire

• Nome: cymbal_context_set
• Descrizione: Cymbal Logistic Query Data
• Carica il file di contesto: fai clic sul pulsante "Browse" e scegli il file JSON con il ContextSet QueryData.

Quando premi il pulsante Salva, potrebbe essere necessario un po' di tempo per inizializzare l'archiviazione del contesto se lo fai per la prima volta.

Dovresti essere in grado di visualizzare il contesto scaricato e, se fai clic sui tre pulsanti verticali a destra, vedrai le azioni disponibili. Nel capitolo successivo inizieremo dall'azione "Contesto del test".

10. Testa il set di contesti QueryData

Modello di test

Utilizza l'azione "Test context" per testare il nostro contesto in AlloyDB Studio. Quando fai clic su "Test context" (Testo di prova), si apre una nuova finestra dell'editor di AlloyDB Studio con il titolo "cymbal_context_set" e l'invito alla generazione di SQL di Gemini con il titolo "Generate SQL using QueryData context: cymbal_context_set". Fai clic sulla generazione di SQL e digita

Hello, can you tell me how many trips we've done in February?

Quando viene generato l'SQL, premi il pulsante "Insert".

Vedrai esattamente la stessa query che abbiamo inserito nel nostro modello di contesto in precedenza.

-- How many trips we've done in February?
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'

Prova a sostituire il mese con "January" e controlla l'istruzione SQL generata. Utilizzerà il mese come parametro per l'intent parametrizzato e modificherà automaticamente l'istruzione SQL.

Creare sfaccettature QueryData

Abbiamo provato un modello per una query e funziona quando sappiamo che tipo di richiesta dell'utente ci aspettiamo. Tuttavia, a volte è utile guidare solo una parte di una query, ad esempio una condizione o un filtro, quando preferiamo che venga utilizzato un determinato ordine o una clausola particolare per un intento ridefinito.

Ad esempio, se chiediamo di restituire i dati relativi all'"ultimo mese", vogliamo ottenere il report per l'ultimo mese di calendario dal 1° all'ultimo giorno del mese, ma non per gli ultimi 30 giorni.

Possiamo aggiungere queste sfaccettature come snippet SQL alla configurazione ContextSet insieme al modello aggiunto in precedenza. Apri querydata_cymbal_contextset.json.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

e aggiungi le sfaccettature dopo i modelli già esistenti. I contenuti risultanti nel file dovrebbero essere i seguenti

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a certain month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)",
      "intent": "last month",
      "manifest": "Records for the previous calendar month",
      "parameterized": {
        "parameterized_intent": "previous calendar month",
        "parameterized_sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)"
      }
    }
  ]
}

Salva il file e caricalo sul computer.

Poi utilizza l'azione di contesto della query "Modifica contesto" e carica il file modificato per sostituire il vecchio contesto con quello nuovo.

Ora prova a utilizzare di nuovo il contesto di test e a generare un'istruzione SQL utilizzando l'intent "ultimo mese". Ad esempio, se generi un SQL per la frase "show trucks trips for the last month"", utilizzerà la condizione che abbiamo fornito come sfaccettatura nel file cymbal_context.json.

Dovresti ottenere un risultato simile al seguente:

-- show trucks trips for the last month
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)

Ora, come puoi utilizzarlo con gli Agenti AI? Nel capitolo successivo rendiamo disponibile il contesto Query Data per gli agenti di AI.

11. QueryData con gli agenti AI

Utilizzerai lo stesso agente dati, ma ora la toolbox MCP verrà configurata per utilizzare il ContextSet QueryData.

Prepara e avvia MCP Toolbox per database

Abbiamo bisogno di un nuovo file di configurazione per MCP Toolbox che utilizzerà l'API Gemini Data Analytics e AlloyDB come origine del database.

Esegui nel terminale:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    querydata.yaml.example > querydata.yaml

Passa all'editor e trova il file querydata.yaml. Il file di configurazione querydata.yaml dovrebbe avere il seguente aspetto, ad eccezione dell'ID progetto e della regione, che rifletteranno il tuo ambiente. Tuttavia, devi comunque aggiornare il valore di contextSetId e sostituire il segnaposto "<add-context-set-id>" con il valore della console.

kind: sources
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: test-project-001-402417
---
kind: tools
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
location: "us-central1"
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
context:
  datasourceReferences:
    alloydb:
      databaseReference:
        projectId: "test-project-001-402417"
        region: "us-central1"
        clusterId: "alloydb-aip-01"
        instanceId: "alloydb-aip-01-pr"
        databaseId: "quickstart_db"
      agentContextReference:
        contextSetId: "<add-context-set-id>"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

Per trovare l'ID ContextSet, fai clic sul pulsante di modifica del set di contesto come mostrato nell'immagine.

Vedrai l'ID del contesto impostato in alto nella nuova scheda a destra.

Il percorso completo deve essere inserito per sostituire il segnaposto "<add-context-set-id>" nel file querydata.yaml.

Torna al terminale.

Apri una nuova scheda in Google Cloud Shell premendo il pulsante "+" nella parte superiore dell'interfaccia di Google Cloud Shell.

Nella nuova scheda, passa alla directory con il file binario della toolbox e il file di configurazione tools.yaml e avvia il server MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config querydata.yaml

Esegui l'agente ADK

Nella prima scheda di Cloud Shell, avvia l'agente.

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Quando viene avviato, fai di nuovo clic sul link http://127.0.0.1:8000 .

Vedrai l'interfaccia dell'agente di anteprima web dell'ADK che già conosci. Pubblica esattamente la stessa query dell'ultima volta.

Hello, can you tell me how many trips we've done in February?

e visualizzare il flusso di lavoro dell'agente. Se tutto è configurato correttamente, dovresti visualizzare un messaggio simile al seguente.

L'ultima volta la richiesta ha richiesto più passaggi, mentre ora viene trasformata in una chiamata allo strumento MCP ed eseguita utilizzando istruzioni SQL prevedibili.

Puoi testare le sfaccettature configurate utilizzando la richiesta come

how trucks trips for the last month

Nell'output, se fai clic sull'azione dello strumento, puoi vedere che è stato utilizzato lo stesso strumento e sono state applicate sfaccettature per ottenere il risultato.

Il lab è terminato. Spero che tu abbia potuto esaminare tutti gli esempi e imparare a utilizzare QueryData per AlloyDB. La tecnologia fornita contribuisce a rendere prevedibile e affidabile il workload agentico e la generazione di SQL.

12. Liberare spazio

Per evitare addebiti imprevisti, è buona norma liberare spazio dalle risorse temporanee. Il modo più affidabile è eliminare il progetto in cui hai testato il flusso di lavoro. In alternativa, puoi limitare l'utilizzo eliminando singole risorse, come AlloyDB.

Elimina le istanze e il cluster AlloyDB al termine del lab.

Elimina il cluster AlloyDB e tutte le istanze

Se hai utilizzato la versione di prova di AlloyDB. Non eliminare il cluster di prova se prevedi di testare altri lab e risorse utilizzando il cluster di prova. Non potrai creare un altro cluster di prova nello stesso progetto.

Il cluster viene eliminato con l'opzione force, che elimina anche tutte le istanze appartenenti al cluster.

In Cloud Shell definisci le variabili di progetto e di ambiente se la connessione è stata interrotta e tutte le impostazioni precedenti sono andate perse:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

Elimina il cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Nota: l'esecuzione del comando richiede 3-5 minuti

Output console previsto:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.   

Elimina i backup di AlloyDB

Elimina tutti i backup AlloyDB per il cluster:

Nota:il comando distruggerà tutti i backup dei dati per il cluster con il nome specificato nella variabile di ambiente

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Output console previsto:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.                                                                                                                                                                                                                                                            

13. Complimenti

Congratulazioni per aver completato il codelab.

Argomenti trattati

• Come creare un cluster AlloyDB e importare dati di esempio
• Come abilitare l'API di accesso ai dati di AlloyDB
• Come attivare QueryData per AlloyDB
• Come generare modelli
• Come utilizzare la ricerca con facet
• Come utilizzare QueryData con gli agenti AI

14. Sondaggio

Output:

Come utilizzerai questo tutorial?

Solo leggere Leggere e completare gli esercizi