MCP Tools Reference: bigquery.googleapis.com

工具：get_dataset_info

取得 BigQuery 資料集的中繼資料資訊。

下列範例示範如何使用 curl 叫用 get_dataset_info 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": "get_dataset_info",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入結構定義

要求資料集。

JSON 表示法 
{
  "projectId": string,
  "datasetId": string
}
欄位
projectId

string

這是必要旗標，資料集要求的專案 ID。
datasetId

string

這是必要旗標，資料集要求的資料集 ID。

輸出內容的結構定義

代表 BigQuery 資料集。

JSON 表示法 
{
  "kind": string,
  "etag": string,
  "id": string,
  "selfLink": string,
  "datasetReference": {
    object (DatasetReference)
  },
  "friendlyName": string,
  "description": string,
  "defaultTableExpirationMs": string,
  "defaultPartitionExpirationMs": string,
  "labels": {
    string: string,
    ...
  },
  "access": [
    {
      object (Access)
    }
  ],
  "creationTime": string,
  "lastModifiedTime": string,
  "location": string,
  "defaultEncryptionConfiguration": {
    object (EncryptionConfiguration)
  },
  "satisfiesPzs": boolean,
  "satisfiesPzi": boolean,
  "type": string,
  "linkedDatasetSource": {
    object (LinkedDatasetSource)
  },
  "linkedDatasetMetadata": {
    object (LinkedDatasetMetadata)
  },
  "externalDatasetReference": {
    object (ExternalDatasetReference)
  },
  "externalCatalogDatasetOptions": {
    object (ExternalCatalogDatasetOptions)
  },
  "isCaseInsensitive": boolean,
  "defaultCollation": string,
  "defaultRoundingMode": enum (RoundingMode),
  "maxTimeTravelHours": string,
  "tags": [
    {
      object (GcpTag)
    }
  ],
  "storageBillingModel": enum (StorageBillingModel),
  "restrictions": {
    object (RestrictionConfig)
  },
  "resourceTags": {
    string: string,
    ...
  }
}
欄位
kind

string

僅供輸出。資源類型。
etag

string

僅供輸出。資源的雜湊值。
id

string

僅供輸出。資料集的完整專屬名稱，格式為「projectId:datasetId」。不含專案名稱的資料集名稱會在 datasetId 資料欄內提供。建立新資料集時，請將此資料欄留空，並改為指定 datasetId 資料欄。
selfLink

string

僅供輸出。可用於再次存取資源的網址。您可以在 Get 或 Update 要求中使用這個資源的網址。
datasetReference

object (DatasetReference)

這是必要旗標，可識別資料集的參照。
friendlyName

string

(選用步驟) 資料集的描述性名稱。
description

string

(選用步驟) 資料集的說明，方便使用者瞭解。
defaultTableExpirationMs

string (Int64Value format)

(選用步驟) 資料集中所有資料表的預設生命週期 (以毫秒為單位)。生命週期值下限為 3600000 毫秒 (一小時)。如要透過 PATCH 要求清除現有的預設到期時間，請將值設為 0。設定這項屬性後，資料集中所有新建立的資料表都會將 expirationTime 屬性設為建立時間加上這項屬性的值，且變更值只會影響新資料表，不會影響現有資料表。如果資料表達到 expirationTime，系統會自動刪除該資料表。如果在資料表到期前修改或移除 expirationTime，或是在建立資料表時提供明確的 expirationTime，則該值會優先於這個屬性所指出的預設到期時間。
defaultPartitionExpirationMs

string (Int64Value format)

預設分區到期時間 (以毫秒為單位)。

在已設定這項屬性的資料集中建立新的時間分區資料表時，資料表會沿用這個值，並做為新資料表的 TimePartitioning.expirationMs 屬性。如果您在建立資料表時明確設定 TimePartitioning.expirationMs，系統會忽略所含資料集的 defaultPartitionExpirationMs。

建立分區資料表時，如果設定 defaultPartitionExpirationMs，系統會忽略 defaultTableExpirationMs 值，且資料表不會沿用資料表到期期限。
labels

map (key: string, value: string)

與這個資料集相關聯的標籤。您可以使用這些標籤來整理及分組資料集。插入或更新資料集時，可以設定這項屬性。詳情請參閱「建立及更新資料集標籤」。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
access[]

object (Access)

