Console
    Start free

    MCP Tools Reference: bigquery.googleapis.com

    Tool: execute_sql

    Run a SQL query in the project and return the result.

    This tool is restricted to only SELECT statements. INSERT , UPDATE , and DELETE statements and stored procedures aren't allowed. If the query doesn't include a SELECT statement, an error is returned. For information on creating queries, see the GoogleSQL documentation .

    The execute_sql tool can also have side effects if the the query invokes remote functions or Python UDFs .

    All queries that are run using the execute_sql tool have a label that identifies the tool as the source. You can use this label to filter the queries using the label and value pair goog-mcp-server: true .

    Queries are charged to the project specified in the project_id field.

    The following sample demonstrate how to use curl to invoke the execute_sql MCP tool.

    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", 
 "arguments": { 
 // provide these details according to the tool' 
s  
MCP  
specification  
 } 
  
 } 
,  
 "jsonrpc" 
:  
 "2.0" 
,  
 "id" 
:  
 1 
 } 
 '

    Input Schema

    Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout.

    JSON representation 
     { 
 "projectId" 
 : 
 string 
 , 
 "query" 
 : 
 string 
 , 
 "dryRun" 
 : 
 boolean 
 }
    Fields
    projectId

    string

    Required. Project that will be used for query execution and billing.
    query

    string

    Required. The query to execute in the form of a GoogleSQL query.
    dryRun

    boolean

    Optional. If set to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false.

    Output Schema

    Response for a BigQuery SQL query.

    JSON representation 
     { 
 "schema" 
 : 
 { 
 object ( TableSchema 
) 
 } 
 , 
 "rows" 
 : 
 [ 
 { 
 object 
 } 
 ] 
 , 
 "jobComplete" 
 : 
 boolean 
 , 
 "errors" 
 : 
 [ 
 { 
 object ( ErrorProto 
) 
 } 
 ] 
 }
    Fields
    schema

    object ( TableSchema )

    The schema of the results. Present only when the query completes successfully.
    rows[]

    object ( Struct format)

    An object with as many results as can be contained within the maximum permitted reply size. To get any additional rows, you can call GetQueryResults and specify the jobReference returned above.
    jobComplete

    boolean

    Whether the query has completed or not. If rows or totalRows are present, this will always be true. If this is false, totalRows will not be available.
    errors[]

    object ( ErrorProto )

    Output only. The first errors or warnings encountered during the running of the job. The final message includes the number of errors that caused the process to stop. Errors here do not necessarily mean that the job has completed or was unsuccessful. For more information about error messages, see Error messages .
    JSON representation 
     { 
 "fields" 
 : 
 [ 
 { 
 object ( TableFieldSchema 
) 
 } 
 ] 
 , 
 "foreignTypeInfo" 
 : 
 { 
 object ( ForeignTypeInfo 
) 
 } 
 }
    Fields
    fields[]

    object ( TableFieldSchema )

    Describes the fields in a table.
    foreignTypeInfo

    object ( ForeignTypeInfo )

    Optional. Specifies metadata of the foreign data type definition in field schema ( TableFieldSchema.foreign_type_definition ).
    JSON representation 
     { 
 "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 
 }
    Fields
    name

    string

    Required. The field name. The name must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_), and must start with a letter or underscore. The maximum length is 300 characters.

    type

    string

    Required. The field data type. Possible values include:

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

    Use of RECORD/STRUCT indicates that the field contains a nested schema.

    mode

    string

    Optional. The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.

    fields[]

    object ( TableFieldSchema )

    Optional. Describes the nested schema fields if the type property is set to RECORD.

    description

    string

    Optional. The field description. The maximum length is 1,024 characters.

    policyTags

    object ( PolicyTagList )

    Optional. The policy tags attached to this field, used for field-level access control. If not set, defaults to empty policy_tags.

    dataPolicies[]

    object ( DataPolicyOption )

    Optional. Data policies attached to this field, used for field-level access control.

    nameAlternative[]

    string

    This field should not be used.

    maxLength

    string ( int64 format)

    Optional. Maximum length of values of this field for STRINGS or BYTES.

    If max_length is not specified, no maximum length constraint is imposed on this field.

    If type = "STRING", then max_length represents the maximum UTF-8 length of strings in this field.

    If type = "BYTES", then max_length represents the maximum number of bytes in this field.

    It is invalid to set this field if type ≠ "STRING" and ≠ "BYTES".

    precision

    string ( int64 format)

    Optional. Precision (maximum number of total digits in base 10) and scale (maximum number of digits in the fractional part in base 10) constraints for values of this field for NUMERIC or BIGNUMERIC.

    It is invalid to set precision or scale if type ≠ "NUMERIC" and ≠ "BIGNUMERIC".

    If precision and scale are not specified, no value range constraint is imposed on this field insofar as values are permitted by the type.

    Values of this NUMERIC or BIGNUMERIC field must be in this range when:

    • Precision ( P ) and scale ( S ) are specified: [-10 P - S + 10 - S , 10 P - S - 10 - S ]
    • Precision ( P ) is specified but not scale (and thus scale is interpreted to be equal to zero): [-10 P + 1, 10 P - 1].

    Acceptable values for precision and scale if both are specified:

    • If type = "NUMERIC": 1 ≤ precision - scale ≤ 29 and 0 ≤ scale ≤ 9.
    • If type = "BIGNUMERIC": 1 ≤ precision - scale ≤ 38 and 0 ≤ scale ≤ 38.

    Acceptable values for precision if only precision is specified but not scale (and thus scale is interpreted to be equal to zero):

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

    If scale is specified but not precision, then it is invalid.

    scale

    string ( int64 format)

    Optional. See documentation for precision.

    timestampPrecision

    string ( Int64Value format)

    Optional. Precision (maximum number of total digits in base 10) for seconds of TIMESTAMP type.

    Possible values include: * 6 (Default, for TIMESTAMP type with microsecond precision) * 12 (For TIMESTAMP type with picosecond precision)

    roundingMode

    enum ( RoundingMode )

    Optional. Specifies the rounding mode to be used when storing values of NUMERIC and BIGNUMERIC type.

    collation

    string

    Optional. Field collation can be set only when the type of field is STRING. The following values are supported:

    • 'und:ci': undetermined locale, case insensitive.
    • '': empty string. Default to case-sensitive behavior.
    defaultValueExpression

    string

    Optional. A SQL expression to specify the default value for this field.

    rangeElementType

    object ( FieldElementType )

    Optional. The subtype of the RANGE, if the type of this field is RANGE. If the type is RANGE, this field is required. Values for the field element type can be the following:

    • DATE
    • DATETIME
    • TIMESTAMP
    foreignTypeDefinition

    string

    Optional. Definition of the foreign data type. Only valid for top-level schema fields (not nested fields). If the type is FOREIGN, this field is required.

    JSON representation 
     { 
 "value" 
 : 
 string 
 }
    Fields
    value

    string

    The string value.
    JSON representation 
     { 
 "names" 
 : 
 [ 
 string 
 ] 
 }
    Fields
    names[]

    string

    A list of policy tag resource names. For example, "projects/1/locations/eu/taxonomies/2/policyTags/3". At most 1 policy tag is currently allowed.
    JSON representation 
     { 
 // Union field _name 
can be only one of the following: 
 "name" 
 : 
 string 
 // End of list of possible types for union field _name 
. 
 }
    Fields

    Union field _name .

    _name can be only one of the following:

    name

    string

    Data policy resource name in the form of projects/project_id/locations/location_id/dataPolicies/data_policy_id.

    JSON representation 
     { 
 "value" 
 : 
 string 
 }
    Fields
    value

    string ( int64 format)

    The int64 value.
    JSON representation 
     { 
 "type" 
 : 
 string 
 }
    Fields
    type

    string

    Required. The type of a field element. For more information, see TableFieldSchema.type .
    JSON representation 
     { 
 "typeSystem" 
 : 
 enum ( TypeSystem 
) 
 }
    Fields
    typeSystem

    enum ( TypeSystem )

    Required. Specifies the system which defines the foreign data type.
    JSON representation 
     { 
 "fields" 
 : 
 { 
 string 
 : 
 value 
 , 
 ... 
 } 
 }
    Fields
    fields

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

    Unordered map of dynamically typed values.

    An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" } .
    JSON representation 
     { 
 "key" 
 : 
 string 
 , 
 "value" 
 : 
 value 
 }
    Fields
    key

    string

    value

    value ( Value format)

    JSON representation 
     { 
 // 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 
. 
 }
    Fields
    Union field kind . The kind of value. kind can be only one of the following:
    nullValue

    null

    Represents a null value.

    numberValue

    number

    Represents a double value.

    stringValue

    string

    Represents a string value.

    boolValue

    boolean

    Represents a boolean value.

    structValue

    object ( Struct format)

    Represents a structured value.

    listValue

    array ( ListValue format)

    Represents a repeated Value .

    JSON representation 
     { 
 "values" 
 : 
 [ 
 value 
 ] 
 }
    Fields
    values[]

    value ( Value format)

    Repeated field of dynamically typed values.
    JSON representation 
     { 
 "value" 
 : 
 boolean 
 }
    Fields
    value

    boolean

    The bool value.
    JSON representation 
     { 
 "reason" 
 : 
 string 
 , 
 "location" 
 : 
 string 
 , 
 "debugInfo" 
 : 
 string 
 , 
 "message" 
 : 
 string 
 }
    Fields
    reason

    string

    A short error code that summarizes the error.
    location

    string

    Specifies where the error occurred, if present.
    debugInfo

    string

    Debugging information. This property is internal to Google and should not be used.
    message

    string

    A human-readable description of the error.

    Tool Annotations

    Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: