MCP Tools Reference: bigquery.googleapis.com

Ferramenta: execute_sql

Executa uma consulta SQL no projeto e retorna o resultado.

Essa ferramenta é restrita apenas a declarações SELECT. Não é permitido usar instruções e procedimentos armazenados INSERT, UPDATE e DELETE. Se a consulta não incluir uma instrução SELECT, um erro será retornado. Para informações sobre como criar consultas, consulte a documentação do GoogleSQL.

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

Todas as consultas executadas com a ferramenta execute_sql têm um rótulo que a identifica como a fonte. Use esse rótulo para filtrar as consultas com o par rótulo-valor goog-mcp-server: true.

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

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

Solicitação 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 retorna os resultados se ela for concluída dentro de um tempo limite especificado.

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

string

Obrigatório. Projeto que será usado para execução de consultas e faturamento.
query

string

Obrigatório. A consulta a ser executada na forma de uma consulta do GoogleSQL.
dryRun

boolean

Opcional. Se definido como "true", o BigQuery não vai executar o job. Em vez disso, se a consulta for válida, o BigQuery vai retornar estatísticas sobre o job, como quantos bytes seriam processados. Se a consulta for inválida, um erro será retornado. O valor padrão é falso.

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 sucesso.
rows[]

object (Struct format)

Um objeto com tantos resultados quanto se permite armazenar em uma resposta. Para receber outras linhas, chame GetQueryResults e especifique o jobReference retornado acima.
jobComplete

boolean

Se a consulta foi concluída ou não. Se existirem linhas ou se totalRows estiver presente, isso será sempre verdadeiro. Se falso, totalRows não estará disponível.
errors[]

object (ErrorProto)

Apenas saída. Os primeiros erros ou avisos encontrados durante a execução do job. A mensagem final inclui o número de erros que causaram a interrupção do processo. Erros aqui não indicam necessariamente que o trabalho foi concluído ou falhou. Para mais informações sobre mensagens de erro, consulte Mensagens de erro.
Representação JSON 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
Campos
fields[]

object (TableFieldSchema)

Descreve os campos na tabela.
foreignTypeInfo

object (ForeignTypeInfo)

Opcional. Especifica metadados da definição do tipo de dados externo no esquema de campo (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. Nome do campo. O nome precisa conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_) e começar com uma letra ou sublinhado. O tamanho máximo é de 300 caracteres.
type

string

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

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

O uso de RECORD/STRUCT indica que o campo contém um esquema aninhado.
mode

string

Opcional. O modo do campo. Os valores possíveis incluem NULLABLE, REQUIRED e REPEATED. O valor padrão é NULLABLE.
fields[]

object (TableFieldSchema)

Opcional. Descreve os campos de esquema aninhados se a propriedade "type" estiver definida como "RECORD".
description

string

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

object (PolicyTagList)

Opcional. As tags de política anexadas a esse campo, usadas para controle de acesso no nível do campo. Se não for definido, o padrão será "policy_tags" vazio.
dataPolicies[]

object (DataPolicyOption)

Opcional. Políticas de dados anexadas a este campo, usadas para controle de acesso no 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, nenhuma restrição de tamanho máximo será imposta a esse campo.

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

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

Não é possível definir esse 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 desse campo para NUMERIC ou BIGNUMERIC.

Não é possível definir precisão ou escala se o tipo não for "NUMERIC" nem "BIGNUMERIC".

Se a precisão e a escala não forem especificadas, nenhuma restrição de intervalo de valores será imposta a esse campo, desde que os valores sejam permitidos pelo tipo.

Os valores desse campo NUMERIC ou BIGNUMERIC precisam estar nesse intervalo quando:

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

Valores aceitáveis para precisão e escala, se ambos forem especificados:

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

Valores aceitáveis para precisão se apenas a precisão for especificada, mas não a escala (e, portanto, a escala for 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 não a precisão, ela será inválida.
scale

string (int64 format)

Opcional. Consulte a documentação para saber mais sobre 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 (padrã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 ser usado 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 valores a seguir são compatíveis:

  • 'und:ci': localidade indeterminada, sem diferenciação de maiúsculas e minúsculas.
  • '': string vazia. O padrão é diferenciar maiúsculas de minúsculas.
defaultValueExpression

string

Opcional. Uma expressão SQL para especificar o valor padrão desse campo.
rangeElementType

object (FieldElementType)

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

  • DATE
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

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

string

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

string

Uma lista de nomes de recursos de tag de política. Por exemplo, "projects/1/locations/eu/taxonomies/2/policyTags/3". No momento, é permitida apenas uma tag 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 pode ser apenas de um dos tipos a seguir:
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. Veja mais informações em TableFieldSchema.type.
Representação JSON 
{
  "typeSystem": enum (TypeSystem)
}
Campos
typeSystem

enum (TypeSystem)

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

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

Mapa não ordenado de valores com tipagem dinâmica.

Um objeto com 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 pode ser apenas de um dos tipos a seguir:
nullValue

null

Representa um valor nulo.
numberValue

number

Representa um valor double.
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 digitados dinamicamente.
Representação JSON 
{
  "value": boolean
}
Campos
value

boolean

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

string

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

string

Especifica onde ocorreu o erro, se presente.
debugInfo

string

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

string

Uma descrição legível por humanos do erro.

Anotações de ferramentas

Dica destrutiva: ✅ | Dica idempotente: ❌ | Dica somente leitura: ❌ | Dica de mundo aberto: ✅