MCP Tools Reference: bigquery.googleapis.com

도구: execute_sql

프로젝트에서 SQL 쿼리를 실행하고 결과를 반환합니다.

이 도구는 SELECT 문으로만 제한됩니다. INSERT, UPDATE, DELETE 문과 저장 프로시저는 허용되지 않습니다. 쿼리에 SELECT 문이 포함되지 않으면 오류가 반환됩니다. 쿼리 만들기에 대한 자세한 내용은 GoogleSQL 문서를 참고하세요.

쿼리에서 원격 함수 또는 Python UDF를 호출하는 경우 execute_sql 도구에 부작용이 있을 수도 있습니다.

execute_sql 도구를 사용하여 실행되는 모든 쿼리에는 도구를 소스로 식별하는 라벨이 있습니다. 이 라벨을 사용하여 라벨 및 값 쌍 goog-mcp-server: true를 사용하여 쿼리를 필터링할 수 있습니다.

쿼리 요금은 project_id 필드에 지정된 프로젝트에 청구됩니다.

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

컬 요청 
                  
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 쿼리를 동기식으로 실행하고, 쿼리가 지정된 제한 시간 이내에 완료될 경우 쿼리 결과를 반환합니다.

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

string

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

string

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

boolean

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

출력 스키마

BigQuery SQL 쿼리의 응답입니다.

JSON 표현 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ]
}
필드
schema

object (TableSchema)

결과의 스키마입니다. 쿼리가 성공적으로 완료된 경우에만 표시됩니다.
rows[]

object (Struct format)

허용되는 최대 답장 크기 내에 포함될 수 있는 만큼의 결과가 있는 객체입니다. 추가 행을 가져오려면 GetQueryResults를 호출하고 위에서 반환된 jobReference를 지정하면 됩니다.
jobComplete

boolean

쿼리가 완료되었는지 여부입니다. rows 또는 totalRows가 있으면 항상 true입니다. 이 값이 false이면 totalRows를 사용할 수 없습니다.
errors[]

object (ErrorProto)

출력 전용입니다. 작업 실행 중에 발생한 첫 번째 오류 또는 경고입니다. 최종 메시지에는 프로세스가 중지된 원인이 된 오류 수가 포함됩니다. 여기에 오류가 표시된다고 해서 작업이 완료되었거나 실패했음을 의미하지는 않습니다. 오류 메시지에 관한 자세한 내용은 오류 메시지를 참고하세요.
JSON 표현 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
필드
fields[]

object (TableFieldSchema)

표의 필드를 설명합니다.
foreignTypeInfo

object (ForeignTypeInfo)

선택사항입니다. 필드 스키마 (TableFieldSchema.foreign_type_definition)에서 외부 데이터 유형 정의의 메타데이터를 지정합니다.
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
}
필드
name

string

필수 항목입니다. 필드 이름입니다. 이름에는 문자 (a~z, A~Z), 숫자 (0~9), 밑줄 (_)만 포함해야 하며 문자 또는 밑줄로 시작해야 합니다. 최대 길이는 300자(영문 기준)입니다.
type

string

필수 항목입니다. 필드 데이터 유형입니다. 가능한 값은 다음과 같습니다.

  • 문자열
  • BYTES
  • INTEGER (또는 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)

선택사항입니다. 필드 수준 액세스 제어에 사용되며 이 필드에 연결된 데이터 정책입니다.
nameAlternative[]

string

이 필드는 사용하면 안 됩니다.
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)가 지정됩니다. [-10P-S + 10-S, 10P-S - 10-S]
  • 정밀도(P)는 지정되었지만 스케일은 지정되지 않았으므로 스케일이 0으로 해석됩니다. [-10P + 1, 10P - 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인 경우 이 필드는 필수입니다.
JSON 표현 
{
  "value": string
}
필드
value

string

문자열 값입니다.
JSON 표현 
{
  "names": [
    string
  ]
}
필드
names[]

string

정책 태그 리소스 이름 목록입니다. 예를 들어 'projects/1/locations/eu/taxonomies/2/policyTags/3'입니다. 현재 최대 1개의 정책 태그가 허용됩니다.
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).
JSON 표현 
{
  "value": string
}
필드
value

string (int64 format)

int64 값입니다.
JSON 표현 
{
  "type": string
}
필드
type

string

필수 항목입니다. 필드 요소의 유형입니다. 자세한 내용은 TableFieldSchema.type을 참조하세요.
JSON 표현 
{
  "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" }
JSON 표현 
{
  "key": string,
  "value": value
}
필드
key

string
value

value (Value format)
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.
}
필드
통합 필드 kind. 값의 종류입니다. kind은 다음 중 하나여야 합니다.
nullValue

null

null 값을 나타냅니다.
numberValue

number

double 값을 나타냅니다.
stringValue

string

문자열 값을 나타냅니다.
boolValue

boolean

불리언 값을 나타냅니다.
structValue

object (Struct format)

구조화된 값을 나타냅니다.
listValue

array (ListValue format)

반복되는 Value을 나타냅니다.
JSON 표현 
{
  "values": [
    value
  ]
}
필드
values[]

value (Value format)

동적으로 입력된 값의 반복 필드입니다.
JSON 표현 
{
  "value": boolean
}
필드
value

boolean

불리언 값입니다.
JSON 표현 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
필드
reason

string

오류를 요약하는 짧은 오류 코드입니다.
location

string

오류가 발생한 위치를 지정합니다(있는 경우).
debugInfo

string

디버깅 정보입니다. 이 속성은 Google 내부용이므로 사용하면 안 됩니다.
message

string

사람이 읽을 수 있는 오류 설명입니다.

도구 주석

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