MCP Tools Reference: bigquery.googleapis.com

도구: `execute_sql`

프로젝트에서 SQL 쿼리를 실행하고 결과를 반환합니다. 가능하면 execute_sql_readonly 도구를 사용하세요.

이 도구는 다음을 비롯하여 BigQuery에서 지원하는 모든 쿼리를 실행할 수 있습니다. * SQL 쿼리 (SELECT, INSERT, UPDATE, DELETE, CREATE 등) * AI.FORECAST, ML.EVALUATE, ML.PREDICT와 같은 AI/ML 함수 * BigQuery에서 지원하는 기타 쿼리

execute_sql 도구를 사용하여 실행된 쿼리에는 작업 라벨 goog-mcp-server: true이 자동으로 설정됩니다. 쿼리 요금은 project_id 필드에 지정된 프로젝트에 청구됩니다.

다음 샘플은 curl를 사용하여 execute_sql MCP 도구를 호출하는 방법을 보여줍니다.

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

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

입력 스키마

BigQuery SQL 쿼리를 동기식으로 실행하고, 쿼리가 지정된 제한 시간 이내에 완료될 경우 쿼리 결과를 반환합니다.

QueryRequest

JSON 표현
{ "projectId": string, "query": string, "dryRun": boolean }

필드

필드
`projectId`	`string` 필수 항목입니다. 쿼리 실행 및 결제에 사용될 프로젝트입니다.
`query`	`string` 필수 항목입니다. 실행할 쿼리입니다(GoogleSQL 쿼리 형식).
`dryRun`	`boolean` 선택사항입니다. true로 설정하면 BigQuery에서 작업을 실행하지 않습니다. 대신 쿼리가 유효한 경우 BigQuery는 처리할 바이트 수와 같은 작업 통계를 반환합니다. 쿼리가 잘못된 경우 오류가 반환됩니다. 기본값은 false입니다.

projectId

string

필수 항목입니다. 쿼리 실행 및 결제에 사용될 프로젝트입니다.

query

string

필수 항목입니다. 실행할 쿼리입니다(GoogleSQL 쿼리 형식).

dryRun

boolean

선택사항입니다. true로 설정하면 BigQuery에서 작업을 실행하지 않습니다. 대신 쿼리가 유효한 경우 BigQuery는 처리할 바이트 수와 같은 작업 통계를 반환합니다. 쿼리가 잘못된 경우 오류가 반환됩니다. 기본값은 false입니다.

출력 스키마

BigQuery SQL 쿼리의 응답입니다.

QueryResponse

JSON 표현

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

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

필드
`schema`	`object (TableSchema)` 결과의 스키마입니다. 쿼리가 성공적으로 완료된 경우에만 표시됩니다.
`rows[]`	`object (Struct format)` 허용되는 최대 답장 크기 내에 포함될 수 있는 만큼의 결과가 있는 객체입니다. 추가 행을 가져오려면 GetQueryResults를 호출하고 위에서 반환된 jobReference를 지정하면 됩니다.
`jobComplete`	`boolean` 쿼리가 완료되었는지 여부입니다. rows 또는 totalRows가 있으면 항상 true입니다. 이 값이 false이면 totalRows를 사용할 수 없습니다.
`errors[]`	`object (ErrorProto)` 출력 전용입니다. 작업 실행 중에 발생한 첫 번째 오류 또는 경고입니다. 최종 메시지에는 프로세스가 중지된 원인이 된 오류 수가 포함됩니다. 여기에 오류가 표시된다고 해서 작업이 완료되었거나 실패했음을 의미하지는 않습니다. 오류 메시지에 관한 자세한 내용은 오류 메시지를 참고하세요.
`queryId`	`string` 출력 전용입니다. 쿼리 ID입니다.
`totalBytesBilled`	`string (Int64Value format)` 출력 전용입니다. 쿼리에 대해 청구된 총 바이트 수입니다. 프로젝트가 주문형 가격 책정을 사용하도록 구성된 경우에만 적용됩니다.
`totalSlotMs`	`string (Int64Value format)` 출력 전용입니다. 사용자에게 실제로 청구되는 슬롯 ms입니다.
`numDmlAffectedRows`	`string (Int64Value format)` 출력 전용입니다. DML 문에 의해 영향을 받는 행 수입니다.
`totalBytesProcessed`	`string (Int64Value format)` 출력 전용입니다. 이 쿼리에 대해 처리된 총 바이트 수입니다.

TableSchema

JSON 표현
{ "fields": [ { object (`TableFieldSchema`) } ], "foreignTypeInfo": { object (`ForeignTypeInfo`) } }

필드

필드
`fields[]`	`object (TableFieldSchema)` 표의 필드를 설명합니다.
`foreignTypeInfo`	`object (ForeignTypeInfo)` 선택사항입니다. 필드 스키마 (`TableFieldSchema.foreign_type_definition`)에서 외부 데이터 유형 정의의 메타데이터를 지정합니다.