(選用步驟) 物件陣列，定義一或多個實體的資料集存取權。插入或更新資料集時，您可以設定這項屬性，控管哪些使用者可以存取資料。如果未在建立資料集時指定，BigQuery 會為下列實體新增預設資料集存取權：access.specialGroup: projectReaders; access.role: READER; access.specialGroup: projectWriters; access.role: WRITER; access.specialGroup: projectOwners; access.role: OWNER; access.userByEmail: [資料集建立者電子郵件地址]; access.role: OWNER; 如果您修補資料集，這個欄位會遭到修補資料集的存取權欄位覆寫。如要新增實體，除了要新增的實體外，您也必須提供整個現有存取權陣列。
creationTime

string (int64 format)

僅供輸出。這個資料集的建立時間，以從 Epoch 紀元時間算起的毫秒數表示。
lastModifiedTime

string (int64 format)

僅供輸出。這個資料集上次修改的日期，以自記錄週期後的毫秒數表示。
location

string

資料集應位於的地理位置。如要瞭解支援的地區，請參閱 https://cloud.google.com/bigquery/docs/locations。
defaultEncryptionConfiguration

object (EncryptionConfiguration)

資料集中所有資料表的預設加密金鑰。設定這項屬性後，資料集中所有新建立的資料表都會使用這個值做為加密金鑰，除非資料表建立要求或查詢明確覆寫金鑰。
satisfiesPzs

boolean

僅供輸出。保留欄位，供日後使用。
satisfiesPzi

boolean

僅供輸出。保留欄位，供日後使用。
type

string

僅供輸出。與 type 中的 ListFormatDataset 相同。資料集類型，可以是下列其中一種：

  • 預設 - 只有擁有者和授權帳戶可以存取，
  • 公開 - 所有人都能存取
  • 已連結 - 連結的資料集，
  • EXTERNAL - 資料集，定義位於外部中繼資料目錄中。
linkedDatasetSource

object (LinkedDatasetSource)

(選用步驟) 如果資料集類型為 LINKED，則為來源資料集參照。其他資料集類型則不會設定。設定後即無法更新這個欄位。如果嘗試使用 Update 和 Patch API 作業更新這個欄位，系統會忽略相關要求。
linkedDatasetMetadata

object (LinkedDatasetMetadata)

僅供輸出。LinkedDataset 的相關中繼資料。資料集類型為 LINKED 時填寫。
externalDatasetReference

object (ExternalDatasetReference)

(選用步驟) 參照 BigQuery 以外資料目錄中定義的唯讀外部資料集。資料集類型為 EXTERNAL 時填寫。
externalCatalogDatasetOptions

object (ExternalCatalogDatasetOptions)

(選用步驟) 定義 BigQuery 目錄中與開放原始碼相容的資料集。包含目前資料集代表的開放原始碼資料庫、結構定義或命名空間的中繼資料。
isCaseInsensitive

boolean

(選用步驟) 如果資料集及其資料表名稱不區分大小寫，則為 TRUE，否則為 FALSE。根據預設，這個值為 FALSE，表示資料集和資料表名稱會區分大小寫。這個欄位不會影響常式參照。
defaultCollation

string

(選用步驟) 定義資料集中未來建立資料表的預設定序規格。如果在這個資料集中建立資料表時未指定資料表層級的預設定序，則資料表會繼承資料集的預設定序，並套用至未明確指定定序的字串欄位。變更這個欄位只會影響之後建立的資料表，不會變更現有資料表。支援的值如下：

  • 「und:ci」：不確定的語言代碼，不區分大小寫。
  • ''：空字串。預設為會區分大小寫。
defaultRoundingMode

enum (RoundingMode)

(選用步驟) 定義這個資料集內建立的新資料表預設捨入模式規格。建立資料表時，如果指定這個欄位，資料集中的資料表就會沿用資料集的預設捨入模式。在表格中設定預設捨入模式會覆寫這個選項。資料集中的現有表格不會受到影響。如果在建立資料表時定義資料欄，除非另有指定，否則資料欄會立即沿用資料表的預設捨入模式。
maxTimeTravelHours

string (Int64Value format)

(選用步驟) 以小時為單位定義時間回溯期。這個值可以介於 48 至 168 小時 (2 至 7 天)。如未設定，預設值為 168 小時。
tags[]
(deprecated)

object (GcpTag)

僅供輸出。資料集的標記。如要提供標記做為輸入內容，請使用 resourceTags 欄位。
storageBillingModel

enum (StorageBillingModel)

(選用步驟) 更新資料集的 storage_billing_model。
restrictions

object (RestrictionConfig)

