MCP Tools Reference: bigquery.googleapis.com

Strumento: execute_sql_readonly

Esegui una query SQL di sola lettura nel progetto e restituisci il risultato. Se possibile, preferisci questo strumento a execute_sql.

Questo strumento è limitato solo agli estratti conto SELECT. Le istruzioni e le procedure archiviate INSERT, UPDATE e DELETE non sono consentite. Se la query non include un'istruzione SELECT, viene restituito un errore. Per informazioni sulla creazione di query, consulta la documentazione di GoogleSQL.

Le query eseguite utilizzando lo strumento execute_sql_readonly avranno l'etichetta del job goog-mcp-server: true impostata automaticamente. Le query vengono addebitate al progetto specificato nel campo project_id.

Il seguente esempio mostra come utilizzare curl per richiamare lo strumento MCP execute_sql_readonly.

Curl Request 
                  
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
}'

Schema di input

Esegue una query SQL BigQuery in modo sincrono e restituisce i risultati se la query viene completata prima di un timeout specificato.

QueryRequest

Rappresentazione JSON 
{
  "projectId": string,
  "query": string,
  "dryRun": boolean
}
Campi
projectId

string

Obbligatorio. Progetto che verrà utilizzato per l'esecuzione delle query e la fatturazione.
query

string

Obbligatorio. Query da eseguire sotto forma di query GoogleSQL.
dryRun

boolean

Facoltativo. Se il valore è true, BigQuery non esegue il job. Se la query è valida, BigQuery restituisce statistiche sul job, ad esempio il numero di byte che verranno elaborati. Se la query non è valida, viene restituito un errore. Il valore predefinito è false.

Schema di output

Risposta per una query SQL di BigQuery.

QueryResponse

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

object (TableSchema)

Lo schema dei risultati. Presente solo al termine della query.
rows[]

object (Struct format)

Un oggetto con il maggior numero possibile di risultati contenuti nella dimensione massima consentita della risposta. Per ottenere altre righe, puoi chiamare GetQueryResults e specificare jobReference restituito sopra.
jobComplete

boolean

Indica se la query è stata completata o meno. Se sono presenti righe o totalRows, questo valore sarà sempre true. Se questo valore è false, totalRows non sarà disponibile.
errors[]

object (ErrorProto)

Solo output. I primi errori o avvisi riscontrati durante l'esecuzione del job. Il messaggio finale include il numero di errori che hanno causato l'interruzione della procedura. Gli errori qui non significano necessariamente che il job è stato completato o non è andato a buon fine. Per ulteriori informazioni sui messaggi di errore, vedi Messaggi di errore.
queryId

string

Solo output. L'ID della query.
totalBytesBilled

string (Int64Value format)

Solo output. Il numero totale di byte fatturati per la query. Si applica solo se il progetto è configurato per utilizzare i prezzi on demand.
totalSlotMs

string (Int64Value format)

Solo output. Numero di millisecondi di slot per cui viene effettivamente addebitato l'utente.
numDmlAffectedRows

string (Int64Value format)

Solo output. Il numero di righe interessate da un'istruzione DML.
totalBytesProcessed

string (Int64Value format)

Solo output. Il numero totale di byte elaborati per questa query.

TableSchema

Rappresentazione JSON 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
Campi
fields[]

object (TableFieldSchema)

Descrive i campi di una tabella.
foreignTypeInfo

object (ForeignTypeInfo)

Facoltativo. Specifica i metadati della definizione del tipo di dati esterni nello schema del campo (TableFieldSchema.foreign_type_definition).

TableFieldSchema

Rappresentazione 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)
  }
}
Campi
name

string

Obbligatorio. Il nome del campo. Il nome deve contenere solo lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_) e deve iniziare con una lettera o un trattino basso. La lunghezza massima è di 300 caratteri.
type

string

Obbligatorio. Il tipo di dati del campo. I valori possibili sono:

  • STRING
  • BYTES
  • INTEGER (o INT64)
  • FLOAT (o FLOAT64)
  • BOOLEANO (o BOOL)
  • TIMESTAMP
  • DATA
  • TEMPO
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • RECORD (o STRUCT)
  • RANGE

L'utilizzo di RECORD/STRUCT indica che il campo contiene uno schema nidificato.
mode

string

Facoltativo. La modalità campo. I valori possibili includono NULLABLE, REQUIRED e REPEATED. Il valore predefinito è NULLABLE.
fields[]

