MCP Tools Reference: bigquery.googleapis.com

כלי: execute_sql

מריצים שאילתת SQL בפרויקט ומחזירים את התוצאה.

הכלי הזה מוגבל ל-SELECT דוחות בלבד. אסור להשתמש בהצהרות INSERT,‏ UPDATE ו-DELETE ובפרוצדורות מאוחסנות. אם השאילתה לא כוללת הצהרת SELECT, מוחזרת שגיאה. מידע על יצירת שאילתות מופיע במאמרי העזרה בנושא GoogleSQL.

לכלי execute_sql יכולות להיות גם תופעות לוואי אם השאילתה מפעילה פונקציות מרחוק או פונקציות מוגדרות על ידי המשתמש (UDF) ב-Python.

לכל השאילתות שמופעלות באמצעות הכלי execute_sql יש תווית שמזהה את הכלי כמקור. אפשר להשתמש בתווית הזו כדי לסנן את השאילתות באמצעות זוג התווית והערך goog-mcp-server: true.

החיוב על השאילתות מתבצע בפרויקט שצוין בשדה project_id.

בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להפעיל את כלי ה-MCP‏ execute_sql.

בקשת 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
}'

סכימת הקלט

מריץ שאילתת SQL ב-BigQuery באופן סינכרוני ומחזיר את תוצאות השאילתה אם השאילתה מסתיימת לפני תפוגת הזמן שצוין.

QueryRequest

ייצוג ב-JSON 
{
  "projectId": string,
  "query": string,
  "dryRun": boolean
}
שדות
projectId

string

חובה. פרויקט שישמש להרצת שאילתות ולחיוב.
query

string

חובה. השאילתה להרצה, בצורה של שאילתת GoogleSQL.
dryRun

boolean

זה שינוי אופציונלי. אם המאפיין מוגדר כ-true, המשימה לא מורצת ב-BigQuery. במקום זאת, אם השאילתה תקינה, BigQuery מחזיר נתונים סטטיסטיים על העבודה, כמו מספר הבייטים שיעברו עיבוד. אם השאילתה לא תקינה, ה-API מחזיר שגיאה. ערך ברירת המחדל הוא false.

סכימת פלט

תגובה לשאילתת SQL ב-BigQuery.

QueryResponse

ייצוג ב-JSON 
{
  "schema": {
    object (TableSchema)
  },
  "rows": [
    {
      object
    }
  ],
  "jobComplete": boolean,
  "errors": [
    {
      object (ErrorProto)
    }
  ]
}
שדות
schema

object (TableSchema)

הסכימה של התוצאות. התג הזה מוצג רק אם השאילתה הושלמה בהצלחה.
rows[]

object (Struct format)

אובייקט עם מספר התוצאות המקסימלי שאפשר לכלול בגודל התשובה המקסימלי המותר. כדי לקבל שורות נוספות, אפשר לקרוא ל-GetQueryResults ולציין את jobReference שהוחזר למעלה.
jobComplete

boolean

האם השאילתה הסתיימה או לא. אם יש שורות או totalRows, הערך הזה תמיד יהיה true. אם הערך הוא False, המאפיין totalRows לא יהיה זמין.
errors[]

object (ErrorProto)

פלט בלבד. השגיאות או האזהרות הראשונות שנתקלו בהן במהלך הפעלת העבודה. ההודעה הסופית כוללת את מספר השגיאות שגרמו להפסקת התהליך. שגיאות שמופיעות כאן לא בהכרח אומרות שהעבודה הסתיימה או שהיא נכשלה. מידע נוסף על הודעות שגיאה זמין במאמר הודעות שגיאה.

TableSchema

ייצוג ב-JSON 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
שדות
fields[]

object (TableFieldSchema)

תיאור השדות בטבלה.
foreignTypeInfo

object (ForeignTypeInfo)

זה שינוי אופציונלי. מציין מטא-נתונים של הגדרת סוג הנתונים החיצוני בסכימת השדה (TableFieldSchema.foreign_type_definition).

TableFieldSchema

ייצוג ב-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
}
שדות
name

string

חובה. שם השדה. השם חייב להכיל רק אותיות (a-z,‏ A-Z), מספרים (0-9) או קווים תחתונים (_), והוא חייב להתחיל באות או בקו תחתון. האורך המקסימלי הוא 300 תווים.
type

string

חובה. סוג הנתונים של השדה. הערכים האפשריים כוללים:

  • מחרוזת
  • BYTES
  • מספר שלם (או INT64)
  • מספר ממשי (FLOAT) (או FLOAT64)
  • בוליאני (או BOOL)
  • TIMESTAMP
  • תאריך
  • שעות
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • רשומה (או STRUCT)
  • RANGE

השימוש ב-RECORD/STRUCT מציין שהשדה מכיל סכימה מקוננת.
mode

string

זה שינוי אופציונלי. השדה mode. הערכים האפשריים הם NULLABLE, ‏ REQUIRED ו-REPEATED. ערך ברירת המחדל הוא NULLABLE.
fields[]

object (TableFieldSchema)

זה שינוי אופציונלי. מתאר את השדות של הסכימה המקוננת אם מאפיין הסוג מוגדר כ-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 מייצג את מספר הבייטים המקסימלי בשדה הזה.

אסור להגדיר את השדה הזה אם הערך של type הוא לא STRING ולא BYTES.
precision

string (int64 format)

זה שינוי אופציונלי. אילוצים של דיוק (מספר הספרות המקסימלי הכולל בבסיס 10) וקנה מידה (מספר הספרות המקסימלי בחלק השברי בבסיס 10) לערכים של השדה הזה עבור NUMERIC או BIGNUMERIC.

אי אפשר להגדיר דיוק או קנה מידה אם type ≠ "NUMERIC" ו-≠ "BIGNUMERIC".

