MCP Tools Reference: bigquery.googleapis.com

Ferramenta: execute_sql

Executar uma consulta SQL no projeto e devolver o resultado.

Esta ferramenta está restrita apenas a declarações SELECT. As declarações INSERT, UPDATE e DELETE, bem como os procedimentos armazenados, não são permitidos. Se a consulta não incluir uma declaração SELECT, é devolvido um erro. Para obter informações sobre como criar consultas, consulte a documentação do GoogleSQL.

A ferramenta execute_sql também pode ter efeitos secundários se a consulta invocar funções remotas ou UDFs do Python.

Todas as consultas executadas através da ferramenta execute_sql têm uma etiqueta que identifica a ferramenta como a origem. Pode usar esta etiqueta para filtrar as consultas através do par de etiqueta e valor goog-mcp-server: true.

As consultas são cobradas ao projeto especificado no campo project_id.

O exemplo seguinte demonstra como usar curl para invocar a ferramenta MCP execute_sql.

Pedido 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

Executa uma consulta SQL do BigQuery de forma síncrona e devolve os resultados da consulta se esta for concluída dentro de um limite de tempo especificado.

Representação JSON 
{
  "projectId": string,
  "query": string,
  "dryRun": boolean
}
Campos
projectId

string

Obrigatório. Projeto que vai ser usado para a execução de consultas e a faturação.
query

string

Obrigatório. A consulta a executar sob a forma de uma consulta GoogleSQL.
dryRun

boolean

Opcional. Se estiver definida como verdadeira, o BigQuery não executa a tarefa. Em alternativa, se a consulta for válida, o BigQuery devolve estatísticas sobre a tarefa, como o número de bytes que seriam processados. Se a consulta for inválida, é devolvido um erro. O valor predefinido é false.

Esquema de saída

Resposta para uma consulta SQL do BigQuery.

Representação JSON 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ]
}
Campos
schema

object (TableSchema)

O esquema dos resultados. Presente apenas quando a consulta é concluída com êxito.
rows[]

object (Struct format)

Um objeto com tantos resultados quanto os que podem ser incluídos no tamanho máximo permitido da resposta. Para obter linhas adicionais, pode chamar GetQueryResults e especificar o jobReference devolvido acima.
jobComplete

boolean

Se a consulta foi concluída ou não. Se rows ou totalRows estiverem presentes, esta propriedade é sempre verdadeira. Se for falso, totalRows não está disponível.
errors[]

object (ErrorProto)

Apenas saída. Os primeiros erros ou avisos encontrados durante a execução da tarefa. A mensagem final inclui o número de erros que fizeram com que o processo parasse. Os erros aqui não significam necessariamente que a tarefa foi concluída ou não foi bem-sucedida. Para mais informações acerca das mensagens de erro, consulte o artigo Mensagens de erro.
Representação JSON 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
Campos
fields[]

object (TableFieldSchema)

Descreve os campos numa tabela.
foreignTypeInfo

object (ForeignTypeInfo)

Opcional. Especifica os metadados da definição do tipo de dados externo no esquema de campos (TableFieldSchema.foreign_type_definition).
Representação 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

Obrigatório. O nome do campo. O nome tem de conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_) e tem de começar por uma letra ou um sublinhado. O comprimento máximo é de 300 carateres.
type

string

Obrigatório. O tipo de dados do campo. Os valores possíveis incluem:

  • STRING
  • BYTES
  • INTEGER (ou INT64)
  • FLOAT (ou FLOAT64)
  • BOOLEANO (ou BOOL)
  • TIMESTAMP
  • DATA
  • HORA
  • DATA/HORA
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • RECORD (ou STRUCT)
  • RANGE

A utilização de RECORD/STRUCT indica que o campo contém um esquema aninhado.
mode

string

Opcional. O campo mode. Os valores possíveis incluem NULLABLE, REQUIRED e REPEATED. O valor predefinido é NULLABLE.
fields[]

object (TableFieldSchema)

Opcional. Descreve os campos do esquema aninhado se a propriedade de tipo estiver definida como RECORD.
description

string

Opcional. A descrição do campo. O comprimento máximo é de 1024 carateres.
policyTags

object (PolicyTagList)

Opcional. As etiquetas de políticas anexadas a este campo, usadas para o controlo de acesso ao nível do campo. Se não estiver definido, o valor predefinido é policy_tags vazio.
dataPolicies[]

object (DataPolicyOption)

Opcional. Políticas de dados anexadas a este campo, usadas para o controlo de acesso ao nível do campo.
nameAlternative[]

string

Este campo não deve ser usado.
maxLength

string (int64 format)

Opcional. Comprimento máximo dos valores deste campo para STRINGS ou BYTES.

Se max_length não for especificado, não é imposta nenhuma restrição de comprimento máximo neste campo.

Se type = "STRING", max_length representa o comprimento máximo UTF-8 das strings neste campo.

Se type = "BYTES", max_length representa o número máximo de bytes neste campo.

Não é válido definir este campo se o tipo for diferente de "STRING" e "BYTES".
precision

string (int64 format)

Opcional. Restrições de precisão (número máximo de dígitos totais na base 10) e escala (número máximo de dígitos na parte fracionária na base 10) para valores deste campo para NUMERIC ou BIGNUMERIC.