fields[]

object (TableFieldSchema)

표의 필드를 설명합니다.

foreignTypeInfo

object (ForeignTypeInfo)

선택사항입니다. 필드 스키마 (TableFieldSchema.foreign_type_definition)에서 외부 데이터 유형 정의의 메타데이터를 지정합니다.

TableFieldSchema

JSON 표현

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`) } }

{
  "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)
  }
}

필드
`name`	`string` 필수 항목입니다. 필드 이름입니다. 이름에는 문자 (a~z, A~Z), 숫자 (0~9), 밑줄 (_)만 포함해야 하며 문자 또는 밑줄로 시작해야 합니다. 최대 길이는 300자(영문 기준)입니다.
`type`	`string` 필수 항목입니다. 필드 데이터 유형입니다. 가능한 값은 다음과 같습니다. 문자열 BYTES 정수 (또는 INT64) FLOAT (또는 FLOAT64) BOOLEAN (또는 BOOL) TIMESTAMP DATE 시간 DATETIME GEOGRAPHY 숫자 형식 BIGNUMERIC JSON RECORD (또는 STRUCT) RANGE RECORD/STRUCT 사용은 필드에 중첩된 스키마가 포함되어 있음을 나타냅니다.
`mode`	`string` 선택사항입니다. 필드 모드입니다. 가능한 값은 NULLABLE, REQUIRED, REPEATED입니다. 기본값은 NULLABLE입니다.
`fields[]`	`object (TableFieldSchema)` 선택사항입니다. type 속성이 RECORD로 설정된 경우 중첩된 스키마 필드를 설명합니다.
`description`	`string` 선택사항입니다. 필드 설명입니다. 최대 길이는 1,024자(영문 기준)입니다.
`policyTags`	`object (PolicyTagList)` 선택사항입니다. 필드 수준 액세스 제어에 사용되는 이 필드에 연결된 정책 태그입니다. 설정하지 않으면 기본값은 빈 policy_tags입니다.
`dataPolicies[]`	`object (DataPolicyOption)` 선택사항입니다. 필드 수준 액세스 제어에 사용되며 이 필드에 연결된 데이터 정책입니다.
`maxLength`	`string (int64 format)` 선택사항입니다. 문자열 또는 바이트의 이 필드 값의 최대 길이입니다. max_length가 지정되지 않으면 이 필드에 최대 길이 제약 조건이 적용되지 않습니다. type = 'STRING'인 경우 max_length는 이 필드의 문자열의 최대 UTF-8 길이를 나타냅니다. type = 'BYTES'인 경우 max_length는 이 필드의 최대 바이트 수를 나타냅니다. 유형이 'STRING' 및 'BYTES'가 아닌 경우 이 필드를 설정하면 유효하지 않습니다.
`precision`	`string (int64 format)` 선택사항입니다. NUMERIC 또는 BIGNUMERIC의 경우 이 필드 값의 정밀도 (10진수의 총 자릿수 최대 개수) 및 스케일 (10진수의 소수 부분 자릿수 최대 개수) 제약 조건입니다. 유형이 'NUMERIC'도 'BIGNUMERIC'도 아닌 경우 정밀도 또는 비율을 설정하는 것은 유효하지 않습니다. 정밀도와 스케일이 지정되지 않은 경우 유형에서 허용하는 한 값 범위 제약 조건이 이 필드에 적용되지 않습니다. 다음의 경우 이 NUMERIC 또는 BIGNUMERIC 필드의 값은 이 범위에 있어야 합니다. 정밀도 (`P`)와 소수 자릿수 (`S`)가 지정됩니다. [-10^P-S + 10^-S, 10^P-S - 10^-S] 정밀도(`P`)는 지정되었지만 스케일은 지정되지 않았으므로 스케일이 0으로 해석됩니다. [-10^P + 1, 10^P - 1] 정밀도와 배율이 모두 지정된 경우 허용되는 값은 다음과 같습니다. type = 'NUMERIC'인 경우: 1 ≤ 정밀도 - 비율 ≤ 29 및 0 ≤ 비율 ≤ 9 type = 'BIGNUMERIC'인 경우: 1 ≤ precision - scale ≤ 38 및 0 ≤ scale ≤ 38 정밀도만 지정되고 배율이 지정되지 않은 경우 (따라서 배율이 0으로 해석됨) 정밀도에 허용되는 값: type = 'NUMERIC'인 경우: 1 ≤ precision ≤ 29 type = 'BIGNUMERIC'인 경우: 1 ≤ precision ≤ 38 규모는 지정되었지만 정밀도가 지정되지 않은 경우 유효하지 않습니다.
`scale`	`string (int64 format)` 선택사항입니다. 정확도는 문서를 참고하세요.
`timestampPrecision`	`string (Int64Value format)` 선택사항입니다. TIMESTAMP 유형의 초에 대한 정밀도 (10진수의 총 자릿수 최대값)입니다. 가능한 값은 다음과 같습니다. * 6 (기본값, 마이크로초 정밀도의 TIMESTAMP 유형) * 12 (피코초 정밀도의 TIMESTAMP 유형)
`roundingMode`	`enum (RoundingMode)` 선택사항입니다. NUMERIC 및 BIGNUMERIC 유형의 값을 저장할 때 사용할 반올림 모드를 지정합니다.
`collation`	`string` 선택사항입니다. 필드 콜레이션은 필드 유형이 문자열인 경우에만 설정할 수 있습니다. 다음과 같은 값이 지원됩니다. 'und:ci': 미확인 언어, 대소문자 구분 안 함 '': 빈 문자열 대소문자 구분 동작으로 기본 설정
`defaultValueExpression`	`string` 선택사항입니다. 이 필드의 기본값을 지정하는 SQL 표현식입니다.
`rangeElementType`	`object (FieldElementType)` 선택사항입니다. 이 필드의 유형이 RANGE인 경우 RANGE의 하위 유형입니다. 유형이 RANGE인 경우 이 필드는 필수입니다. 필드 요소 유형의 값은 다음 중 하나일 수 있습니다. DATE DATETIME TIMESTAMP
`foreignTypeDefinition`	`string` 선택사항입니다. 외부 데이터 유형의 정의입니다. 최상위 스키마 필드 (중첩 필드 아님)에만 유효합니다. 유형이 FOREIGN인 경우 이 필드는 필수입니다.
`generatedColumn`	`object (GeneratedColumn)` 선택사항입니다. 필드의 값이 생성되는 방식에 관한 정의입니다. 최상위 스키마 필드 (중첩 필드 아님)에만 유효합니다.

StringValue

JSON 표현
{ "value": string }

필드

필드
`value`	`string` 문자열 값입니다.

value

string

문자열 값입니다.

PolicyTagList

JSON 표현
{ "names": [ string ] }

필드

필드
`names[]`	`string` 정책 태그 리소스 이름 목록입니다. 예를 들어 'projects/1/locations/eu/taxonomies/2/policyTags/3'입니다. 현재 정책 태그는 최대 1개까지 허용됩니다.

names[]

string

정책 태그 리소스 이름 목록입니다. 예를 들어 'projects/1/locations/eu/taxonomies/2/policyTags/3'입니다. 현재 정책 태그는 최대 1개까지 허용됩니다.

DataPolicyOption

JSON 표현
{ // Union field `_name` can be only one of the following: "name": string // End of list of possible types for union field `_name`. }

필드

필드
통합 필드 `_name`. `_name`는 다음 중 하나여야 합니다.
`name`	`string` 데이터 정책 리소스 이름입니다(형식: projects/project_id/locations/location_id/dataPolicies/data_policy_id).

통합 필드 _name.

_name는 다음 중 하나여야 합니다.

name

string

데이터 정책 리소스 이름입니다(형식: projects/project_id/locations/location_id/dataPolicies/data_policy_id).

Int64Value

JSON 표현
{ "value": string }

필드

필드
`value`	`string (int64 format)` int64 값입니다.

value

string (int64 format)

int64 값입니다.

FieldElementType

JSON 표현
{ "type": string }

필드

필드
`type`	`string` 필수 항목입니다. 필드 요소의 유형입니다. 자세한 내용은 `TableFieldSchema.type`을 참조하세요.

type

string

필수 항목입니다. 필드 요소의 유형입니다. 자세한 내용은 TableFieldSchema.type을 참조하세요.

GeneratedColumn

JSON 표현

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

{

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

필드

필드
통합 필드 `_generated_mode`. `_generated_mode`는 다음 중 하나여야 합니다.
`generatedMode`	`enum (GeneratedMode)` 선택사항입니다. 시스템 생성 값이 필드를 채우는 시기를 지정합니다.
통합 필드 `definition`. `definition`는 다음 중 하나여야 합니다.
`generatedExpressionInfo`	`object (GeneratedExpressionInfo)` 필드를 생성하는 데 사용되는 표현식의 정의입니다.

통합 필드 _generated_mode.

_generated_mode는 다음 중 하나여야 합니다.

generatedMode

enum (GeneratedMode)

선택사항입니다. 시스템 생성 값이 필드를 채우는 시기를 지정합니다.

통합 필드 definition.

definition는 다음 중 하나여야 합니다.

generatedExpressionInfo

object (GeneratedExpressionInfo)

필드를 생성하는 데 사용되는 표현식의 정의입니다.

GeneratedExpressionInfo

JSON 표현

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

{

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

필드

필드
통합 필드 `_generation_expression`. `_generation_expression`는 다음 중 하나여야 합니다.
`generationExpression`	`string` 선택사항입니다. 필드를 생성하는 데 사용된 생성 표현식 (예: AI.EMBED(...))입니다.
통합 필드 `_asynchronous`. `_asynchronous`는 다음 중 하나여야 합니다.
`asynchronous`	`boolean` 선택사항입니다. 열 생성이 비동기적으로 실행되는지 여부입니다.
통합 필드 `_stored`. `_stored`는 다음 중 하나여야 합니다.
`stored`	`boolean` 선택사항입니다. 생성된 열이 테이블에 저장되는지 여부입니다.

통합 필드 _generation_expression.

_generation_expression는 다음 중 하나여야 합니다.

generationExpression

string

선택사항입니다. 필드를 생성하는 데 사용된 생성 표현식 (예: AI.EMBED(...))입니다.

통합 필드 _asynchronous.

_asynchronous는 다음 중 하나여야 합니다.

asynchronous

boolean

선택사항입니다. 열 생성이 비동기적으로 실행되는지 여부입니다.

통합 필드 _stored.

_stored는 다음 중 하나여야 합니다.

stored

boolean

선택사항입니다. 생성된 열이 테이블에 저장되는지 여부입니다.

ForeignTypeInfo

JSON 표현
{ "typeSystem": enum (`TypeSystem`) }

필드

필드
`typeSystem`	`enum (TypeSystem)` 필수 항목입니다. 외부 데이터 유형을 정의하는 시스템을 지정합니다.

typeSystem

enum (TypeSystem)

필수 항목입니다. 외부 데이터 유형을 정의하는 시스템을 지정합니다.

구조체

JSON 표현
{ "fields": { string: value, ... } }

필드

필드
`fields`	`map (key: string, value: value (Value format))` 동적으로 입력된 값의 순서가 지정되지 않은 맵입니다. `"key": value` 쌍 목록을 포함하는 객체입니다. 예: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`

