MCP Tools Reference: bigquery.googleapis.com

Tool: execute_sql

Führe eine SQL-Abfrage im Projekt aus und gib das Ergebnis zurück. Verwenden Sie nach Möglichkeit das execute_sql_readonly-Tool.

Mit diesem Tool können alle von BigQuery unterstützten Abfragen ausgeführt werden, darunter: * SQL-Abfragen (SELECT, INSERT, UPDATE, DELETE, CREATE usw.) * KI-/ML-Funktionen wie AI.FORECAST, ML.EVALUATE und ML.PREDICT * Alle anderen Abfragen, die von BigQuery unterstützt werden.

Für Abfragen, die mit dem Tool execute_sql ausgeführt werden, wird automatisch das Joblabel goog-mcp-server: true festgelegt. Abfragen werden dem Projekt in Rechnung gestellt, das im Feld project_id angegeben ist.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool execute_sql aufrufen.

Curl-Anfrage 
                  
curl --location 'https://bigquery.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

Führt eine BigQuery-SQL-Abfrage synchron aus und gibt Ergebnisse zurück, wenn die Abfrage innerhalb eines bestimmten Zeitlimits abgeschlossen wird.

QueryRequest

JSON-Darstellung 
{
  "projectId": string,
  "query": string,
  "dryRun": boolean
}
Felder
projectId

string

Erforderlich. Projekt, das für die Ausführung von Abfragen und die Abrechnung verwendet wird.
query

string

Erforderlich. Die auszuführende Abfrage in Form einer GoogleSQL-Abfrage.
dryRun

boolean

Optional. Wenn auf „true“ gesetzt, wird der Job nicht von BigQuery ausgeführt. Wenn die Abfrage gültig ist, gibt BigQuery stattdessen Statistiken zum Job zurück, z. B. die Anzahl der zu verarbeitenden Byte. Wenn die Abfrage ungültig ist, wird ein Fehler zurückgegeben. Der Standardwert ist „false“.

Ausgabeschema

Antwort für eine BigQuery-SQL-Abfrage.

QueryResponse

JSON-Darstellung 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ],
  "queryId": string,
  "totalBytesBilled": string,
  "totalSlotMs": string,
  "numDmlAffectedRows": string,
  "totalBytesProcessed": string
}
Felder
schema

object (TableSchema)

Das Schema der Ergebnisse. Nur vorhanden, wenn die Abfrage erfolgreich abgeschlossen wurde.
rows[]

object (Struct format)

Ein Objekt mit so vielen Ergebnissen, wie in der maximal zulässigen Antwortgröße enthalten sein können. Wenn Sie zusätzliche Zeilen abrufen möchten, können Sie GetQueryResults aufrufen und die oben zurückgegebene jobReference angeben.
jobComplete

boolean

Gibt an, ob die Abfrage abgeschlossen wurde. Wenn „rows“ oder „totalRows“ vorhanden sind, ist dieser Wert immer „true“. Wenn dieser Wert „false“ ist, ist „totalRows“ nicht verfügbar.
errors[]

object (ErrorProto)

Nur Ausgabe. Die ersten Fehler oder Warnungen, die beim Ausführen des Jobs aufgetreten sind. Die endgültige Meldung enthält die Anzahl der Fehler, die zum Stoppen des Vorgangs geführt haben. Fehler hier bedeuten nicht unbedingt, dass der Job abgeschlossen wurde oder fehlgeschlagen ist. Weitere Informationen zu Fehlermeldungen finden Sie unter Fehlermeldungen.
queryId

string

Nur Ausgabe. Die ID der Abfrage.
totalBytesBilled

string (Int64Value format)

Nur Ausgabe. Die Gesamtzahl der für die Abfrage berechneten Byte. Gilt nur, wenn das Projekt für die Verwendung von On-Demand-Preisen konfiguriert ist.
totalSlotMs

string (Int64Value format)

Nur Ausgabe. Anzahl der Slot-Millisekunden, die dem Nutzer tatsächlich in Rechnung gestellt werden.
numDmlAffectedRows

string (Int64Value format)

Nur Ausgabe. Die Anzahl der Zeilen, die von einer DML-Anweisung betroffen sind.
totalBytesProcessed

