Method: projects.locations.queryData

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

string

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 (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
Campi
prompt

string

Obbligatorio. La query in linguaggio naturale per cui generare la query. Esempio: "Quali sono i 5 prodotti più venduti questo mese?"

context

object (QueryDataContext)

Obbligatorio. Il contesto per la query sui dati, incluse le origini dati da utilizzare.

generationOptions

object (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 (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
Campi
generatedQuery

string

Query generata per il prompt dell'utente specificato.

intentExplanation

string

Una spiegazione in linguaggio naturale della query generata. Compilato se options.generate_explanation era true nella richiesta.

queryResult

object (ExecutedQueryResult)

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

string

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[]

string

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

object (Struct format)

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

object (TokenUsage)

Utilizzo totale dei token per la richiesta.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://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 (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
Campi
datasourceReferences

object (DatasourceReferences)

Obbligatorio. I riferimenti all'origine dati da utilizzare per la query.

parameterizedSecureViewParameters

object (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 (Parameter)
    }
  ]
}
Campi
parameters[]

object (Parameter)

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

string

Obbligatorio. La chiave del parametro (ad es. "userId").

value

string

Obbligatorio. Il valore parametro (ad es. "123").

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

boolean

Facoltativo. Se true, la query generata verrà eseguita e i dati dei risultati verranno restituiti nella risposta.

generateNaturalLanguageAnswer

boolean

Facoltativo. Se true, verrà generata una risposta in linguaggio naturale basata sul risultato dell'esecuzione della query, che verrà restituita nella risposta.

generateExplanation

boolean

Facoltativo. Se impostato su true, nella risposta verrà restituita una spiegazione della query generata.

generateDisambiguationQuestion

boolean

Facoltativo. Se impostato su true (il valore predefinito è false), il servizio potrebbe restituire una domanda di chiarimento se la query di input è ambigua.

generateDebugInfo

boolean

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 (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
Campi
columns[]

object (Column)

Le colonne nel set di risultati, in ordine.

rows[]

object (Row)

Le righe restituite dalla query.

totalRowCount

string (int64 format)

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

boolean

Impostato su true se le righe restituite in queryResult sono un sottoinsieme del risultato completo. Ciò può accadere, ad esempio, se l'esecuzione della query raggiunge un limite di righe. Se true, queryResult non contiene tutte le righe. Per recuperare il risultato completo, valuta la possibilità di utilizzare generatedQuery in QueryDataResponse ed eseguirlo nel tuo ambiente.

queryExecutionError

string

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

string

Il nome della colonna.

type

string

Il tipo di colonna (ad es. "VARCHAR", "INT64", "TIMESTAMP").

Riga

Rappresenta una singola riga nel set di risultati.

Rappresentazione JSON
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campi
values[]

object (Value)

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

string

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

integer

Il numero totale di token di input utilizzati in questa richiesta.

outputTokenCount

integer

Il numero totale di token di output utilizzati in questa richiesta.