fields

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

동적으로 입력된 값의 순서가 지정되지 않은 맵입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }

FieldsEntry

JSON 표현
{ "key": string, "value": value }

필드
`key`	`string`
`value`	`value (Value format)`

값

JSON 표현

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

{

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

필드
통합 필드 `kind`. 값의 종류입니다. `kind`은 다음 중 하나여야 합니다.
`nullValue`	`null` JSON `null`를 나타냅니다.
`numberValue`	`number` JSON 숫자를 나타냅니다. JSON에서는 `NaN`, `Infinity`, `-Infinity`가 지원되지 않으므로 이러한 값은 사용할 수 없습니다. 또한 JSON 형식은 일반적으로 숫자 유형에서 큰 Int64 값을 지원하지 않으므로 이를 표현할 수 없습니다.
`stringValue`	`string` JSON 문자열을 나타냅니다.
`boolValue`	`boolean` JSON 불리언 (JSON의 `true` 또는 `false` 리터럴)을 나타냅니다.
`structValue`	`object (Struct format)` JSON 객체를 나타냅니다.
`listValue`	`array (ListValue format)` JSON 배열을 나타냅니다.

ListValue

JSON 표현
{ "values": [ value ] }

필드

필드
`values[]`	`value (Value format)` 동적으로 입력된 값의 반복 필드입니다.

values[]

value (Value format)

동적으로 입력된 값의 반복 필드입니다.

BoolValue

JSON 표현
{ "value": boolean }

필드

필드
`value`	`boolean` 불리언 값입니다.

value

boolean

불리언 값입니다.

ErrorProto

JSON 표현
{ "reason": string, "location": string, "debugInfo": string, "message": string }

필드
`reason`	`string` 오류를 요약하는 짧은 오류 코드입니다.
`location`	`string` 오류가 발생한 위치를 지정합니다(있는 경우).
`debugInfo`	`string` 디버깅 정보입니다. 이 속성은 Google 내부용이므로 사용하면 안 됩니다.
`message`	`string` 사람이 읽을 수 있는 오류 설명입니다.

도구 주석

파괴적 힌트: ✅ | 동일한 힌트: ❌ | 읽기 전용 힌트: ❌ | 오픈 월드 힌트: ✅

MCP Tools Reference: bigquery.googleapis.com 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

도구: execute_sql

입력 스키마

QueryRequest

출력 스키마

QueryResponse

TableSchema

TableFieldSchema

StringValue

PolicyTagList

DataPolicyOption

Int64Value

FieldElementType

GeneratedColumn

GeneratedExpressionInfo

ForeignTypeInfo

구조체

FieldsEntry

값

ListValue

BoolValue

ErrorProto

도구 주석

MCP Tools Reference: bigquery.googleapis.com

도구: `execute_sql`