MCP Tools Reference: bigquery.googleapis.com

Herramienta: execute_sql

Ejecuta una consulta de SQL en el proyecto y devuelve el resultado.

Esta herramienta solo se puede usar con SELECT. No se permiten las instrucciones INSERT, UPDATE y DELETE ni los procedimientos almacenados. Si la consulta no incluye una instrucción SELECT, se devuelve un error. Para obtener información sobre cómo crear consultas, consulta la documentación de GoogleSQL.

La herramienta execute_sql también puede tener efectos secundarios si la consulta invoca funciones remotas o UDFs de Python.

Todas las consultas que se ejecutan con la herramienta execute_sql tienen una etiqueta que identifica la herramienta como fuente. Puede usar esta etiqueta para filtrar las consultas con el par de etiqueta y valor goog-mcp-server: true.

Las consultas se cobran al proyecto especificado en el campo project_id.

En el siguiente ejemplo se muestra cómo usar curl para invocar la herramienta execute_sql MCP.

Solicitud de Curl 
                  
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
}'

Esquema de entrada

Ejecuta una consulta de SQL de BigQuery de forma síncrona y devuelve los resultados si la consulta se completa en el tiempo de espera especificado.

Representación JSON 
{
  "projectId": string,
  "query": string,
  "dryRun": boolean
}
Campos
projectId

string

Obligatorio. Proyecto que se usará para la ejecución de consultas y la facturación.
query

string

Obligatorio. Consulta que se va a ejecutar en forma de consulta de GoogleSQL.
dryRun

boolean

Opcional. Si se le asigna el valor true, BigQuery no ejecuta el trabajo. En su lugar, si la consulta es válida, BigQuery devuelve estadísticas sobre el trabajo, como el número de bytes que se procesarían. Si la consulta no es válida, se devuelve un error. El valor predeterminado es false.

Esquema de salida

Respuesta de una consulta de SQL de BigQuery.

Representación JSON 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ]
}
Campos
schema

object (TableSchema)

El esquema de los resultados. Aparece únicamente cuando la consulta se completa de forma correcta.
rows[]

object (Struct format)

Un objeto con tantos resultados como se pueden contener dentro del tamaño máximo de respuesta permitido. Para obtener filas adicionales, puedes llamar a GetQueryResults y especificar el jobReference devuelto anteriormente.
jobComplete

boolean

Determina si la consulta se ha completado o no. Si aparecen filas o el valor totalRows, siempre será verdadero. Si fuera falso, el valor totalRows no estará disponible.
errors[]

object (ErrorProto)

Solo de salida. Los primeros errores o advertencias que se han encontrado durante la ejecución del trabajo. El mensaje final incluye el número de errores que han provocado que el proceso se detenga. Estos errores no indican necesariamente que el trabajo se haya completado o que se haya completado incorrectamente. Para obtener más información sobre los mensajes de error, consulta el artículo Mensajes de error.
Representación JSON 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
Campos
fields[]

object (TableFieldSchema)

Describe los campos de una tabla.
foreignTypeInfo

object (ForeignTypeInfo)

Opcional. Especifica los metadatos de la definición del tipo de datos externos en el esquema de campo (TableFieldSchema.foreign_type_definition).
Representación JSON 
{
  "name": string,
  "type": string,
  "mode": string,
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "description": string,
  "policyTags": {
    object (PolicyTagList)
  },
  "dataPolicies": [
    {
      object (DataPolicyOption)
    }
  ],
  "nameAlternative": [
    string
  ],
  "maxLength": string,
  "precision": string,
  "scale": string,
  "timestampPrecision": string,
  "roundingMode": enum (RoundingMode),
  "collation": string,
  "defaultValueExpression": string,
  "rangeElementType": {
    object (FieldElementType)
  },
  "foreignTypeDefinition": string
}
Campos
name

string

Obligatorio. Nombre del campo. El nombre solo puede contener letras (a-z, A-Z), números (0-9) o guiones bajos (_), y debe empezar por una letra o un guion bajo. La longitud máxima es de 300 caracteres.
type

string

Obligatorio. El tipo de datos del campo. Estos son algunos de los posibles valores:

  • STRING
  • BYTES
  • INTEGER (o INT64)
  • FLOAT (o FLOAT64)
  • BOOLEAN (o BOOL)
  • TIMESTAMP
  • FECHA
  • HORA
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • RECORD (o STRUCT)
  • RANGE

El uso de RECORD o STRUCT indica que el campo contiene un esquema anidado.
mode

string

Opcional. El modo del campo. Entre los valores posibles se incluyen NULLABLE, REQUIRED y REPEATED. El valor predeterminado es NULLABLE.
fields[]

object (TableFieldSchema)

Opcional. Describe los campos de esquema anidados si la propiedad type se define como RECORD.
description

string

Opcional. Descripción del campo. La longitud máxima es de 1024 caracteres.
policyTags

object (PolicyTagList)

Opcional. Las etiquetas de política asociadas a este campo, que se usan para el control de acceso a nivel de campo. Si no se define, se utiliza una lista vacía de policy_tags de forma predeterminada.
dataPolicies[]

object (DataPolicyOption)

Opcional. Políticas de datos asociadas a este campo, que se usan para el control de acceso a nivel de campo.
nameAlternative[]

string

Este campo no se debe usar.
maxLength

string (int64 format)

Opcional. Longitud máxima de los valores de este campo para STRINGS o BYTES.

Si no se especifica max_length, no se impone ninguna restricción de longitud máxima en este campo.

Si type = "STRING", max_length representa la longitud máxima en UTF-8 de las cadenas de este campo.