Não é válido definir a precisão ou a escala se o tipo for diferente de "NUMERIC" e "BIGNUMERIC".

Se a precisão e a escala não forem especificadas, não é imposta nenhuma restrição de intervalo de valores neste campo, na medida em que os valores são permitidos pelo tipo.

Os valores deste campo NUMERIC ou BIGNUMERIC têm de estar neste intervalo quando:

  • A precisão (P) e a escala (S) são especificadas: [-10P-S + 10-S, 10P-S - 10-S]
  • A precisão (P) é especificada, mas não a escala (e, por isso, a escala é interpretada como igual a zero): [-10P + 1, 10P - 1].

Valores aceitáveis para a precisão e a escala se ambas forem especificadas:

  • Se type = "NUMERIC": 1 ≤ precision - scale ≤ 29 e 0 ≤ scale ≤ 9.
  • Se o tipo for "BIGNUMERIC": 1 ≤ precisão - escala ≤ 38 e 0 ≤ escala ≤ 38.

Valores aceitáveis para a precisão se apenas a precisão for especificada, mas não a escala (e, por isso, a escala é interpretada como igual a zero):

  • Se type = "NUMERIC": 1 ≤ precisão ≤ 29.
  • Se type = "BIGNUMERIC": 1 ≤ precisão ≤ 38.

Se a escala for especificada, mas a precisão não, é inválido.
scale

string (int64 format)

Opcional. Consulte a documentação para ver a precisão.
timestampPrecision

string (Int64Value format)

Opcional. Precisão (número máximo de dígitos totais na base 10) para segundos do tipo TIMESTAMP.

Os valores possíveis incluem: * 6 (predefinição, para o tipo TIMESTAMP com precisão de microssegundos) * 12 (para o tipo TIMESTAMP com precisão de picossegundos)
roundingMode

enum (RoundingMode)

Opcional. Especifica o modo de arredondamento a usar ao armazenar valores do tipo NUMERIC e BIGNUMERIC.
collation

string

Opcional. A ordenação de campos só pode ser definida quando o tipo de campo é STRING. Os seguintes valores são suportados:

  • 'und:ci': local indeterminado, sem distinção entre maiúsculas e minúsculas.
  • "": string vazia. Comportamento predefinido sensível a maiúsculas e minúsculas.
defaultValueExpression

string

Opcional. Uma expressão SQL para especificar o valor predefinido deste campo.
rangeElementType

object (FieldElementType)

Opcional. O subtipo do INTERVALO, se o tipo deste campo for INTERVALO. Se o tipo for RANGE, este campo é obrigatório. Os valores para o tipo de elemento de campo podem ser os seguintes:

  • DATA
  • DATA/HORA
  • TIMESTAMP
foreignTypeDefinition

string

Opcional. Definição do tipo de dados externo. Válido apenas para campos de esquema de nível superior (não campos aninhados). Se o tipo for FOREIGN, este campo é obrigatório.
Representação JSON 
{
  "value": string
}
Campos
value

string

O valor de string.
Representação JSON 
{
  "names": [
    string
  ]
}
Campos
names[]

string

Uma lista de nomes de recursos de etiquetas de políticas. Por exemplo, "projects/1/locations/eu/taxonomies/2/policyTags/3". Atualmente, é permitida, no máximo, 1 etiqueta de política.
Representação 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ão _name.

_name só pode ser uma das seguintes opções:
name

string

Nome do recurso da política de dados no formato projects/project_id/locations/location_id/dataPolicies/data_policy_id.
Representação JSON 
{
  "value": string
}
Campos
value

string (int64 format)

O valor int64.
Representação JSON 
{
  "type": string
}
Campos
type

string

Obrigatório. O tipo de um elemento de campo. Para mais informações, consulte TableFieldSchema.type.
Representação JSON 
{
  "typeSystem": enum (TypeSystem)
}
Campos
typeSystem

enum (TypeSystem)

Obrigatório. Especifica o sistema que define o tipo de dados externos.
Representação JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campos
fields

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

Mapa não ordenado de valores com tipo dinâmico.

Um objeto que contém uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
Representação JSON 
{
  "key": string,
  "value": value
}
Campos
key

string
value

value (Value format)
Representação 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ão kind. O tipo de valor. kind só pode ser uma das seguintes opções:
nullValue

null

Representa um valor nulo.
numberValue

number

Representa um valor duplo.
stringValue

string

Representa um valor de string.
boolValue

boolean

Representa um valor booleano.
structValue

object (Struct format)

Representa um valor estruturado.
listValue

array (ListValue format)

Representa um Value repetido.
Representação JSON 
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Campo repetido de valores com tipo dinâmico.
Representação JSON 
{
  "value": boolean
}
Campos
value

boolean

O valor bool.
Representação JSON 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
Campos
reason

string

Um código de erro curto que resume o erro.
location

string

Especifica onde ocorreu o erro, se estiver presente.
debugInfo

string

Informações de depuração. Esta propriedade é interna à Google e não deve ser usada.
message

string

Uma descrição legível do erro.

Anotações de ferramentas

Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