אם לא מציינים את הדיוק והקנה מידה, לא מוטל על השדה הזה אילוץ של טווח ערכים, כל עוד הערכים מותרים לפי הסוג.

הערכים בשדה NUMERIC או BIGNUMERIC חייבים להיות בטווח הזה כאשר:

  • הדיוק (P) והקנה מידה (S) מוגדרים: [-10P-S + 10-S, 10P-S - 10-S]
  • הארגומנט precision (P) צוין אבל לא הארגומנט scale (ולכן הארגומנט scale מפורש כשווי ערך לאפס): [‎-10P + 1, 10P - 1].

ערכים קבילים לדיוק ולסולם אם שניהם מצוינים:

  • אם type = "NUMERIC": 1 ≤ precision - scale ≤ 29 and 0 ≤ scale ≤ 9.
  • אם type = "BIGNUMERIC": ‏ 1 ≤ precision - scale ≤ 38 ו-0 ≤ scale ≤ 38.

ערכים קבילים לדיוק אם מציינים רק דיוק ולא קנה מידה (ולכן קנה המידה מפורש כשווי ערך לאפס):

  • אם type = "NUMERIC": ‏ 1 ≤ precision ≤ 29.
  • אם type = "BIGNUMERIC": ‏ 1 ≤ precision ≤ 38.

אם מציינים את קנה המידה אבל לא את הדיוק, הערך לא תקין.
scale

string (int64 format)

זה שינוי אופציונלי. לקבלת פרטים, אפשר לעיין במסמכי התיעוד.
timestampPrecision

string (Int64Value format)

זה שינוי אופציונלי. הדיוק (מספר הספרות הכולל המקסימלי בבסיס 10) של שניות מסוג TIMESTAMP.

הערכים האפשריים כוללים: * 6 (ברירת מחדל, לסוג TIMESTAMP עם דיוק של מיקרו-שנייה) * 12 (לסוג TIMESTAMP עם דיוק של פיקו-שנייה)
roundingMode

enum (RoundingMode)

זה שינוי אופציונלי. מציין את אופן העיגול שיש להשתמש בו כשמאחסנים ערכים מסוג NUMERIC ו-BIGNUMERIC.
collation

string

זה שינוי אופציונלי. אפשר להגדיר איסוף שדות רק אם סוג השדה הוא STRING. יש תמיכה בערכים הבאים:

  • ‫‎'und:ci': לוקאל לא מוגדר, לא תלוי רישיות.
  • ‫'': מחרוזת ריקה. ברירת המחדל היא התנהגות תלוית אותיות רישיות.
defaultValueExpression

string

זה שינוי אופציונלי. ביטוי SQL שמציין את ערך ברירת המחדל של השדה הזה.
rangeElementType

object (FieldElementType)

זה שינוי אופציונלי. סוג המשנה של הטווח, אם הסוג של השדה הזה הוא RANGE. אם הסוג הוא RANGE, חובה למלא את השדה הזה. הערכים של סוג רכיב השדה יכולים להיות:

  • תאריך
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

זה שינוי אופציונלי. ההגדרה של סוג הנתונים החיצוני. ההגדרה הזו תקפה רק לשדות סכימה ברמה העליונה (לא לשדות מוטמעים). אם הסוג הוא FOREIGN (זר), חובה למלא את השדה הזה.

StringValue

ייצוג ב-JSON 
{
  "value": string
}
שדות
value

string

ערך המחרוזת.

PolicyTagList

ייצוג ב-JSON 
{
  "names": [
    string
  ]
}
שדות
names[]

string

רשימה של שמות משאבים של תגי מדיניות. לדוגמה, "projects/1/locations/eu/taxonomies/2/policyTags/3". נכון לעכשיו, מותר להשתמש בתג מדיניות אחד לכל היותר.

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.

Int64Value

ייצוג ב-JSON 
{
  "value": string
}
שדות
value

string (int64 format)

הערך int64.

FieldElementType

ייצוג ב-JSON 
{
  "type": string
}
שדות
type

string

חובה. הסוג של רכיב שדה. מידע נוסף זמין במאמר TableFieldSchema.type.

ForeignTypeInfo

ייצוג ב-JSON 
{
  "typeSystem": enum (TypeSystem)
}
שדות
typeSystem

enum (TypeSystem)

חובה. מציין את המערכת שמגדירה את סוג הנתונים החיצוני.

Struct

ייצוג ב-JSON 
{
  "fields": {
    string: value,
    ...
  }
}
שדות
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 
{

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

מייצג ערך כפול.
stringValue

string

מייצג ערך מחרוזת.
boolValue

boolean

מייצג ערך בוליאני.
structValue

object (Struct format)

מייצג ערך מובנה.
listValue

array (ListValue format)

מייצג Value שחוזר על עצמו.

ListValue

ייצוג ב-JSON 
{
  "values": [
    value
  ]
}
שדות
values[]

value (Value format)

שדה חוזר של ערכים עם הקלדה דינמית.

BoolValue

ייצוג ב-JSON 
{
  "value": boolean
}
שדות
value

boolean

הערך הבוליאני.

ErrorProto

ייצוג ב-JSON 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
שדות
reason

string

קוד שגיאה קצר שמסכם את השגיאה.
location

string

מציין איפה השגיאה התרחשה, אם יש כזו.
debugInfo

string

מידע על תוצאות ניפוי הבאגים. המאפיין הזה הוא פנימי ל-Google ואין להשתמש בו.
message

string

תיאור השגיאה שכתוב בצורה שקריאה לאנשים.

הערות על כלי

רמז הרסני: ✅ | רמז אידמפוטנטי: ❌ | רמז לקריאה בלבד: ❌ | רמז לעולם פתוח: ✅