string (Int64Value format)

Nur Ausgabe. Die Gesamtzahl der für diese Abfrage verarbeiteten Byte.

TableSchema

JSON-Darstellung 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
Felder
fields[]

object (TableFieldSchema)

Beschreibt die Felder in einer Tabelle.
foreignTypeInfo

object (ForeignTypeInfo)

Optional. Gibt Metadaten der Definition des externen Datentyps im Feldschema (TableFieldSchema.foreign_type_definition) an.

TableFieldSchema

JSON-Darstellung 
{
  "name": string,
  "type": string,
  "mode": string,
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "description": string,
  "policyTags": {
    object (PolicyTagList)
  },
  "dataPolicies": [
    {
      object (DataPolicyOption)
    }
  ],
  "maxLength": string,
  "precision": string,
  "scale": string,
  "timestampPrecision": string,
  "roundingMode": enum (RoundingMode),
  "collation": string,
  "defaultValueExpression": string,
  "rangeElementType": {
    object (FieldElementType)
  },
  "foreignTypeDefinition": string,
  "generatedColumn": {
    object (GeneratedColumn)
  }
}
Felder
name

string

Erforderlich. Der Feldname. Der Name darf nur Buchstaben (a–z, A–Z), Ziffern (0–9) und Unterstriche (_) enthalten und muss mit einem Buchstaben oder einem Unterstrich beginnen. Die maximale Länge beträgt 300 Zeichen.
type

string

Erforderlich. Der Datentyp des Felds. Mögliche Werte:

  • STRING
  • BYTES
  • INTEGER (oder INT64)
  • FLOAT (oder FLOAT64)
  • BOOLEAN (oder BOOL)
  • TIMESTAMP
  • DATE
  • UHRZEIT
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • RECORD (oder STRUCT)
  • RANGE

Die Verwendung von RECORD/STRUCT gibt an, dass das Feld ein verschachteltes Schema enthält.
mode

string

Optional. Der Feldmodus. Mögliche Werte sind NULLABLE, REQUIRED und REPEATED. Der Standardwert ist NULLABLE.
fields[]

object (TableFieldSchema)

Optional. Beschreibt die verschachtelten Schemafelder, wenn das Attribut „type“ auf „RECORD“ gesetzt ist.
description

string

Optional. Die Feldbeschreibung. Die maximale Länge beträgt 1.024 Zeichen.
policyTags

object (PolicyTagList)

Optional. Die Richtlinien-Tags, die diesem Feld zugewiesen sind und für die Zugriffssteuerung auf Feldebene verwendet werden. Wenn nichts anderes festgelegt ist, wird standardmäßig „empty policy_tags“ verwendet.
dataPolicies[]

object (DataPolicyOption)

Optional. Datenrichtlinien, die diesem Feld zugeordnet sind und für die Zugriffssteuerung auf Feldebene verwendet werden.
maxLength

string (int64 format)

Optional. Maximale Länge der Werte dieses Felds für STRINGS oder BYTES.

Wenn „max_length“ nicht angegeben ist, wird für dieses Feld keine maximale Länge festgelegt.

Wenn type = „STRING“, dann steht max_length für die maximale UTF-8-Länge von Strings in diesem Feld.

Wenn type = „BYTES“, dann stellt max_length die maximale Anzahl von Byte in diesem Feld dar.

Dieses Feld darf nicht festgelegt werden, wenn type ≠ „STRING“ und ≠ „BYTES“.
precision

string (int64 format)

Optional. Einschränkungen für die Genauigkeit (maximale Anzahl der Ziffern insgesamt in Basis 10) und die Skalierung (maximale Anzahl der Ziffern im Bruchteil in Basis 10) für Werte dieses Felds für NUMERIC oder BIGNUMERIC.

Es ist ungültig, Genauigkeit oder Skalierung festzulegen, wenn type ≠ „NUMERIC“ und ≠ „BIGNUMERIC“.

Wenn keine Genauigkeit und Skalierung angegeben sind, wird für dieses Feld keine Einschränkung des Wertebereichs festgelegt, sofern Werte vom Typ zulässig sind.

