- Richiesta HTTP
- Parametri di percorso
- Corpo della richiesta
- Corpo della risposta
- Ambiti di autorizzazione
- QueryDataContext
- ParameterizedSecureViewParameters
- Parametro
- GenerationOptions
- ExecutedQueryResult
- Colonna
- Row
- Valore
- TokenUsage
Esegue query sui dati da una query utente in linguaggio naturale.
Richiesta HTTP
POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData
L'URL utilizza la sintassi di transcodifica gRPC.
Parametri di percorso
| Parametri | |
|---|---|
parent |
Obbligatorio. La risorsa padre per cui generare la query. Formato: projects/{project}/locations/{location} |
Corpo della richiesta
Il corpo della richiesta contiene dati con la seguente struttura:
| Rappresentazione JSON |
|---|
{ "prompt": string, "context": { object ( |
| Campi | |
|---|---|
prompt |
Obbligatorio. La query in linguaggio naturale per cui generare la query. Esempio: "Quali sono i 5 prodotti più venduti questo mese?" |
context |
Obbligatorio. Il contesto per la query sui dati, incluse le origini dati da utilizzare. |
generationOptions |
Facoltativo. Opzioni per controllare il comportamento di generazione ed esecuzione delle query. |
Corpo della risposta
Risposta contenente la query generata e le informazioni correlate.
In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:
| Rappresentazione JSON |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| Campi | |
|---|---|
generatedQuery |
Query generata per il prompt dell'utente specificato. |
intentExplanation |
Una spiegazione in linguaggio naturale della query generata. Compilato se options.generate_explanation era true nella richiesta. |
queryResult |
Il risultato dell'esecuzione della query. Compilato se options.generate_query_result o options.generate_natural_language_answer era true nella richiesta e l'esecuzione è stata completata o tentata. |
naturalLanguageAnswer |
Una risposta in linguaggio naturale alla query, basata su queryResult. Compilato se options.generate_natural_language_answer era true nella richiesta e l'esecuzione della query è andata a buon fine in base alla risposta dell'API executeSql. |
disambiguationQuestion[] |
Se è stata rilevata un'ambiguità nella query in linguaggio naturale e options.generate_disambiguation_question era true, questo campo contiene una domanda per l'utente per chiarire l'ambiguità. Il valore restituito rappresenta il risultato migliore del servizio in base all'input ambiguo. |
pipelineDebugInfo |
Informazioni dettagliate sull'esecuzione della pipeline passo passo. Compilato solo se generationOptions.generate_debug_info era true. Fornito solo per scopi di debug e trasparenza. La struttura e i contenuti di questo oggetto non sono garantiti e possono cambiare in qualsiasi momento senza preavviso. Non scrivere codice di produzione o logica di business in base ai campi di questo oggetto. |
tokenUsage |
Utilizzo totale dei token per la richiesta. |
Ambiti di autorizzazione
Richiede uno dei seguenti ambiti OAuth:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
Per saperne di più, consulta la Authentication Overview.
QueryDataContext
Riferimenti alle origini dati e al contesto da utilizzare per la query.
| Rappresentazione JSON |
|---|
{ "datasourceReferences": { object ( |
| Campi | |
|---|---|
datasourceReferences |
Obbligatorio. I riferimenti all'origine dati da utilizzare per la query. |
parameterizedSecureViewParameters |
Facoltativo. Parametri per le viste sicure parametrizzate (PSV). |
ParameterizedSecureViewParameters
Parametri per le viste sicure parametrizzate (PSV). Questi parametri vengono utilizzati per applicare la sicurezza a livello di riga durante la generazione di SQL e l'esecuzione delle query.
| Rappresentazione JSON |
|---|
{
"parameters": [
{
object ( |
| Campi | |
|---|---|
parameters[] |
Facoltativo. Parametri denominati per le viste sicure parametrizzate (PSV). |
Parametro
Rappresenta un singolo parametro per le viste sicure parametrizzate.
| Rappresentazione JSON |
|---|
{ "key": string, "value": string } |
| Campi | |
|---|---|
key |
Obbligatorio. La chiave del parametro (ad es. |
value |
Obbligatorio. Il valore parametro (ad es. |
GenerationOptions
Opzioni per controllare la generazione, l'esecuzione e il formato della risposta delle query.
| Rappresentazione JSON |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| Campi | |
|---|---|
generateQueryResult |
Facoltativo. Se true, la query generata verrà eseguita e i dati dei risultati verranno restituiti nella risposta. |
generateNaturalLanguageAnswer |
Facoltativo. Se true, verrà generata una risposta in linguaggio naturale basata sul risultato dell'esecuzione della query, che verrà restituita nella risposta. |
generateExplanation |
Facoltativo. Se impostato su true, nella risposta verrà restituita una spiegazione della query generata. |
generateDisambiguationQuestion |
Facoltativo. Se impostato su true (il valore predefinito è false), il servizio potrebbe restituire una domanda di chiarimento se la query di input è ambigua. |
generateDebugInfo |
Facoltativo. Se il valore è true (il valore predefinito è false), restituisce informazioni di debug interne. |
ExecutedQueryResult
Il risultato dell'esecuzione di una query. Il design è generico per tutti i dialetti.
| Rappresentazione JSON |
|---|
{ "columns": [ { object ( |
| Campi | |
|---|---|
columns[] |
Le colonne nel set di risultati, in ordine. |
rows[] |
Le righe restituite dalla query. |
totalRowCount |
Il numero totale di righe nel set di risultati completo, se noto. Potrebbe trattarsi di una stima o di un conteggio esatto. Nota: se durante l'esecuzione della query è stato applicato un limite interno (ad esempio LIMIT 1000) per evitare un trasferimento di dati eccessivo, questo conteggio riflette le dimensioni dei risultati troncati anziché quelle dei risultati della tabella senza restrizioni. |
partialResult |
Impostato su true se le righe restituite in |
queryExecutionError |
Il messaggio di errore se l'esecuzione della query non è riuscita. |
Colonna
Descrive una singola colonna nel set di risultati.
| Rappresentazione JSON |
|---|
{ "name": string, "type": string } |
| Campi | |
|---|---|
name |
Il nome della colonna. |
type |
Il tipo di colonna (ad es. "VARCHAR", "INT64", "TIMESTAMP"). |
Riga
Rappresenta una singola riga nel set di risultati.
| Rappresentazione JSON |
|---|
{
"values": [
{
object ( |
| Campi | |
|---|---|
values[] |
I valori nella riga, corrispondenti alle colonne in base alla posizione. |
Valore
Rappresenta un singolo valore all'interno di una riga.
| Rappresentazione JSON |
|---|
{ "value": string } |
| Campi | |
|---|---|
value |
Il valore della cella, rappresentato in formato stringa. I timestamp possono essere formattati, ad esempio, utilizzando RFC3339Nano. Questo campo viene utilizzato se il valore non è null. |
TokenUsage
Monitoraggio dell'utilizzo complessivo dei token per la richiesta.
| Rappresentazione JSON |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| Campi | |
|---|---|
inputTokenCount |
Il numero totale di token di input utilizzati in questa richiesta. |
outputTokenCount |
Il numero totale di token di output utilizzati in questa richiesta. |