Si type = "BYTES", max_length representa el número máximo de bytes de este campo.

No se puede definir este campo si type ≠ "STRING" y ≠ "BYTES".
precision

string (int64 format)

Opcional. Restricciones de precisión (número máximo de dígitos totales en base 10) y escala (número máximo de dígitos en la parte fraccionaria en base 10) para los valores de este campo en NUMERIC o BIGNUMERIC.

No se puede definir la precisión ni la escala si el tipo no es "NUMERIC" ni "BIGNUMERIC".

Si no se especifican la precisión y la escala, no se impone ninguna restricción de intervalo de valores en este campo, siempre que los valores estén permitidos por el tipo.

Los valores de este campo NUMERIC o BIGNUMERIC deben estar en este intervalo cuando:

  • Se especifican la precisión (P) y la escala (S): [-10P-S + 10-S, 10P-S - 10-S]
  • Se especifica la precisión (P), pero no la escala (por lo que se interpreta que la escala es igual a cero): [-10P + 1, 10P - 1].

Valores aceptables para la precisión y la escala si se especifican ambos:

  • Si type = "NUMERIC": 1 ≤ precisión - escala ≤ 29 y 0 ≤ escala ≤ 9.
  • Si type = "BIGNUMERIC": 1 ≤ precisión - escala ≤ 38 y 0 ≤ escala ≤ 38.

Valores aceptables de precisión si solo se especifica la precisión, pero no la escala (por lo que se interpreta que la escala es igual a cero):

  • Si type = "NUMERIC", 1 ≤ precisión ≤ 29.
  • Si type = "BIGNUMERIC", 1 ≤ precisión ≤ 38.

Si se especifica la escala, pero no la precisión, no será válido.
scale

string (int64 format)

Opcional. Consulta la documentación para obtener información sobre la precisión.
timestampPrecision

string (Int64Value format)

Opcional. Precisión (número máximo de dígitos totales en base 10) de los segundos del tipo TIMESTAMP.

Entre los valores posibles se incluyen los siguientes: * 6 (valor predeterminado para el tipo TIMESTAMP con precisión de microsegundos) * 12 (para el tipo TIMESTAMP con precisión de picosegundos)
roundingMode

enum (RoundingMode)

Opcional. Especifica el modo de redondeo que se debe usar al almacenar valores de tipo NUMERIC y BIGNUMERIC.
collation

string

Opcional. La ordenación de campos solo se puede definir cuando el tipo de campo es STRING. Se admiten los siguientes valores:

  • 'und:ci': configuración regional indeterminada, sin distinción entre mayúsculas y minúsculas.
  • '': cadena vacía. Se distingue entre mayúsculas y minúsculas de forma predeterminada.
defaultValueExpression

string

Opcional. Una expresión SQL para especificar el valor predeterminado de este campo.
rangeElementType

object (FieldElementType)

Opcional. Subtipo de RANGE, si el tipo de este campo es RANGE. Si el tipo es INTERVALO, este campo es obligatorio. Los valores del tipo de elemento de campo pueden ser los siguientes:

  • FECHA
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

Opcional. Definición del tipo de datos externo. Solo es válido para los campos de esquema de nivel superior (no para los campos anidados). Si el tipo es EXTERNO, este campo es obligatorio.
Representación JSON 
{
  "value": string
}
Campos
value

string

Valor de cadena.
Representación JSON 
{
  "names": [
    string
  ]
}
Campos
names[]

string

Lista de nombres de recursos de etiquetas de política. Por ejemplo, "projects/1/locations/eu/taxonomies/2/policyTags/3". Actualmente, se permite 1 etiqueta de política como máximo.
Representación JSON 
{

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

Campo de unión _name.

_name solo puede ser una de estas dos opciones:
name

string

Nombre de recurso de la política de datos con el formato projects/project_id/locations/location_id/dataPolicies/data_policy_id.
Representación JSON 
{
  "value": string
}
Campos
value

string (int64 format)

Valor int64.
Representación JSON 
{
  "type": string
}
Campos
type

string

Obligatorio. Tipo de elemento de campo. Para obtener más información, consulta TableFieldSchema.type.
Representación JSON 
{
  "typeSystem": enum (TypeSystem)
}
Campos
typeSystem

enum (TypeSystem)

Obligatorio. Especifica el sistema que define el tipo de datos externos.
Representación JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campos
fields

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

Mapa desordenado de valores con tipo dinámico.

Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
Representación JSON 
{
  "key": string,
  "value": value
}
Campos
key

string
value

value (Value format)
Representación JSON 
{

  // 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.
}
Campos
Campo de unión kind. El tipo de valor. kind solo puede ser una de estas dos opciones:
nullValue

null

Representa un valor nulo.
numberValue

number

Representa un valor doble.
stringValue

string

Representa un valor de cadena.
boolValue

boolean

Representa un valor booleano.
structValue

object (Struct format)

Representa un valor estructurado.
listValue

array (ListValue format)

Representa un Value repetido.
Representación JSON 
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Campo repetido de valores con tipo dinámico.
Representación JSON 
{
  "value": boolean
}
Campos
value

boolean

Valor booleano.
Representación JSON 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
Campos
reason

string

Un código de error breve que resume el error.
location

string

Especifica dónde se ha producido el error, si es que se ha producido alguno.
debugInfo

string

Información de depuración. Esta propiedad es interna de Google y no debe usarse.
message

string

Descripción del error con formato legible para humanos.

Anotaciones de herramientas

Pista destructiva: ✅ | Pista idempotente: ❌ | Pista de solo lectura: ❌ | Pista de mundo abierto: ✅