MCP Tools Reference: bigquery.googleapis.com

Ferramenta: execute_sql_readonly

Executa uma consulta SQL somente leitura no projeto e retorna o resultado. Prefira essa ferramenta em vez de execute_sql, se possível.

Essa ferramenta é restrita apenas a instruçõ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.

As consultas executadas com a ferramenta execute_sql_readonly têm o rótulo do job goog-mcp-server: true definido automaticamente. 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_readonly 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_readonly",
    "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.

QueryRequest

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.

QueryResponse

Representação JSON 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ],
  "queryId": string,
  "totalBytesBilled": string,
  "totalSlotMs": string,
  "numDmlAffectedRows": string,
  "totalBytesProcessed": string
}
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.
queryId

string

Apenas saída. O ID da consulta.
totalBytesBilled

string (Int64Value format)

Apenas saída. O número total de bytes faturados para a consulta. Só se aplica se o projeto estiver configurado para usar preços sob demanda.
totalSlotMs

string (Int64Value format)

Apenas saída. Número de ms de slot que o usuário realmente paga.
numDmlAffectedRows

string (Int64Value format)

Apenas saída. O número de linhas afetadas por uma instrução DML.
totalBytesProcessed

string (Int64Value format)

Apenas saída. O número total de bytes processados para esta consulta.

TableSchema

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).

TableFieldSchema

Representação JSON 
{
  "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)
  }
}
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.
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. 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", esse campo será obrigatório.
generatedColumn

object (GeneratedColumn)

Opcional. Definição de como os valores são gerados para o campo. Válido apenas para campos de esquema de nível superior (não aninhados).

StringValue

Representação JSON 
{
  "value": string
}
Campos
value

string

O valor da string.

PolicyTagList

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.

DataPolicyOption

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.

Int64Value

Representação JSON 
{
  "value": string
}
Campos
value

string (int64 format)

O valor int64.

FieldElementType

Representação JSON 
{
  "type": string
}
Campos
type

string

Obrigatório. O tipo de um elemento de campo. Veja mais informações em TableFieldSchema.type.

GeneratedColumn

Representação JSON 
{

  // 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.
}
Campos

Campo de união _generated_mode.

_generated_mode pode ser apenas de um dos tipos a seguir:
generatedMode

enum (GeneratedMode)

Opcional. Determina quando os valores gerados pelo sistema são usados para preencher o campo.

Campo de união definition.

definition pode ser apenas de um dos tipos a seguir:
generatedExpressionInfo

object (GeneratedExpressionInfo)

Definição da expressão usada para gerar o campo.

GeneratedExpressionInfo

Representação JSON 
{

  // 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.
}
Campos

Campo de união _generation_expression.

_generation_expression pode ser apenas de um dos tipos a seguir:
generationExpression

string

Opcional. A expressão de geração (por exemplo, AI.EMBED(...)) usada para gerar o campo.

Campo de união _asynchronous.

_asynchronous pode ser apenas de um dos tipos a seguir:
asynchronous

boolean

Opcional. Indica se a geração de colunas é feita de forma assíncrona.

Campo de união _stored.

_stored pode ser apenas de um dos tipos a seguir:
stored

boolean

Opcional. Se a coluna gerada está armazenada na tabela.

ForeignTypeInfo

Representação JSON 
{
  "typeSystem": enum (TypeSystem)
}
Campos
typeSystem

enum (TypeSystem)

Obrigatório. Especifica o sistema que define o tipo de dados externo.

Struct

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" }.

FieldsEntry

Representação JSON 
{
  "key": string,
  "value": value
}
Campos
key

string
value

value (Value format)

Valor

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 null JSON.
numberValue

number

Representa um número JSON. Não pode ser NaN, Infinity ou -Infinity, porque esses tipos não são compatíveis com JSON. Isso também não pode representar valores Int64 grandes, já que o formato JSON geralmente não os aceita no tipo de número.
stringValue

string

Representa uma string JSON.
boolValue

boolean

Representa um booleano JSON (literal true ou false em JSON).
structValue

object (Struct format)

Representa um objeto JSON.
listValue

array (ListValue format)

Representa uma matriz JSON.

ListValue

Representação JSON 
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Campo repetido de valores digitados dinamicamente.

BoolValue

Representação JSON 
{
  "value": boolean
}
Campos
value

boolean

O valor booleano.

ErrorProto

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 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 do erro.

Anotações de ferramentas

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