object (TableFieldSchema)

Facoltativo. Descrive i campi dello schema nidificati se la proprietà type è impostata su RECORD.
description

string

Facoltativo. La descrizione del campo. La lunghezza massima è di 1024 caratteri.
policyTags

object (PolicyTagList)

Facoltativo. I tag criterio collegati a questo campo, utilizzati per controllo dell'accesso a livello di campo. Se non viene impostato, il valore predefinito è policy_tags vuoto.
dataPolicies[]

object (DataPolicyOption)

Facoltativo. Policy dei dati associate a questo campo, utilizzate per controllo dell'accesso a livello di campo.
maxLength

string (int64 format)

Facoltativo. Lunghezza massima dei valori di questo campo per STRINGHE o BYTE.

Se max_length non è specificato, non viene imposto alcun vincolo di lunghezza massima a questo campo.

Se type = "STRING", max_length rappresenta la lunghezza massima UTF-8 delle stringhe in questo campo.

Se type = "BYTES", max_length rappresenta il numero massimo di byte in questo campo.

Non è valido impostare questo campo se type ≠ "STRING" e ≠ "BYTES".
precision

string (int64 format)

Facoltativo. Vincoli di precisione (numero massimo di cifre totali in base 10) e scala (numero massimo di cifre nella parte frazionaria in base 10) per i valori di questo campo per NUMERIC o BIGNUMERIC.

Non è valido impostare la precisione o la scala se il tipo è diverso da "NUMERIC" e "BIGNUMERIC".

Se non vengono specificati precisione e scala, a questo campo non viene imposto alcun vincolo di intervallo di valori, a condizione che i valori siano consentiti dal tipo.

I valori di questo campo NUMERIC o BIGNUMERIC devono essere compresi in questo intervallo quando:

  • Sono specificati precisione (P) e scala (S): [-10P-S + 10-S, 10P-S - 10-S]
  • La precisione (P) è specificata, ma non la scala (che quindi viene interpretata come uguale a zero): [-10P + 1, 10P - 1].

Valori accettabili per precisione e scala se vengono specificati entrambi:

  • Se type = "NUMERIC": 1 ≤ precision - scale ≤ 29 e 0 ≤ scale ≤ 9.
  • Se type = "BIGNUMERIC": 1 ≤ precisione - scalabilità ≤ 38 e 0 ≤ scalabilità ≤ 38.

Valori accettabili per la precisione se viene specificata solo la precisione, ma non la scala (e quindi la scala viene interpretata come uguale a zero):

  • Se type = "NUMERIC": 1 ≤ precision ≤ 29.
  • Se type = "BIGNUMERIC": 1 ≤ precision ≤ 38.

Se la scala è specificata, ma non la precisione, il valore non è valido.
scale

string (int64 format)

Facoltativo. Per informazioni dettagliate, consulta la documentazione.
timestampPrecision

string (Int64Value format)

Facoltativo. Precisione (numero massimo di cifre totali in base 10) per i secondi del tipo TIMESTAMP.

I valori possibili includono: * 6 (valore predefinito per il tipo TIMESTAMP con precisione al microsecondo) * 12 (per il tipo TIMESTAMP con precisione al picosecondo)
roundingMode

enum (RoundingMode)

Facoltativo. Specifica la modalità di arrotondamento da utilizzare per l'archiviazione dei valori di tipo NUMERIC e BIGNUMERIC.
collation

string

Facoltativo. Le regole di confronto dei campi possono essere impostate solo quando il tipo di campo è STRING. Sono supportati i seguenti valori:

  • 'und:ci': impostazioni internazionali non determinate, senza distinzione tra maiuscole e minuscole.
  • "": stringa vuota. Per impostazione predefinita viene applicato il comportamento sensibile alle maiuscole.
defaultValueExpression

string

Facoltativo. Un'espressione SQL per specificare il valore predefinito per questo campo.
rangeElementType

object (FieldElementType)

Facoltativo. Il sottotipo di RANGE, se il tipo di questo campo è RANGE. Se il tipo è INTERVALLO, questo campo è obbligatorio. I valori per il tipo di elemento del campo possono essere i seguenti:

  • DATA
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

Facoltativo. Definizione del tipo di dati esterni. Valido solo per i campi dello schema di primo livello (non per i campi nidificati). Se il tipo è ESTERO, questo campo è obbligatorio.
generatedColumn