Werte dieses NUMERIC- oder BIGNUMERIC-Felds müssen in diesem Bereich liegen, wenn:

  • Genauigkeit (P) und Skalierung (S) sind angegeben: [-10P-S + 10-S, 10P-S – 10-S]
  • Die Genauigkeit (P) wird angegeben, nicht aber die Skalierung (die daher als null interpretiert wird): [-10P + 1, 10P – 1].

Zulässige Werte für Genauigkeit und Skalierung, wenn beide angegeben sind:

  • Wenn type = „NUMERIC“: 1 ≤ precision – scale ≤ 29 und 0 ≤ scale ≤ 9.
  • Wenn type = „BIGNUMERIC“: 1 ≤ precision – scale ≤ 38 und 0 ≤ scale ≤ 38.

Zulässige Werte für die Genauigkeit, wenn nur die Genauigkeit, nicht aber die Skalierung angegeben wird (und die Skalierung daher als null interpretiert wird):

  • Wenn type = „NUMERIC“: 1 ≤ precision ≤ 29.
  • Wenn type = „BIGNUMERIC“: 1 ≤ precision ≤ 38.

Wenn die Skalierung, aber nicht die Genauigkeit angegeben wird, ist das ungültig.
scale

string (int64 format)

Optional. Weitere Informationen zur Genauigkeit finden Sie in der Dokumentation.
timestampPrecision

string (Int64Value format)

Optional. Genauigkeit (maximale Anzahl der Gesamtziffern in Basis 10) für Sekunden des TIMESTAMP-Typs.

Mögliche Werte sind: * 6 (Standard für den TIMESTAMP-Typ mit Mikrosekundengenauigkeit) * 12 (für den TIMESTAMP-Typ mit Pikosekundengenauigkeit)
roundingMode

enum (RoundingMode)

Optional. Gibt den Rundungsmodus an, der beim Speichern von Werten des Typs NUMERIC und BIGNUMERIC verwendet werden soll.
collation

string

Optional. Die Sortierung von Feldern kann nur festgelegt werden, wenn der Feldtyp STRING ist. Folgende Werte werden unterstützt:

  • 'und:ci': unbestimmtes Gebietsschema, Groß-/Kleinschreibung nicht berücksichtigend.
  • '': leerer String. Standardmäßig wird zwischen Groß- und Kleinschreibung unterschieden.
defaultValueExpression

string

Optional. Ein SQL-Ausdruck, mit dem der Standardwert für dieses Feld angegeben wird.
rangeElementType

object (FieldElementType)

Optional. Der Untertyp des Bereichs, wenn der Typ dieses Felds „RANGE“ ist. Wenn der Typ RANGE ist, ist dieses Feld erforderlich. Für den Feld-Elementtyp sind folgende Werte möglich:

  • DATE
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

Optional. Definition des fremden Datentyps. Gilt nur für Schemafelder der obersten Ebene (nicht für verschachtelte Felder). Wenn der Typ FOREIGN (ausländisch) ist, ist dieses Feld erforderlich.
generatedColumn

object (GeneratedColumn)

Optional. Definition, wie Werte für das Feld generiert werden. Gilt nur für Schemafelder der obersten Ebene (nicht für verschachtelte Felder).

StringValue

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

string

Stringwert.

PolicyTagList

JSON-Darstellung 
{
  "names": [
    string
  ]
}
Felder
names[]

string

Eine Liste mit Ressourcennamen von Richtlinien-Tags. Beispiel: „projects/1/locations/eu/taxonomies/2/policyTags/3“. Derzeit ist maximal ein Richtlinien-Tag zulässig.

DataPolicyOption

JSON-Darstellung 
{

  // Union field _name can be only one of the following:
  "name": string
  // End of list of possible types for union field _name.
}
Felder

Union-Feld _name.

Für _name ist nur einer der folgenden Werte zulässig:
name

string

Ressourcenname der Datenrichtlinie im Format „projects/project_id/locations/location_id/dataPolicies/data_policy_id“.

Int64Value

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

string (int64 format)

Der int64-Wert.

FieldElementType

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

string

Erforderlich. Der Typ eines Feldelements. Weitere Informationen finden Sie unter TableFieldSchema.type.

GeneratedColumn

