- HTTP-Anfrage
- Pfadparameter
- Anfragetext
- Antworttext
- Autorisierungsbereiche
- QueryDataContext
- ParameterizedSecureViewParameters
- Parameter
- GenerationOptions
- ExecutedQueryResult
- Spalte
- Zeile
- Wert
- TokenUsage
Fragt Daten aus einer Nutzeranfrage in natürlicher Sprache ab.
HTTP-Anfrage
POST https://geminidataanalytics.googleapis.com/v1alpha/{parent=projects/*/locations/*}:queryData
Die URL verwendet die Syntax der gRPC-Transcodierung.
Pfadparameter
| Parameter | |
|---|---|
parent |
Erforderlich. Die übergeordnete Ressource, für die die Abfrage generiert werden soll. Format: projects/{projekt}/locations/{location} |
Anfragetext
Der Anfragetext enthält Daten mit folgender Struktur:
| JSON-Darstellung |
|---|
{ "prompt": string, "context": { object ( |
| Felder | |
|---|---|
prompt |
Erforderlich. Die Abfrage in natürlicher Sprache, für die eine Abfrage generiert werden soll. Beispiel: „Welche fünf Produkte wurden diesen Monat am meisten verkauft?“ |
context |
Erforderlich. Der Kontext für die Datenabfrage, einschließlich der zu verwendenden Datenquellen. |
generationOptions |
Optional. Optionen zum Steuern der Abfragegenerierung und des Ausführungsverhaltens. |
Antworttext
Antwort mit der generierten Abfrage und zugehörigen Informationen.
Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:
| JSON-Darstellung |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| Felder | |
|---|---|
generatedQuery |
Generierte Abfrage für den angegebenen Nutzer-Prompt. |
intentExplanation |
Eine Erklärung der generierten Abfrage in natürlicher Sprache. Wird ausgefüllt, wenn „options.generate_explanation“ in der Anfrage „true“ war. |
queryResult |
Das Ergebnis der Abfrageausführung. Wird ausgefüllt, wenn „options.generate_query_result“ oder „options.generate_natural_language_answer“ in der Anfrage „true“ war und die Ausführung erfolgreich war oder versucht wurde. |
naturalLanguageAnswer |
Eine Antwort in natürlicher Sprache auf die Abfrage, basierend auf dem queryResult. Wird ausgefüllt, wenn „options.generate_natural_language_answer“ in der Anfrage „true“ war und die Abfrageausführung basierend auf der Antwort der executeSql API erfolgreich war. |
disambiguationQuestion[] |
Wenn in der Abfrage in natürlicher Sprache eine Mehrdeutigkeit erkannt wurde und options.generate_disambiguation_question auf „true“ gesetzt war, enthält dieses Feld eine Frage an den Nutzer zur Klärung. Das zurückgegebene Ergebnis stellt die bestmögliche Leistung des Dienstes basierend auf der mehrdeutigen Eingabe dar. |
pipelineDebugInfo |
Detaillierte Schritt-für-Schritt-Informationen zur Pipelineausführung. Wird nur ausgefüllt, wenn „generationOptions.generate_debug_info“ auf „true“ gesetzt war. Wird nur zur Fehlerbehebung und für Transparenzzwecke bereitgestellt. Die Struktur und der Inhalt dieses Objekts sind nicht garantiert und können sich jederzeit ohne Vorankündigung ändern. Schreiben Sie keinen Produktionscode oder keine Geschäftslogik, die von den Feldern in diesem Objekt abhängen. |
tokenUsage |
Gesamte Tokennutzung für die Anfrage. |
Autorisierungsbereiche
Erfordert einen der folgenden OAuth-Bereiche:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
Weitere Informationen finden Sie unter Authentication Overview.
QueryDataContext
Verweise auf Datenquellen und Kontext, die für die Abfrage verwendet werden sollen.
| JSON-Darstellung |
|---|
{ "datasourceReferences": { object ( |
| Felder | |
|---|---|
datasourceReferences |
Erforderlich. Die Datenquellenreferenzen, die für die Abfrage verwendet werden sollen. |
parameterizedSecureViewParameters |
Optional. Parameter für parametrisierte sichere Ansichten (PSV). |
ParameterizedSecureViewParameters
Parameter für parametrisierte sichere Ansichten (PSV). Diese Parameter werden verwendet, um die Sicherheit auf Zeilenebene während der SQL-Generierung und Abfrageausführung zu erzwingen.
| JSON-Darstellung |
|---|
{
"parameters": [
{
object ( |
| Felder | |
|---|---|
parameters[] |
Optional. Benannte Parameter für parametrisierte sichere Ansichten (PSV). |
Parameter
Stellt einen einzelnen Parameter für parametrisierte sichere Ansichten dar.
| JSON-Darstellung |
|---|
{ "key": string, "value": string } |
| Felder | |
|---|---|
key |
Erforderlich. Der Parameterschlüssel (z.B. |
value |
Erforderlich. Der Parameterwert (z.B. |
GenerationOptions
Optionen zum Steuern der Abfragegenerierung, ‑ausführung und des Antwortformats.
| JSON-Darstellung |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| Felder | |
|---|---|
generateQueryResult |
Optional. Wenn „true“, wird die generierte Abfrage ausgeführt und die Ergebnisdaten werden in der Antwort zurückgegeben. |
generateNaturalLanguageAnswer |
Optional. Wenn „true“, wird eine Antwort in natürlicher Sprache basierend auf dem Ergebnis der Abfrageausführung generiert und in der Antwort zurückgegeben. |
generateExplanation |
Optional. Wenn „true“, wird in der Antwort eine Erklärung der generierten Abfrage zurückgegeben. |
generateDisambiguationQuestion |
Optional. Wenn „true“ (Standardeinstellung ist „false“), kann der Dienst eine „clarifying_question“ zurückgeben, wenn die Eingabeanfrage mehrdeutig ist. |
generateDebugInfo |
Optional. Wenn „true“ (Standardeinstellung ist „false“), werden interne Debugging-Informationen zurückgegeben. |
ExecutedQueryResult
Das Ergebnis einer Abfrageausführung. Das Design ist für alle Dialekte generisch.
| JSON-Darstellung |
|---|
{ "columns": [ { object ( |
| Felder | |
|---|---|
columns[] |
Die Spalten im Ergebnissatz in der richtigen Reihenfolge. |
rows[] |
Die von der Abfrage zurückgegebenen Zeilen. |
totalRowCount |
Die Gesamtzahl der Zeilen im vollständigen Ergebnissatz, falls bekannt. Dies kann eine Schätzung oder eine genaue Anzahl sein. Hinweis: Wenn während der Abfrageausführung ein internes Limit (z. B. LIMIT 1000) angewendet wurde, um eine übermäßige Datenübertragung zu verhindern, spiegelt diese Anzahl die gekürzte Ergebnisgröße und nicht die uneingeschränkte Tabellenergebnisgröße wider. |
partialResult |
Wird auf „true“ gesetzt, wenn die zurückgegebenen Zeilen in |
queryExecutionError |
Die Fehlermeldung, wenn die Abfrageausführung fehlgeschlagen ist. |
Spalte
Beschreibt eine einzelne Spalte im Ergebnissatz.
| JSON-Darstellung |
|---|
{ "name": string, "type": string } |
| Felder | |
|---|---|
name |
Der Name der Spalte. |
type |
Der Typ der Spalte (z.B. „VARCHAR“, „INT64“, „TIMESTAMP“). |
Zeile
Stellt eine einzelne Zeile im Ergebnissatz dar.
| JSON-Darstellung |
|---|
{
"values": [
{
object ( |
| Felder | |
|---|---|
values[] |
Die Werte in der Zeile, die den Spaltenpositionen entsprechen. |
Wert
Stellt einen einzelnen Wert innerhalb einer Zeile dar.
| JSON-Darstellung |
|---|
{ "value": string } |
| Felder | |
|---|---|
value |
Der Zellenwert im Stringformat. Zeitstempel können beispielsweise mit RFC3339Nano formatiert werden. Dieses Feld wird verwendet, wenn der Wert nicht null ist. |
TokenUsage
Tracking der gesamten Tokennutzung für die Anfrage.
| JSON-Darstellung |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| Felder | |
|---|---|
inputTokenCount |
Die Gesamtzahl der in dieser Anfrage verwendeten Eingabetokens. |
outputTokenCount |
Die Gesamtzahl der in dieser Anfrage verwendeten Ausgabetokens. |