object (GeneratedColumn)

Facoltativo. Definizione della modalità di generazione dei valori per il campo. Valido solo per i campi dello schema di primo livello (non per i campi nidificati).

StringValue

Rappresentazione JSON 
{
  "value": string
}
Campi
value

string

Il valore stringa.

PolicyTagList

Rappresentazione JSON 
{
  "names": [
    string
  ]
}
Campi
names[]

string

Un elenco di nomi di risorse tag di criteri. Ad esempio, "projects/1/locations/eu/taxonomies/2/policyTags/3". Al momento è consentito al massimo un tag di criteri.

DataPolicyOption

Rappresentazione JSON 
{

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

Campo unione _name.

_name può essere solo uno dei seguenti tipi:
name

string

Nome risorsa della policy sui dati nel formato projects/project_id/locations/location_id/dataPolicies/data_policy_id.

Int64Value

Rappresentazione JSON 
{
  "value": string
}
Campi
value

string (int64 format)

Il valore int64.

FieldElementType

Rappresentazione JSON 
{
  "type": string
}
Campi
type

string

Obbligatorio. Il tipo di un elemento del campo. Per ulteriori informazioni, vedi TableFieldSchema.type.

GeneratedColumn

Rappresentazione 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.
}
Campi

Campo unione _generated_mode.

_generated_mode può essere solo uno dei seguenti tipi:
generatedMode

enum (GeneratedMode)

Facoltativo. Determina quando i valori generati dal sistema vengono utilizzati per compilare il campo.

Campo unione definition.

definition può essere solo uno dei seguenti tipi:
generatedExpressionInfo

object (GeneratedExpressionInfo)

Definizione dell'espressione utilizzata per generare il campo.

GeneratedExpressionInfo

Rappresentazione 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.
}
Campi

Campo unione _generation_expression.

_generation_expression può essere solo uno dei seguenti tipi:
generationExpression

string

Facoltativo. L'espressione di generazione (ad es. AI.EMBED(...)) utilizzata per generare il campo.

Campo unione _asynchronous.

_asynchronous può essere solo uno dei seguenti tipi:
asynchronous

boolean

Facoltativo. Indica se la generazione di colonne viene eseguita in modo asincrono.

Campo unione _stored.

_stored può essere solo uno dei seguenti tipi:
stored

boolean

Facoltativo. Indica se la colonna generata è memorizzata nella tabella.

ForeignTypeInfo

Rappresentazione JSON 
{
  "typeSystem": enum (TypeSystem)
}
Campi
typeSystem

enum (TypeSystem)

Obbligatorio. Specifica il sistema che definisce il tipo di dati esterni.

Struct

Rappresentazione JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campi
fields

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

Mappa non ordinata di valori digitati dinamicamente.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Rappresentazione JSON 
{
  "key": string,
  "value": value
}
Campi
key

string
value

value (Value format)

Valore

Rappresentazione 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.
}
Campi
Campo unione kind. Il tipo di valore. kind può essere solo uno dei seguenti tipi:
nullValue

null

Rappresenta un null JSON.
numberValue

number

Rappresenta un numero JSON. Non deve essere NaN, Infinity o -Infinity, in quanto non sono supportati in JSON. Inoltre, non può rappresentare valori Int64 di grandi dimensioni, poiché il formato JSON in genere non li supporta nel suo tipo di numero.
stringValue

string

Rappresenta una stringa JSON.
boolValue

boolean

Rappresenta un valore booleano JSON (valore letterale true o false in JSON).
structValue

object (Struct format)

Rappresenta un oggetto JSON.
listValue

array (ListValue format)

Rappresenta un array JSON.

ListValue

Rappresentazione JSON 
{
  "values": [
    value
  ]
}
Campi
values[]

value (Value format)

Campo ripetuto di valori con tipo dinamico.

BoolValue

Rappresentazione JSON 
{
  "value": boolean
}
Campi
value

boolean

Il valore booleano.

ErrorProto

Rappresentazione JSON 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
Campi
reason

string

Un breve codice di errore che riassume l'errore.
location

string

Specifica dove si è verificato l'errore, se presente.
debugInfo

string

Informazioni di debug. Questa proprietà è interna a Google e non deve essere utilizzata.
message

string

Una descrizione dell'errore leggibile.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