(選用步驟) 僅供輸出。所有資料表和資料集的限制設定。如果設定了這項屬性，系統會根據設定限制資料集和所有資料表的特定存取權。詳情請參閱「資料輸出」。
resourceTags

map (key: string, value: string)

(選用步驟) 附加至這個資料集的標記。標記鍵在全域範圍內不得重複。標記鍵應採用命名空間格式，例如「123456789012/environment」，其中 123456789012 是這個標記鍵的父項機構或專案資源 ID。標記值應為簡短名稱，例如「Production」。詳情請參閱「標記定義」。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
JSON 表示法 
{
  "datasetId": string,
  "projectId": string,
  "datasetIdAlternative": [
    string
  ],
  "projectIdAlternative": [
    string
  ]
}
欄位
datasetId

string

這是必要旗標，此資料集不含專案名稱的唯一 ID。ID 只能包含英文字母 (a-z、A-Z)、數字 (0-9) 或底線 (_)，長度上限為 1,024 個半形字元。
projectId

string

(選用步驟) 這個資料集所屬專案的 ID。
datasetIdAlternative[]

string

請勿使用這個欄位。
projectIdAlternative[]

string

請勿使用這個欄位。
JSON 表示法 
{
  "value": string
}
欄位
value

string

字串值。
JSON 表示法 
{
  "value": string
}
欄位
value

string (int64 format)

int64 值。
JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string
JSON 表示法 
{
  "role": string,
  "userByEmail": string,
  "groupByEmail": string,
  "domain": string,
  "specialGroup": string,
  "iamMember": string,
  "view": {
    object (TableReference)
  },
  "routine": {
    object (RoutineReference)
  },
  "dataset": {
    object (DatasetAccessEntry)
  },
  "condition": {
    object (google.type.Expr)
  }
}
欄位
role

string

應授予這個存取權項目的使用者、群組或網域的 IAM 角色 ID。系統會套用下列舊版對應：

  • OWNER：roles/bigquery.dataOwner
  • WRITER：roles/bigquery.dataEditor
  • READER：roles/bigquery.dataViewer

這個欄位會接受上述任一格式，但只會傳回舊版格式。舉例來說，如果您將這個欄位設為「roles/bigquery.dataOwner」，系統會以「OWNER」的形式傳回。
userByEmail

string

[選擇一項] 要授予存取權的使用者電子郵件地址。例如：fred@example.com。對應至 IAM 政策成員「user:EMAIL」或「serviceAccount:EMAIL」。
groupByEmail

string

[選擇其中一項] 要授予存取權的 Google 群組電子郵件地址。對應至 IAM 政策成員「group:GROUP」。
domain

string

[選擇] 授予存取權的網域。以此指定網域登入的任何者將具有指定之存取權。例如：「example.com」。對應至身分與存取權管理政策成員「domain:DOMAIN」。
specialGroup

string

[選擇一項] 授予存取權的特殊群組。可能的值包括：

  • projectOwners：封閉專案的擁有者。
  • projectReaders：封閉專案的讀者。
  • projectWriters：封閉專案的撰寫者。
  • allAuthenticatedUsers：所有通過驗證的 BigQuery 使用者。

對應至名稱類似的 IAM 成員。
iamMember

string

[選擇其中一項] IAM 政策中出現的其他類型成員，但不是使用者、群組、網域或特殊群組。
view

object (TableReference)

[選擇一項] 要授予存取權的其他資料集檢視畫面。對該檢視表執行的查詢將擁有這個資料集中檢視表/資料表/處理常式的讀取權限。設定這個欄位時，不需要角色欄位。如果任何使用者更新該檢視區塊，您必須透過更新作業再次授予檢視區塊的存取權。
routine

object (RoutineReference)

[Pick one] A routine from a different dataset to grant access to. 針對該處理常式執行的查詢，將具有這個資料集中檢視表/資料表/處理常式的讀取權限。目前僅支援 UDF。設定這個欄位時，不需要角色欄位。如果任何使用者更新了該日常安排，您就必須透過更新作業再次授予日常安排的存取權。
dataset

object (DatasetAccessEntry)

[選擇其中一項] 授權特定資料集中特定類型的所有資源存取這個資料集。目前僅支援檢視畫面。設定這個欄位時，不需要角色欄位。如果該資料集遭到刪除並重新建立，就必須透過更新作業再次授予存取權。
condition

object (google.type.Expr)