JSON-Darstellung 
{

  // Union field _generated_mode can be only one of the following:
  "generatedMode": enum (GeneratedMode)
  // End of list of possible types for union field _generated_mode.

  // Union field definition can be only one of the following:
  "generatedExpressionInfo": {
    object (GeneratedExpressionInfo)
  }
  // End of list of possible types for union field definition.
}
Felder

Union-Feld _generated_mode.

Für _generated_mode ist nur einer der folgenden Werte zulässig:
generatedMode

enum (GeneratedMode)

Optional. Gibt an, wann vom System generierte Werte zum Ausfüllen des Felds verwendet werden.

Union-Feld definition.

Für definition ist nur einer der folgenden Werte zulässig:
generatedExpressionInfo

object (GeneratedExpressionInfo)

Definition des Ausdrucks, der zum Generieren des Felds verwendet wird.

GeneratedExpressionInfo

JSON-Darstellung 
{

  // Union field _generation_expression can be only one of the following:
  "generationExpression": string
  // End of list of possible types for union field _generation_expression.

  // Union field _asynchronous can be only one of the following:
  "asynchronous": boolean
  // End of list of possible types for union field _asynchronous.

  // Union field _stored can be only one of the following:
  "stored": boolean
  // End of list of possible types for union field _stored.
}
Felder

Union-Feld _generation_expression.

Für _generation_expression ist nur einer der folgenden Werte zulässig:
generationExpression

string

Optional. Der Ausdruck zum Generieren (z.B. AI.EMBED(...)), der zum Generieren des Felds verwendet wurde.

Union-Feld _asynchronous.

Für _asynchronous ist nur einer der folgenden Werte zulässig:
asynchronous

boolean

Optional. Gibt an, ob die Spaltengenerierung asynchron erfolgt.

Union-Feld _stored.

Für _stored ist nur einer der folgenden Werte zulässig:
stored

boolean

Optional. Gibt an, ob die generierte Spalte in der Tabelle gespeichert wird.

ForeignTypeInfo

JSON-Darstellung 
{
  "typeSystem": enum (TypeSystem)
}
Felder
typeSystem

enum (TypeSystem)

Erforderlich. Gibt das System an, das den externen Datentyp definiert.

Struct

JSON-Darstellung 
{
  "fields": {
    string: value,
    ...
  }
}
Felder
fields

map (key: string, value: value (Value format))

Ungeordnete Zuordnung von dynamisch typisierten Werten.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

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

string
value

value (Value format)

Wert

JSON-Darstellung 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
Felder
Union-Feld kind. Die Art des Werts. Für kind ist nur einer der folgenden Werte zulässig:
nullValue

null

Stellt ein JSON-null dar.
numberValue

number

Stellt eine JSON-Zahl dar. Darf nicht NaN, Infinity oder -Infinity sein, da diese in JSON nicht unterstützt werden. Auch große Int64-Werte können nicht dargestellt werden, da das JSON-Format sie in seinem Zahlentyp generell nicht unterstützt.
stringValue

string

Stellt einen JSON-String dar.
boolValue

boolean

Stellt einen booleschen JSON-Wert dar (true- oder false-Literal in JSON).
structValue

object (Struct format)

Stellt ein JSON-Objekt dar.
listValue

array (ListValue format)

Stellt ein JSON-Array dar.

ListValue

JSON-Darstellung 
{
  "values": [
    value
  ]
}
Felder
values[]

value (Value format)

Wiederholtes Feld mit dynamisch typisierten Werten.

BoolValue

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

boolean

Der boolesche Wert.

ErrorProto

JSON-Darstellung 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
Felder
reason

string

Ein kurzer Fehlercode, der den Fehler zusammenfasst.
location

string

Gibt an, wo der Fehler aufgetreten ist, sofern vorhanden.
debugInfo

string

Debugging-Informationen. Diese Property ist intern bei Google und sollte nicht verwendet werden.
message

string

Eine für Menschen lesbare Beschreibung des Fehlers.

Tool-Annotationen

Destruktiver Hinweis: ✅ | Idempotenter Hinweis: ❌ | Nur-Lese-Hinweis: ❌ | Open-World-Hinweis: ✅