Method: projects.locations.queryData

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

string

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

string

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

object (QueryDataContext)

Erforderlich. Der Kontext für die Datenabfrage, einschließlich der zu verwendenden Datenquellen.

generationOptions

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

string

Generierte Abfrage für den angegebenen Nutzer-Prompt.

intentExplanation

string

Eine Erklärung der generierten Abfrage in natürlicher Sprache. Wird ausgefüllt, wenn „options.generate_explanation“ in der Anfrage „true“ war.

queryResult

object (ExecutedQueryResult)

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

string

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

string

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

object (Struct format)

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

object (TokenUsage)

Gesamte Tokennutzung für die Anfrage.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

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

object (DatasourceReferences)

Erforderlich. Die Datenquellenreferenzen, die für die Abfrage verwendet werden sollen.

parameterizedSecureViewParameters

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

object (Parameter)

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

string

Erforderlich. Der Parameterschlüssel (z.B. "userId").

value

string

Erforderlich. Der Parameterwert (z.B. "123").

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

boolean

Optional. Wenn „true“, wird die generierte Abfrage ausgeführt und die Ergebnisdaten werden in der Antwort zurückgegeben.

generateNaturalLanguageAnswer

boolean

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

boolean

Optional. Wenn „true“, wird in der Antwort eine Erklärung der generierten Abfrage zurückgegeben.

generateDisambiguationQuestion

boolean

Optional. Wenn „true“ (Standardeinstellung ist „false“), kann der Dienst eine „clarifying_question“ zurückgeben, wenn die Eingabeanfrage mehrdeutig ist.

generateDebugInfo

boolean

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

object (Column)

Die Spalten im Ergebnissatz in der richtigen Reihenfolge.

rows[]

object (Row)

Die von der Abfrage zurückgegebenen Zeilen.

totalRowCount

string (int64 format)

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

boolean

Wird auf „true“ gesetzt, wenn die zurückgegebenen Zeilen in queryResult eine Teilmenge des vollständigen Ergebnisses sind. Das kann beispielsweise passieren, wenn die Abfrageausführung ein Zeilenlimit erreicht. Wenn „true“, enthält die queryResult nicht alle Zeilen. Wenn Sie das vollständige Ergebnis abrufen möchten, können Sie die generatedQuery in QueryDataResponse verwenden und in Ihrer eigenen Umgebung ausführen.

queryExecutionError

string

Die Fehlermeldung, wenn die Abfrageausführung fehlgeschlagen ist.

Spalte

Beschreibt eine einzelne Spalte im Ergebnissatz.

JSON-Darstellung
{
  "name": string,
  "type": string
}
Felder
name

string

Der Name der Spalte.

type

string

Der Typ der Spalte (z.B. „VARCHAR“, „INT64“, „TIMESTAMP“).

Zeile

Stellt eine einzelne Zeile im Ergebnissatz dar.

JSON-Darstellung
{
  "values": [
    {
      object (Value)
    }
  ]
}
Felder
values[]

object (Value)

Die Werte in der Zeile, die den Spaltenpositionen entsprechen.

Wert

Stellt einen einzelnen Wert innerhalb einer Zeile dar.

JSON-Darstellung
{
  "value": string
}
Felder
value

string

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

integer

Die Gesamtzahl der in dieser Anfrage verwendeten Eingabetokens.

outputTokenCount

integer

Die Gesamtzahl der in dieser Anfrage verwendeten Ausgabetokens.