選用。繫結條件。如果這個欄位中的 CEL 運算式為 true，系統會將這個存取權繫結視為
JSON 表示法 
{
  "projectId": string,
  "datasetId": string,
  "tableId": string,
  "projectIdAlternative": [
    string
  ],
  "datasetIdAlternative": [
    string
  ],
  "tableIdAlternative": [
    string
  ]
}
欄位
projectId

string

這是必要旗標，包含這個資料表的專案 ID。
datasetId

string

這是必要旗標，包含這個資料表的資料集 ID。
tableId

string

這是必要旗標，資料表的 ID。ID 可包含類別 L (字母)、M (標記)、N (數字)、Pc (連接符，包括底線)、Pd (破折號) 和 Zs (空格) 的 Unicode 字元。詳情請參閱「一般類別」。長度上限為 1,024 個半形字元。某些作業允許在資料表 ID 後方加上分區修飾符，例如 sample_table$20190123。
projectIdAlternative[]

string

請勿使用這個欄位。
datasetIdAlternative[]

string

請勿使用這個欄位。
tableIdAlternative[]

string

請勿使用這個欄位。
JSON 表示法 
{
  "projectId": string,
  "datasetId": string,
  "routineId": string
}
欄位
projectId

string

這是必要旗標，包含此常式的專案 ID。
datasetId

string

這是必要旗標，包含此常式的資料集 ID。
routineId

string

這是必要旗標，處理常式的 ID。ID 只能包含英文字母 (a-z、A-Z)、數字 (0-9) 或底線 (_)，長度上限為 256 個半形字元。
JSON 表示法 
{
  "dataset": {
    object (DatasetReference)
  },
  "targetTypes": [
    enum (TargetType)
  ]
}
欄位
dataset

object (DatasetReference)

這個項目適用的資料集
targetTypes[]

enum (TargetType)

這個項目適用的資料集資源。目前僅支援觀看次數，但日後可能會新增其他目標類型。
JSON 表示法 
{
  "expression": string,
  "title": string,
  "description": string,
  "location": string
}
欄位
expression

string

使用一般運算語言語法的運算式文字表示法。
title

string

選用。運算式的標題，即說明其用途的簡短字串。這可用在允許輸入運算式的 UI 中。
description

string

選用。運算式的說明。這是一段較長的文字，用於說明運算式。例如，使用者在 UI 中將游標懸停在運算式上方時，即可顯示說明文字。
location

string

選用。指出要提報錯誤的運算式所在位置，例如檔案名稱及檔案內的位置。
JSON 表示法 
{
  "kmsKeyName": string
}
欄位
kmsKeyName

string

(選用步驟) 說明用來保護目的地 BigQuery 資料表的 Cloud KMS 加密金鑰。與專案相關聯的 BigQuery 服務帳戶必須有權存取這個加密金鑰。
JSON 表示法 
{
  "value": boolean
}
欄位
value

boolean

布林值。
JSON 表示法 
{
  "sourceDataset": {
    object (DatasetReference)
  }
}
欄位
sourceDataset

object (DatasetReference)

來源資料集參照包含專案編號，而非專案 ID。
JSON 表示法 
{
  "linkState": enum (LinkState)
}
欄位
linkState

enum (LinkState)

僅供輸出。指定連結資料集目前是否處於連結狀態。
JSON 表示法 
{
  "externalSource": string,
  "connection": string
}
欄位
externalSource

string

這是必要旗標，支援這個資料集的外部來源。
connection

string

這是必要旗標，用於存取 external_source 的連線 ID。

格式：projects/{project_id}/locations/{location_id}/connections/{connection_id}
JSON 表示法 
{
  "parameters": {
    string: string,
    ...
  },
  "defaultStorageLocationUri": string
}
欄位
parameters

map (key: string, value: string)

(選用步驟) 鍵/值組合對應表，定義開放原始碼結構定義的參數和屬性。大小上限為 2 MiB。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
defaultStorageLocationUri

string

(選用步驟) 資料集中所有資料表的儲存位置 URI。等同於 Hive 中繼存放區的 databaseLocationUri。長度上限為 1024 個半形字元。
JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string
JSON 表示法 
{
  "tagKey": string,
  "tagValue": string
}
欄位
tagKey

string

這是必要旗標，標記鍵的命名空間友善名稱，例如「12345/environment」，其中 12345 是機構 ID。
tagValue

string

這是必要旗標，標記值的簡短名稱，例如「production」。
JSON 表示法 
{
  "type": enum (RestrictionType)
}
欄位
type

enum (RestrictionType)

僅供輸出。指定資料集/表格限制類型。
JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string

工具註解

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