MCP Tools Reference: bigquery.googleapis.com

工具：get_table_info

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

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

輸入結構定義

要求提供資料表。

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

string

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

string

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

string

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

輸出內容的結構定義

JSON 表示法 
{
  "kind": string,
  "etag": string,
  "id": string,
  "selfLink": string,
  "tableReference": {
    object (TableReference)
  },
  "friendlyName": string,
  "description": string,
  "labels": {
    string: string,
    ...
  },
  "schema": {
    object (TableSchema)
  },
  "timePartitioning": {
    object (TimePartitioning)
  },
  "rangePartitioning": {
    object (RangePartitioning)
  },
  "clustering": {
    object (Clustering)
  },
  "requirePartitionFilter": boolean,
  "numBytes": string,
  "numPhysicalBytes": string,
  "numLongTermBytes": string,
  "numRows": string,
  "creationTime": string,
  "expirationTime": string,
  "lastModifiedTime": string,
  "type": string,
  "view": {
    object (ViewDefinition)
  },
  "materializedView": {
    object (MaterializedViewDefinition)
  },
  "materializedViewStatus": {
    object (MaterializedViewStatus)
  },
  "externalDataConfiguration": {
    object (ExternalDataConfiguration)
  },
  "biglakeConfiguration": {
    object (BigLakeConfiguration)
  },
  "managedTableType": enum (ManagedTableType),
  "location": string,
  "streamingBuffer": {
    object (Streamingbuffer)
  },
  "encryptionConfiguration": {
    object (EncryptionConfiguration)
  },
  "snapshotDefinition": {
    object (SnapshotDefinition)
  },
  "defaultCollation": string,
  "defaultRoundingMode": enum (RoundingMode),
  "cloneDefinition": {
    object (CloneDefinition)
  },
  "numTimeTravelPhysicalBytes": string,
  "numTotalLogicalBytes": string,
  "numActiveLogicalBytes": string,
  "numLongTermLogicalBytes": string,
  "numCurrentPhysicalBytes": string,
  "numTotalPhysicalBytes": string,
  "numActivePhysicalBytes": string,
  "numLongTermPhysicalBytes": string,
  "numPartitions": string,
  "maxStaleness": string,
  "restrictions": {
    object (RestrictionConfig)
  },
  "tableConstraints": {
    object (TableConstraints)
  },
  "resourceTags": {
    string: string,
    ...
  },
  "tableReplicationInfo": {
    object (TableReplicationInfo)
  },
  "replicas": [
    {
      object (TableReference)
    }
  ],
  "externalCatalogTableOptions": {
    object (ExternalCatalogTableOptions)
  },

  // Union field _partition_definition can be only one of the following:
  "partitionDefinition": {
    object (PartitioningDefinition)
  }
  // End of list of possible types for union field _partition_definition.
}
欄位
kind

string

資源 ID 的類型。
etag

string

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

string

僅供輸出。可明確識別資料表的不透明 ID。
selfLink

string

僅供輸出。可用於再次存取這項資源的網址。
tableReference

object (TableReference)

這是必要旗標，說明這個資料表 ID 的參照。
friendlyName

string

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

string

(選用步驟) 這個資料表的說明，方便使用者瞭解。
labels

map (key: string, value: string)

與這個資料表相關聯的標籤。你可以使用這些項目整理及分組表格。標籤鍵/值的長度不得超過 63 個字元，只能包含小寫英文字母、數字、底線和破折號。可以使用國際字元。標籤值為選填項目。標籤鍵開頭必須是字母，且清單中的每個標籤都必須有不同的鍵。

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

object (TableSchema)

(選用步驟) 說明這個資料表的結構定義。
timePartitioning

object (TimePartitioning)

如果指定，則為這個資料表設定時間分區。
rangePartitioning

object (RangePartitioning)

如有指定，則為這個資料表設定範圍分區。
clustering

object (Clustering)

資料表的叢集規格。必須與時間分區一併指定，資料表中的資料會先分區，然後再分群。
requirePartitionFilter

boolean

(選用步驟) 如果設為 true，查詢這個資料表時，必須指定可用於刪除分區的分區篩選器。
numBytes

string (Int64Value format)

僅供輸出。這個資料表的大小 (以邏輯位元組為單位)，不含串流緩衝區中的任何資料。
numPhysicalBytes

string (Int64Value format)

僅供輸出。這個表格的實際大小 (以位元組為單位)。包括用於時空旅行的儲存空間。
numLongTermBytes

string (Int64Value format)

僅供輸出。資料表中視為「長期儲存」的邏輯位元組數。
numRows

string (UInt64Value format)

僅供輸出。這個資料表中的資料列數，不含串流緩衝區中的任何資料。
creationTime

string (int64 format)

僅供輸出。此資料表建立的時間，從指定期間開始計算，並以毫秒為單位。
expirationTime

string (Int64Value format)

(選用步驟) 這個資料表到期的時間，以從 Epoch 紀元時間算起的毫秒數表示。如果沒有指定，資料表將永遠不會過期。過期的資料表會遭到刪除，儲存空間也會回收。封裝資料集的 defaultTableExpirationMs 屬性可用於設定新建立資料表的預設 expirationTime。
lastModifiedTime

string (uint64 format)

僅供輸出。這個資料表的上次修改時間，以自 Epoch 紀元時間起的毫秒數表示。
type

string

僅供輸出。說明資料表類型。支援的值如下：

  • TABLE：一般的 BigQuery 資料表。
  • VIEW：由 SQL 查詢定義的虛擬資料表。
  • EXTERNAL：參照儲存在外部儲存系統 (例如 Google Cloud Storage) 中的資料的資料表。
  • MATERIALIZED_VIEW：由 SQL 查詢定義的預先計算檢視區塊。
  • SNAPSHOT：不可變更的 BigQuery 資料表，可保留特定時間點的基礎資料表內容。如要瞭解資料表快照的更多資訊，請參閱這篇文章。

預設值為 TABLE。
view

object (ViewDefinition)

(選用步驟) 檢視畫面定義。
materializedView

object (MaterializedViewDefinition)

(選用步驟) 具體化檢視表定義。
materializedViewStatus

object (MaterializedViewStatus)

僅供輸出。具體化檢視表狀態。
externalDataConfiguration

object (ExternalDataConfiguration)

(選用步驟) 說明儲存在 BigQuery 外部的資料表資料格式、位置和其他屬性。定義這些屬性後，即可查詢資料來源，就像查詢標準 BigQuery 資料表一樣。
biglakeConfiguration

object (BigLakeConfiguration)

(選用步驟) 指定 Apache Iceberg 專用 BigQuery 資料表的設定。
managedTableType

enum (ManagedTableType)

(選用步驟) 如果設定，則會覆寫資料集中設定的預設受管理資料表類型。
location

string

僅供輸出。資料表所在的地理位置。這個值會沿用資料集的值。
streamingBuffer

object (Streamingbuffer)

僅供輸出。如果這個資料表有串流緩衝區，這個欄位會包含相關資訊。如果資料表未串流至緩衝區，或串流緩衝區中沒有資料，系統就不會顯示這個欄位。
encryptionConfiguration

object (EncryptionConfiguration)

自訂加密設定 (例如 Cloud KMS 金鑰)。
snapshotDefinition

object (SnapshotDefinition)

僅供輸出。內含快照的相關資訊。這個值是在建立快照時設定。
defaultCollation

string

(選用步驟) 定義資料表中新 STRING 欄位的預設定序規格。建立或更新資料表時，如果將 STRING 欄位新增至資料表，但未明確指定定序，資料表就會沿用預設定序。變更這個欄位只會影響之後新增的欄位，不會變更現有欄位。支援的值如下：

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

enum (RoundingMode)

(選用步驟) 定義資料表中新十進位欄位 (NUMERIC 或 BIGNUMERIC) 的預設捨入模式規格。建立或更新資料表時，如果將十進位欄位新增至資料表，但未明確指定捨入模式，則該欄位會沿用資料表的預設捨入模式。變更這個欄位不會影響現有欄位。
cloneDefinition

object (CloneDefinition)

僅供輸出。內含複製的相關資訊。這個值是透過複製作業設定。
numTimeTravelPhysicalBytes

string (Int64Value format)

僅供輸出。時空旅行儲存空間 (已刪除或變更的資料) 使用的實體位元組數。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
numTotalLogicalBytes

string (Int64Value format)

僅供輸出。資料表或具體化檢視中的邏輯位元組總數。
numActiveLogicalBytes

string (Int64Value format)

僅供輸出。未滿 90 天的邏輯位元組數量。
numLongTermLogicalBytes

string (Int64Value format)

僅供輸出。超過 90 天的邏輯位元組數量。
numCurrentPhysicalBytes

string (Int64Value format)

僅供輸出。目前即時資料儲存空間使用的實體位元組數。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
numTotalPhysicalBytes

string (Int64Value format)

僅供輸出。這個表格的實際大小 (以位元組為單位)。這也包括用於時空旅行的儲存空間。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
numActivePhysicalBytes

string (Int64Value format)

僅供輸出。未滿 90 天的實體位元組數量。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
numLongTermPhysicalBytes

string (Int64Value format)

僅供輸出。超過 90 天的實體位元組數量。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
numPartitions

string (Int64Value format)

僅供輸出。資料表或具體化檢視區塊中的分區數。這項資料並非即時更新，可能會有幾秒到幾分鐘的延遲。
maxStaleness

string

(選用步驟) 查詢資料表 (或過時的具體化檢視表) 時，傳回的資料最多可能過時多久。以 sql IntervalValue 類型編碼的字串編碼表示陳舊程度。
restrictions

object (RestrictionConfig)

(選用步驟) 僅供輸出。資料表的限制設定。如果已設定，請根據設定限制資料表的特定存取權。詳情請參閱「資料輸出」。
tableConstraints

object (TableConstraints)

(選用步驟) 資料表主鍵和外鍵資訊
resourceTags

map (key: string, value: string)

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

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

object (TableReplicationInfo)

(選用步驟) 以 AS REPLICA DDL 建立的資料表 (例如 CREATE MATERIALIZED VIEW mv1 AS REPLICA OF src_mv) 的資料表複寫資訊。
replicas[]

object (TableReference)

(選用步驟) 僅供輸出。目前在資料表上有效的所有副本的資料表參照。
externalCatalogTableOptions

object (ExternalCatalogTableOptions)

(選用步驟) 定義開放原始碼相容資料表的選項。

聯集欄位 _partition_definition。

_partition_definition 只能是下列其中一個設定：
partitionDefinition

object (PartitioningDefinition)

(選用步驟) 所有資料表格式的分區資訊，包括受管理的分區資料表、Hive 分區資料表、Iceberg 分區資料表和 Metastore 分區資料表。這個欄位只會填入中繼存放區分區資料表。如果是其他表格格式，這就是僅限輸出的欄位。
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 表示法 
{
  "value": string
}
欄位
value

string

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

string
value

string
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

這是必要旗標，欄位資料類型。可能的值包括：

  • STRING
  • BYTES
  • INTEGER (或 INT64)
  • FLOAT (或 FLOAT64)
  • BOOLEAN (或 BOOL)
  • TIMESTAMP
  • DATE
  • 時間
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • 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)

(選用步驟) 這個欄位的值長度上限 (適用於 STRINGS 或 BYTES)。

如未指定 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)，但未指定比例 (因此比例會解讀為等於零)：[-10P + 1, 10P - 1]。

如果同時指定有效位數和小數位數，可接受的值如下：

  • 如果 type =「NUMERIC」：1 ≤ precision - scale ≤ 29 且 0 ≤ scale ≤ 9。
  • 如果 type =「BIGNUMERIC」：1 ≤ precision - scale ≤ 38 且 0 ≤ scale ≤ 38。

如果只指定精確度，但未指定小數位數 (因此小數位數會解讀為零)，則精確度可接受的值如下：

  • 如果 type =「NUMERIC」：1 ≤ precision ≤ 29。
  • 如果 type =「BIGNUMERIC」：1 ≤ precision ≤ 38。

如果指定了 scale，但未指定 precision，則無效。
scale

string (int64 format)

(選用步驟) 如要瞭解精確度，請參閱說明文件。
timestampPrecision

string (Int64Value format)

(選用步驟) TIMESTAMP 類型秒數的精確度 (以 10 為底的總位數上限)。

可能的值包括：* 6 (預設值，適用於微秒精確度的 TIMESTAMP 類型) * 12 (適用於皮秒精確度的 TIMESTAMP 類型)
roundingMode

enum (RoundingMode)

(選用步驟) 指定儲存 NUMERIC 和 BIGNUMERIC 類型的值時要使用的捨入模式。
collation

string

(選用步驟) 只有在欄位類型為 STRING 時，才能設定欄位對照。支援的值如下：

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

string

(選用步驟) 指定這個欄位預設值的 SQL 運算式。
rangeElementType

object (FieldElementType)

(選用步驟) 如果這個欄位的類型為 RANGE，則為 RANGE 的子類型。如果類型為 RANGE，則必須填寫這個欄位。欄位元素類型的值可以是下列項目：

  • DATE
  • DATETIME
  • TIMESTAMP
foreignTypeDefinition

string

(選用步驟) 外來資料類型的定義。僅適用於頂層架構欄位 (不適用於巢狀欄位)。如果類型為 FOREIGN，則必須填寫這個欄位。
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 表示法 
{
  "type": string,
  "expirationMs": string,
  "field": string,
  "requirePartitionFilter": boolean
}
欄位
type

string

這是必要旗標，支援的類型包括 DAY、HOUR、MONTH 和 YEAR，分別代表每日、每小時、每月和每年產生一個分區。
expirationMs

string (Int64Value format)

(選用步驟) 要保留分區儲存空間的毫秒數。由於 0 是無效值，因此這裡會使用包裝函式。
field

string

(選用步驟) 如未設定，資料表會依虛擬資料欄「_PARTITIONTIME」分區；如已設定，資料表會依這個欄位分區。這個欄位必須是頂層 TIMESTAMP 或 DATE 欄位。模式必須為 NULLABLE 或 REQUIRED。由於空字串是無效值，因此這裡會使用包裝函式。
requirePartitionFilter
(deprecated)

boolean

如果設為 true，查詢這個資料表時，必須指定可用於刪除分區的分區篩選器。這個欄位已淘汰，請改為在資料表本身設定同名的欄位。這個欄位需要包裝函式，因為如果使用者明確設定，我們想輸出預設值 (false)。
JSON 表示法 
{
  "value": boolean
}
欄位
value

boolean

布林值。
JSON 表示法 
{
  "field": string,
  "range": {
    object (Range)
  }
}
欄位
field

string

這是必要旗標，用於對資料表進行分區的資料欄名稱。必須是頂層的 INT64 資料欄，且模式為 NULLABLE 或 REQUIRED。
range

object (Range)

定義範圍分區的範圍。
JSON 表示法 
{
  "start": string,
  "end": string,
  "interval": string
}
欄位
start

string

這是必要旗標，範圍分區的起始值 (含)。這個欄位是 INT64 值，以字串表示。
end

string

這是必要旗標，範圍分區的結束值 (不含)。這個欄位是 INT64 值，以字串表示。
interval

string

這是必要旗標，每個間隔的寬度。這個欄位是 INT64 值，以字串表示。
JSON 表示法 
{
  "fields": [
    string
  ]
}
欄位
fields[]

string

要用來叢集資料的一或多個欄位。系統僅支援頂層、非重複的簡單類型欄位。為了篩選，叢集欄位的排序應從最重要到最不重要。

詳情請參閱叢集資料表簡介。
JSON 表示法 
{
  "partitionedColumn": [
    {
      object (PartitionedColumn)
    }
  ]
}
欄位
partitionedColumn[]

object (PartitionedColumn)

(選用步驟) 每個分割欄的詳細資料。除了中繼存放區分區資料表以外，所有分區類型都會輸出這個欄位。BigQuery 原生資料表僅支援 1 個分區資料欄。其他表格類型可能支援 0 個、1 個或多個分割欄。如果是 Metastore 分區資料表，順序必須與 Hive Metastore 中的定義順序相符，且必須與資料表的實體版面配置相符。例如，假設使用者要求系統 將文字從英文翻譯成法文

CREATE TABLE a_table(id BIGINT, name STRING) PARTITIONED BY (city STRING, state STRING)。

在這種情況下，值必須依序為 ['city', 'state']。
JSON 表示法 
{

  // Union field _field can be only one of the following:
  "field": string
  // End of list of possible types for union field _field.
}
欄位

聯集欄位 _field。

_field 只能是下列其中一個設定：
field

string

這是必要旗標，分區資料欄的名稱。
JSON 表示法 
{
  "value": string
}
欄位
value

string

uint64 值。
JSON 表示法 
{
  "query": string,
  "userDefinedFunctionResources": [
    {
      object (UserDefinedFunctionResource)
    }
  ],
  "useLegacySql": boolean,
  "useExplicitColumnNames": boolean,
  "privacyPolicy": {
    object (PrivacyPolicy)
  },
  "foreignDefinitions": [
    {
      object (ForeignViewDefinition)
    }
  ]
}
欄位
query

string

這是必要旗標，在參照檢視區塊時，BigQuery 執行的查詢。
userDefinedFunctionResources[]

object (UserDefinedFunctionResource)

說明查詢中使用的使用者定義函式資源。
useLegacySql

boolean

指定是否要為這個檢視區塊使用 BigQuery 的舊版 SQL。預設值為 true。如果設為 false，檢視畫面會使用 BigQuery 的 GoogleSQL：https://cloud.google.com/bigquery/sql-reference/

參照這個檢視區塊的查詢和檢視區塊必須使用相同的旗標值。由於預設值為 True，因此這裡會使用包裝函式。
useExplicitColumnNames

boolean

如果明確指定資料欄名稱，則為 True。例如使用「CREATE VIEW v(c1, c2) AS ...」語法。只能為 GoogleSQL 檢視區塊設定。
privacyPolicy

object (PrivacyPolicy)

(選用步驟) 指定檢視區塊的隱私權政策。
foreignDefinitions[]

object (ForeignViewDefinition)

(選用步驟) 外觀檢視畫面。
JSON 表示法 
{
  "resourceUri": string,
  "inlineCode": string,
  "inlineCodeAlternative": [
    string
  ]
}
欄位
resourceUri

string

[選擇一項] 要從 Google Cloud Storage URI (gs://bucket/path) 載入的程式碼資源。
inlineCode

string

[選擇一項] 含有使用者定義函式 (UDF) 程式碼的內嵌資源。提供內嵌程式碼資源，等同於提供含有相同程式碼的檔案 URI。
inlineCodeAlternative[]

string
JSON 表示法 
{

  // Union field privacy_policy can be only one of the following:
  "aggregationThresholdPolicy": {
    object (AggregationThresholdPolicy)
  },
  "differentialPrivacyPolicy": {
    object (DifferentialPrivacyPolicy)
  }
  // End of list of possible types for union field privacy_policy.

  // Union field _join_restriction_policy can be only one of the following:
  "joinRestrictionPolicy": {
    object (JoinRestrictionPolicy)
  }
  // End of list of possible types for union field _join_restriction_policy.
}
欄位
聯集欄位 privacy_policy。與這項需求規格相關聯的隱私權政策。每個資料來源物件只能使用一種隱私權方法。privacy_policy 只能是下列其中一個設定：
aggregationThresholdPolicy

object (AggregationThresholdPolicy)

(選用步驟) 用於匯總門檻的政策。
differentialPrivacyPolicy

object (DifferentialPrivacyPolicy)

(選用步驟) 用於差異化隱私的政策。

聯集欄位 _join_restriction_policy。

_join_restriction_policy 只能是下列其中一個設定：
joinRestrictionPolicy

object (JoinRestrictionPolicy)

(選用步驟) 加入限制政策不屬於任何政策，因為這項政策可與其他政策一併設定。這項政策可讓資料供應商在從隱私權保護檢視區塊查詢資料時，強制執行「join_allowed_columns」的聯結。
JSON 表示法 
{
  "privacyUnitColumns": [
    string
  ],

  // Union field _threshold can be only one of the following:
  "threshold": string
  // End of list of possible types for union field _threshold.
}
欄位
privacyUnitColumns[]

string

(選用步驟) 與這項政策相關聯的隱私權單位欄。目前每個資料來源物件 (表格、檢視區塊) 只能有一個隱私權單位欄。在擴充功能的中繼資料中，以重複欄位表示，方便日後擴充至多個資料欄。不得重複或重複使用結構體欄位。如果是巢狀欄位，請使用點記號 (「outer.inner」)

聯集欄位 _threshold。

_threshold 只能是下列其中一個設定：
threshold

string (int64 format)

(選用步驟) 「匯總門檻」政策的門檻。
JSON 表示法 
{

  // Union field _max_epsilon_per_query can be only one of the following:
  "maxEpsilonPerQuery": number
  // End of list of possible types for union field _max_epsilon_per_query.

  // Union field _delta_per_query can be only one of the following:
  "deltaPerQuery": number
  // End of list of possible types for union field _delta_per_query.

  // Union field _max_groups_contributed can be only one of the following:
  "maxGroupsContributed": string
  // End of list of possible types for union field _max_groups_contributed.

  // Union field _privacy_unit_column can be only one of the following:
  "privacyUnitColumn": string
  // End of list of possible types for union field _privacy_unit_column.

  // Union field _epsilon_budget can be only one of the following:
  "epsilonBudget": number
  // End of list of possible types for union field _epsilon_budget.

  // Union field _delta_budget can be only one of the following:
  "deltaBudget": number
  // End of list of possible types for union field _delta_budget.

  // Union field _epsilon_budget_remaining can be only one of the following:
  "epsilonBudgetRemaining": number
  // End of list of possible types for union field _epsilon_budget_remaining.

  // Union field _delta_budget_remaining can be only one of the following:
  "deltaBudgetRemaining": number
  // End of list of possible types for union field _delta_budget_remaining.
}
欄位

聯集欄位 _max_epsilon_per_query。

_max_epsilon_per_query 只能是下列其中一個設定：
maxEpsilonPerQuery

number

(選用步驟) 查詢可消耗的 Epsilon 值上限。如果訂閱者在 SELECT 查詢中將 epsilon 指定為參數，則該值必須小於或等於這個值。epsilon 參數可控制要加入群組的雜訊量，epsilon 越高，雜訊就越少。

聯集欄位 _delta_per_query。

_delta_per_query 只能是下列其中一個設定：
deltaPerQuery

number

(選用步驟) 每個查詢使用的 Delta 值。Delta 代表任何資料列無法達到 epsilon 差異隱私的機率。指出在查詢結果中公開匯總資料列的相關風險。

聯集欄位 _max_groups_contributed。

_max_groups_contributed 只能是下列其中一個設定：
maxGroupsContributed

string (int64 format)

(選用步驟) 每個查詢使用的最大群組貢獻值。代表每個受保護實體可貢獻的群組數量上限。變更這個值不會改善或惡化隱私權。準確度和實用性的最佳值取決於查詢和資料。

聯集欄位 _privacy_unit_column。

_privacy_unit_column 只能是下列其中一個設定：
privacyUnitColumn

string

(選用步驟) 與這項政策相關聯的隱私權單位欄。每個資料來源物件 (表格、檢視區塊) 的差異隱私權政策只能有一個隱私權單位欄。

聯集欄位 _epsilon_budget。

_epsilon_budget 只能是下列其中一個設定：
epsilonBudget

number

(選用步驟) 針對受隱私權保護的檢視畫面，所有查詢的總 Epsilon 預算。針對這個檢視區塊的每項訂閱者查詢，都會收取查詢中要求的 epsilon 金額。如果預算充足，訂閱者查詢就會嘗試完成。但仍可能因其他原因而失敗，屆時我們會退還款項。如果預算不足，系統會拒絕查詢。如果單一查詢參照多個檢視區塊，系統可能會多次嘗試收費。在這種情況下，所有費用都必須有足夠的預算，否則查詢會遭到拒絕，且系統會盡量退還費用。預算沒有重新整理政策，只能透過 ALTER VIEW 更新，或建立可使用新預算查詢的新檢視區塊來規避。

聯集欄位 _delta_budget。

_delta_budget 只能是下列其中一個設定：
deltaBudget

number

(選用步驟) 針對受隱私權保護的檢視畫面，所有查詢的總 Delta 預算。每項對這個檢視區塊執行的訂閱者查詢，都會收取貢獻者透過隱私權政策的 delta_per_query 欄位預先定義的 Delta 金額。如果預算充足，訂閱者查詢就會嘗試完成。但仍可能因其他原因而失敗，屆時我們會退還款項。如果預算不足，系統會拒絕查詢。如果單一查詢參照多個檢視區塊，系統可能會多次嘗試收費。在這種情況下，所有費用都必須有足夠的預算，否則查詢會遭到拒絕，且系統會盡量退還費用。預算沒有重新整理政策，只能透過 ALTER VIEW 更新，或建立可使用新預算查詢的新檢視區塊來規避。

聯集欄位 _epsilon_budget_remaining。

_epsilon_budget_remaining 只能是下列其中一個設定：
epsilonBudgetRemaining

number

僅供輸出。剩餘的 epsilon 預算。如果預算用盡，就無法再進行查詢。請注意，系統會在查詢執行前扣除查詢預算。如果查詢失敗或取消，系統會退還預算。在這種情況下，剩餘預算金額可能會增加。

聯集欄位 _delta_budget_remaining。

_delta_budget_remaining 只能是下列其中一個設定：
deltaBudgetRemaining

number

僅供輸出。剩餘的預算差異。如果預算用盡，就無法再進行查詢。請注意，系統會在查詢執行前扣除查詢預算。如果查詢失敗或取消，系統會退還預算。在這種情況下，剩餘預算金額可能會增加。
JSON 表示法 
{
  "joinAllowedColumns": [
    string
  ],

  // Union field _join_condition can be only one of the following:
  "joinCondition": enum (JoinCondition)
  // End of list of possible types for union field _join_condition.
}
欄位
joinAllowedColumns[]

string

(選用步驟) 只能在允許的資料欄上進行聯結。對於 join_conditions JOIN_ANY 和 JOIN_ALL，這個欄位必須指定，但不能設為 JOIN_BLOCKED。

聯集欄位 _join_condition。

_join_condition 只能是下列其中一個設定：
joinCondition

enum (JoinCondition)

(選用步驟) 指定查詢檢視區塊時是否需要聯結。預設值為 JOIN_CONDITION_UNSPECIFIED。
JSON 表示法 
{
  "query": string,
  "dialect": string
}
欄位
query

string

這是必要旗標，定義檢視區塊的查詢。
dialect

string

(選用步驟) 代表查詢的方言。
JSON 表示法 
{
  "query": string,
  "lastRefreshTime": string,
  "enableRefresh": boolean,
  "refreshIntervalMs": string,
  "allowNonIncrementalDefinition": boolean
}
欄位
query

string

這是必要旗標，查詢結果會保留的查詢。
lastRefreshTime

string (int64 format)

僅供輸出。上次重新整理這個具體化檢視區塊的時間，以從 Epoch 紀元時間算起的毫秒數表示。
enableRefresh

boolean

(選用步驟) 在基本資料表更新時，啟用具體化檢視表的自動重新整理功能。預設值為「true」。
refreshIntervalMs

string (UInt64Value format)

(選用步驟) 這個具體化檢視的重新整理頻率上限。預設值為「1800000」(30 分鐘)。
allowNonIncrementalDefinition

boolean

(選用步驟) 這個選項會聲明要建構不會遞增重新整理的具體化檢視區塊。非增量具體化檢視表支援更多 SQL 查詢。實體化檢視區塊建立後，就無法變更 allow_non_incremental_definition 選項。
JSON 表示法 
{
  "refreshWatermark": string,
  "lastRefreshStatus": {
    object (ErrorProto)
  }
}
欄位
refreshWatermark

string (Timestamp format)

僅供輸出。重新整理具體化檢視區塊的水印。在此之前，基礎資料表的資料會收集到具體化檢視區塊快取中。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastRefreshStatus

object (ErrorProto)

僅供輸出。上次自動重新整理時發生錯誤。如果顯示這個圖示，表示上次自動重新整理失敗。
JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負值秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果秒數值為負數，且包含小數，奈秒值仍須為非負數，且會向前計時。必須介於 0 至 999,999,999 之間 (含)。
JSON 表示法 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
欄位
reason

string

簡短的錯誤代碼，可摘要說明錯誤。
location

string

指明發生錯誤的位置 (如果有的話)。
debugInfo

string

偵錯資訊。這個屬性是 Google 內部屬性，不應使用。
message

string

使用者容易理解的錯誤說明。
JSON 表示法 
{
  "sourceUris": [
    string
  ],
  "fileSetSpecType": enum (FileSetSpecType),
  "schema": {
    object (TableSchema)
  },
  "sourceFormat": string,
  "maxBadRecords": integer,
  "autodetect": boolean,
  "ignoreUnknownValues": boolean,
  "compression": string,
  "csvOptions": {
    object (CsvOptions)
  },
  "jsonOptions": {
    object (JsonOptions)
  },
  "bigtableOptions": {
    object (BigtableOptions)
  },
  "googleSheetsOptions": {
    object (GoogleSheetsOptions)
  },
  "maxBadRecordsAlternative": [
    integer
  ],
  "hivePartitioningOptions": {
    object (HivePartitioningOptions)
  },
  "connectionId": string,
  "decimalTargetTypes": [
    enum (DecimalTargetType)
  ],
  "avroOptions": {
    object (AvroOptions)
  },
  "jsonExtension": enum (JsonExtension),
  "parquetOptions": {
    object (ParquetOptions)
  },
  "referenceFileSchemaUri": string,
  "metadataCacheMode": enum (MetadataCacheMode),
  "timestampTargetPrecision": [
    integer
  ],

  // Union field _object_metadata can be only one of the following:
  "objectMetadata": enum (ObjectMetadata)
  // End of list of possible types for union field _object_metadata.

  // Union field _time_zone can be only one of the following:
  "timeZone": string
  // End of list of possible types for union field _time_zone.

  // Union field _date_format can be only one of the following:
  "dateFormat": string
  // End of list of possible types for union field _date_format.

  // Union field _datetime_format can be only one of the following:
  "datetimeFormat": string
  // End of list of possible types for union field _datetime_format.

  // Union field _time_format can be only one of the following:
  "timeFormat": string
  // End of list of possible types for union field _time_format.

  // Union field _timestamp_format can be only one of the following:
  "timestampFormat": string
  // End of list of possible types for union field _timestamp_format.
}
欄位
sourceUris[]

string

[必要] 指向 Google Cloud 中資料的完整 URI。Google Cloud Storage URI：每個 URI 都可以包含一個「*」萬用字元，而且它必須出現在「bucket」名稱之後。與載入工作相關的大小限制適用於外部資料來源。Google Cloud Bigtable URI：您只能指定一個 URI，且該 URI 對 Google Cloud Bigtable 資料表來說必須是完整且有效的 HTTPS 網址。Google Cloud Datastore 備份只能指定一個 URI。此外，也不允許使用「*」萬用字元。
fileSetSpecType

enum (FileSetSpecType)

(選用步驟) 指定如何解讀來源 URI，以建構要載入的檔案集。根據預設，來源 URI 會根據基礎儲存空間展開。其他選項包括指定資訊清單檔案。僅適用於物件儲存系統。
schema

object (TableSchema)

(選用步驟) 資料的結構定義。如果未開啟自動偵測功能，CSV 和 JSON 格式就需要結構定義。Google Cloud Bigtable、Cloud Datastore 備份、Avro、ORC 和 Parquet 格式不允許使用結構定義。
sourceFormat

string

[必要] 資料格式。如果是 CSV 檔案，請指定「CSV」。如為 Google 試算表，請指定「GOOGLE_SHEETS」。如為以換行符號分隔的 JSON，請指定「NEWLINE_DELIMITED_JSON」。如果是 Avro 檔案，請指定「AVRO」。如果是 Google Cloud Datastore 備份，請指定「DATASTORE_BACKUP」。如果是 Apache Iceberg 資料表，請指定「ICEBERG」。如果是 ORC 檔案，請指定「ORC」。如果是 Parquet 檔案，請指定「PARQUET」。[Beta] 針對 Google Cloud Bigtable，指定「BIGTABLE」。
maxBadRecords

integer

(選用步驟) BigQuery 讀取資料時可忽略的錯誤記錄數量上限。如果損壞記錄的數量超過這個值，系統會在工作結果中傳回無效錯誤。預設值為 0，表示所有記錄都必須有效。如果是 Google Cloud Bigtable、Google Cloud Datastore 備份、Avro、ORC 和 Parquet 格式，系統會忽略這項設定。
autodetect

boolean

嘗試自動偵測結構定義和格式選項。系統會採用明確指定的任何選項。
ignoreUnknownValues

boolean

(選用步驟) 表示 BigQuery 是否應允許不在資料表結構定義中的其他值。如為 true，會忽略其他值。如為 false，系統會將包含其他欄位的記錄視為損壞記錄；如果損壞記錄過多，工作結果就會顯示無效錯誤。預設值為 false。sourceFormat 屬性決定 BigQuery 將什麼視為其他值：如為 CSV，則是結尾資料欄；如為 JSON，則是不符合任何資料欄名稱的已命名值；如為 Google Cloud Bigtable，則會忽略這項設定。Google Cloud Datastore 備份：系統會忽略這項設定。Avro：系統會忽略這項設定。ORC：系統會忽略這項設定。Parquet：系統會忽略這項設定。
compression

string

(選用步驟) 資料來源的壓縮類型。可能的值包括 GZIP 和 NONE。預設值為 NONE。如果是 Google Cloud Bigtable、Google Cloud Datastore 備份、Avro、ORC 和 Parquet 格式，系統會忽略這項設定。空字串是無效值。
csvOptions

object (CsvOptions)

(選用步驟) 如果 sourceFormat 設為 CSV，則要設定其他屬性。
jsonOptions

object (JsonOptions)

(選用步驟) 如果 sourceFormat 設為 JSON，則要設定其他屬性。
bigtableOptions

object (BigtableOptions)

(選用步驟) 如果 sourceFormat 設為 BIGTABLE，則為其他選項。
googleSheetsOptions

object (GoogleSheetsOptions)

(選用步驟) 如果 sourceFormat 設為 GOOGLE_SHEETS，則為其他選項。
maxBadRecordsAlternative[]

integer

請勿使用這個欄位。
hivePartitioningOptions

object (HivePartitioningOptions)

(選用步驟) 設定後，系統會設定 Hive 分區支援。並非所有儲存空間格式都支援 Hive 分區，在不支援的格式中要求 Hive 分區會導致錯誤，提供無效規格也會導致錯誤。
connectionId

string

(選用步驟) 連線，指定用於讀取外部儲存空間 (例如 Azure Blob、Cloud Storage 或 S3) 的憑證。connection_id 的格式可以是 {project_id}.{location_id};{connection_id} 或 projects/{project_id}/locations/{location_id}/connections/{connection_id}。
decimalTargetTypes[]

enum (DecimalTargetType)

定義來源小數值轉換成的可能 SQL 資料類型清單。這份清單和十進位欄位的有效位數和小數位數參數，會決定目標型別。系統會按照 NUMERIC、BIGNUMERIC 和 STRING 的順序，選取指定清單中支援的有效位數和小數位數類型。STRING 支援所有有效位數和小數位數值。如果清單中的類型都不支援有效位數和小數位數，系統會選取指定清單中支援範圍最廣的類型，且如果讀取資料時值超出支援範圍，就會擲回錯誤。

示例：假設這個欄位的值為 ["NUMERIC", "BIGNUMERIC"]。如果 (precision,scale) 為：

  • (38,9) -> NUMERIC;
  • (39,9) -> BIGNUMERIC (NUMERIC 無法保留 30 個整數數字)；
  • (38,10) -> BIGNUMERIC (NUMERIC 無法保留 10 個小數位數)；
  • (76,38) -> BIGNUMERIC;
  • (77,38) -> BIGNUMERIC (如果值超出支援範圍，就會發生錯誤)。

這個欄位不得含有重複的類型。這個欄位中的類型順序不會有影響。舉例來說，["BIGNUMERIC", "NUMERIC"] 與 ["NUMERIC", "BIGNUMERIC"] 相同，且 NUMERIC 一律優先於 BIGNUMERIC。

ORC 的預設值為 ["NUMERIC", "STRING"]，其他檔案格式則為 ["NUMERIC"]。
avroOptions

object (AvroOptions)

(選用步驟) 如果 sourceFormat 設為 AVRO，則要設定的額外屬性。
jsonExtension

enum (JsonExtension)

(選用步驟) 與 source_format 以換行符號分隔的 JSON 一併使用的載入選項，表示要載入 JSON 的變體。如要載入以換行符號分隔的 GeoJSON，請指定 GEOJSON (且 source_format 必須設為 NEWLINE_DELIMITED_JSON)。
parquetOptions

object (ParquetOptions)

(選用步驟) 如果 sourceFormat 設為 PARQUET，則要設定的額外屬性。
referenceFileSchemaUri

string

(選用步驟) 建立外部資料表時，使用者可以提供含有資料表結構定義的參考檔案。這項功能適用於下列格式：AVRO、PARQUET、ORC。
metadataCacheMode

enum (MetadataCacheMode)

(選用步驟) 資料表的「中繼資料快取模式」。設定此選項可啟用外部資料來源的中繼資料快取。
timestampTargetPrecision[]

integer

TIMESTAMP 類型秒數的精確度 (以十進位表示的位數總數上限)，允許用於自動偵測模式的目的地資料表。

適用於 CSV 格式。

如為 CSV 格式，可能的值包括：未指定、[] 或 [6]：所有自動偵測到的 TIMESTAMP 欄的 timestamp(6) [6, 12]：所有自動偵測到的 TIMESTAMP 欄的 timestamp(6)，這些欄的子秒數少於 6 位數。對於所有自動偵測到的 TIMESTAMP 資料欄，如果子秒數超過 6 位數，則為 timestamp(12)。[12]：所有自動偵測到的 TIMESTAMP 資料欄的時間戳記(12)。

系統會忽略這個陣列中的元素順序。如果輸入內容的精確度高於這個陣列中的最高目標精確度，系統會將輸入內容截斷。

聯集欄位 _object_metadata。

_object_metadata 只能是下列其中一個設定：
objectMetadata

enum (ObjectMetadata)

(選用步驟) ObjectMetadata 用於建立物件資料表。物件表包含在 source_uris 找到的物件清單 (及其相關中繼資料)。如果已設定 ObjectMetadata，則應省略 source_format。

目前僅支援 SIMPLE 物件中繼資料類型。

聯集欄位 _time_zone。

_time_zone 只能是下列其中一個設定：
timeZone

string

(選用步驟) 剖析沒有特定時區資訊的時間戳記值時所用的時區 (例如 2024-04-20 12:34:56)。預期格式為 IANA 時區字串 (例如 America/Los_Angeles)。

聯集欄位 _date_format。

_date_format 只能是下列其中一個設定：
dateFormat

string

(選用步驟) 用來剖析 DATE 值的格式。支援 C 樣式和 SQL 樣式的值。

聯集欄位 _datetime_format。

_datetime_format 只能是下列其中一個設定：
datetimeFormat

string

(選用步驟) 用來剖析 DATETIME 值的格式。支援 C 樣式和 SQL 樣式的值。

聯集欄位 _time_format。

_time_format 只能是下列其中一個設定：
timeFormat

string

(選用步驟) 用來剖析 TIME 值的格式。支援 C 樣式和 SQL 樣式的值。

聯集欄位 _timestamp_format。

_timestamp_format 只能是下列其中一個設定：
timestampFormat

string

(選用步驟) 用來剖析 TIMESTAMP 值的格式。支援 C 樣式和 SQL 樣式的值。
JSON 表示法 
{
  "value": integer
}
欄位
value

integer

int32 值。
JSON 表示法 
{
  "fieldDelimiter": string,
  "skipLeadingRows": string,
  "quote": string,
  "allowQuotedNewlines": boolean,
  "allowJaggedRows": boolean,
  "encoding": string,
  "preserveAsciiControlCharacters": boolean,
  "nullMarker": string,
  "nullMarkers": [
    string
  ],
  "sourceColumnMatch": string
}
欄位
fieldDelimiter

string

(選用步驟) CSV 檔案中的欄位分隔符。分隔符會解讀為單一位元組。如果是以 ISO-8859-1 編碼的檔案，可以使用任何單一字元做為分隔符。如果是以 UTF-8 編碼的檔案，可直接使用十進位範圍 1 到 127 (U+0001 到 U+007F) 的字元。以多個位元組編碼的 UTF-8 字元 (即 U+0080 以上) 只會使用第一個位元組分隔欄位。其餘位元組會視為欄位的一部分。BigQuery 也支援使用逸出序列 "\t" (U+0009) 來指定定位點分隔符。預設值為半形逗號 (「,」，U+002C)。
skipLeadingRows

string (Int64Value format)

(選用步驟) BigQuery 讀取資料時，會略過 CSV 檔案開頭的列數。預設值為 0。如果檔案中有應略過的標頭列，這項屬性就非常實用。開啟自動偵測功能後，系統會執行下列操作：

  • 未指定 skipLeadingRows - 自動偵測會嘗試偵測第一列中的標題。如果系統未偵測到標題，就會將該列視為資料。否則系統會從第二列開始讀取資料。
  • skipLeadingRows 為 0 - 指示自動偵測沒有標題，且應從第一列開始讀取資料。
  • skipLeadingRows = N > 0 - 自動偵測會略過 N-1 列，並嘗試偵測第 N 列中的標題。如果系統未偵測到標題，就會直接略過第 N 列。否則系統會使用第 N 列擷取偵測到的結構定義的資料欄名稱。
quote

string

(選用步驟) 在 CSV 檔案中用來引用資料區段的值。BigQuery 會將字串轉換成 ISO-8859-1 編碼格式，並使用已編碼字串的第一個位元組來分割原始的二進位資料。預設值為雙引號 (「"」)。如果資料未包含引用區段，請將這個屬性值設為空字串。如果資料包含引用的換行符號字元，您也必須將 allowQuotedNewlines 屬性設為 true。如要在加上引號的值中加入特定引號字元，請在該字元前面加上相符的引號字元。舉例來說，如要逸出預設字元「"」，請使用「""」。
allowQuotedNewlines

boolean

(選用步驟) 指出 BigQuery 是否應允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false。
allowJaggedRows

boolean

(選用步驟) 指出 BigQuery 是否應接受缺少結尾自選欄的資料列。如為 true，BigQuery 會將缺少的結尾資料欄視為空值。如為 false，系統會將缺少結尾資料欄的記錄視為損壞記錄；如果損壞記錄過多，工作結果中就會出現無效錯誤。預設值為 false。
encoding

string

(選用步驟) 資料的字元編碼。支援的值為 UTF-8、ISO-8859-1、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。預設值為 UTF-8。使用 quote 和 fieldDelimiter 屬性的值分割原始的二進位資料後，BigQuery 會將資料解碼。
preserveAsciiControlCharacters

boolean

(選用步驟) 指出是否保留內嵌的 ASCII 控制字元 (ASCII 表格中的前 32 個字元，從 '\x00' 到 '\x1F')。
nullMarker

string

(選用步驟) 指定代表 CSV 檔案中空值的字串。舉例來說，如果您指定「\N」，查詢 CSV 檔案時，BigQuery 會將「\N」解譯為空值。預設值為空字串。如果將這個屬性設為自訂值，當 STRING 與 BYTE 以外的所有資料類型出現空字串時，BigQuery 會擲回錯誤。BigQuery 會將 STRING 與 BYTE 資料欄的空字串解譯為空值。
nullMarkers[]

string

(選用步驟) CSV 檔案中以 SQL NULL 值表示的字串清單。

null_marker 和 null_markers 無法同時設定。如果設定 null_marker，就不得設定 null_markers。如果設定 null_markers，就不得設定 null_marker。如果同時設定 null_marker 和 null_markers，系統會擲回使用者錯誤。null_markers 中列出的任何字串 (包括空字串) 都會解讀為 SQL NULL。這項設定適用於所有欄類型。
sourceColumnMatch

string

(選用步驟) 控管策略，以便比對載入的資料欄與結構定義。如未設定，系統會根據架構的提供方式選擇適當的預設值。如果使用自動偵測，系統會依名稱比對資料欄。否則，系統會依位置比對欄。這是為了確保行為回溯相容。可接受的值如下：POSITION - 依位置比對。這項假設的前提是資料欄的排序方式與結構定義相同。NAME - 依名稱比對。這會將標題列讀取為資料欄名稱，並重新排序資料欄，以符合結構定義中的欄位名稱。
JSON 表示法 
{
  "encoding": string
}
欄位
encoding

string

(選用步驟) 資料的字元編碼。支援的值為 UTF-8、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。預設值為 UTF-8。
JSON 表示法 
{
  "columnFamilies": [
    {
      object (BigtableColumnFamily)
    }
  ],
  "ignoreUnspecifiedColumnFamilies": boolean,
  "readRowkeyAsString": boolean,
  "outputColumnFamiliesAsJson": boolean
}
欄位
columnFamilies[]

object (BigtableColumnFamily)

(選用步驟) 要在資料表結構定義中公開的資料欄系列清單，以及這些資料欄系列的類型。這份清單會限制查詢中可參照的資料欄系列，並指定其值類型。您可以使用這份清單執行類型轉換，詳情請參閱「type」欄位。如果將這份清單留空，資料表結構定義中就會包含所有資料欄系列，且所有資料欄系列的值會當做 BYTES 讀取。查詢期間，系統只會從 Bigtable 讀取查詢中參照的資料欄系列。
ignoreUnspecifiedColumnFamilies

boolean

(選用步驟) 如果欄位為 true，則資料表結構定義不會顯示 columnFamilies 清單中未指定的資料欄系列。如果沒有，則會與 BYTES 類型值一併讀取。預設值為 false。
readRowkeyAsString

boolean

(選用步驟) 如果欄位為 true，系統便會讀取 rowkey 資料欄系列，並將其轉換為字串。如果沒有，則會與 BYTES 類型值一併讀取，且使用者必須視需要手動以 CAST 轉換。預設值為 false。
outputColumnFamiliesAsJson

boolean

(選用步驟) 如果欄位為 true，則每個資料欄系列都會讀取為單一 JSON 欄。否則會讀取為含有時間戳記/值元組的重複儲存格結構。預設值為 false。
JSON 表示法 
{
  "familyId": string,
  "type": string,
  "encoding": string,
  "columns": [
    {
      object (BigtableColumn)
    }
  ],
  "onlyReadLatest": boolean,
  "protoConfig": {
    object (BigtableProtoConfig)
  }
}
欄位
familyId

string

資料欄系列的 ID。
type

string

(選用步驟) 要轉換這個資料欄系列中儲存格值的類型。使用 BINARY 編碼值時，這些值應使用 HBase Bytes.toBytes 函式編碼。允許使用下列 BigQuery 類型 (區分大小寫)：

  • BYTES
  • STRING
  • INTEGER
  • FLOAT
  • BOOLEAN
  • JSON

預設類型為 BYTES。如要覆寫特定資料欄的設定，請在「columns」中列出該資料欄，並指定其類型。
encoding

string

(選用步驟) 如果類型不是 STRING，值的編碼方式。可接受的編碼值如下：TEXT - 表示值為英數文字字串。BINARY - 表示值是使用 HBase Bytes.toBytes 系列函式編碼。PROTO_BINARY - 表示值是使用序列化 proto 訊息編碼。這項功能只能搭配 JSON 類型使用。如要覆寫特定資料欄的編碼，請在「columns」中列出該資料欄，並指定編碼。
columns[]

object (BigtableColumn)

(選用步驟) 資料欄清單，應以個別欄位形式公開，而非 (資料欄名稱、值) 配對清單。凡是限定詞與這份清單中限定詞相符的欄，都可以做為 <family field name>.<column field name> 存取。其他資料欄可透過 <family field name>.Column 欄位以清單形式存取。
onlyReadLatest

boolean

(選用步驟) 如果設定這個選項，系統只會顯示這個資料欄系列中所有資料欄的最新值。如要覆寫特定資料欄的設定，請在「columns」中列出該資料欄，並為該資料欄指定不同的設定。
protoConfig

object (BigtableProtoConfig)

(選用步驟) Protobuf 專用設定，僅在編碼為 PROTO_BINARY 時生效。
JSON 表示法 
{
  "qualifierEncoded": string,
  "qualifierString": string,
  "fieldName": string,
  "type": string,
  "encoding": string,
  "onlyReadLatest": boolean,
  "protoConfig": {
    object (BigtableProtoConfig)
  }
}
欄位
qualifierEncoded

string (BytesValue format)

[必要] 資料欄的限定詞。具有這個確切限定詞的父項資料欄系列中的資料欄，會顯示為 <family field name>.<column field name> 欄位。如果限定符是有效的 UTF-8 字串，則可在 qualifier_string 欄位中指定。否則，必須將 base-64 編碼值設為 qualifier_encoded。資料欄欄位名稱與資料欄限定符相同。不過，如果限定符不是有效的 BigQuery 欄位 ID (即不符合 [a-zA-Z][a-zA-Z0-9_]*)，則必須以 field_name 提供有效的 ID。
qualifierString

string

限定字串。
fieldName

string

(選用步驟) 如果限定符不是有效的 BigQuery 欄位 ID (即不符合 [a-zA-Z][a-zA-Z0-9_]*)，則必須提供有效的 ID 做為資料欄欄位名稱，並在查詢中做為欄位名稱。
type

string

(選用步驟) 要轉換這個資料欄中儲存格值的類型。使用 BINARY 編碼值時，這些值應使用 HBase Bytes.toBytes 函式編碼。允許使用下列 BigQuery 類型 (區分大小寫)：

  • BYTES
  • STRING
  • INTEGER
  • FLOAT
  • BOOLEAN
  • JSON

預設類型為 BYTES。也可以在資料欄系列層級設定「type」。不過，如果兩個層級都設定了「類型」，系統會優先採用這個層級的設定。
encoding

string

(選用步驟) 如果類型不是 STRING，值的編碼方式。可接受的編碼值如下：TEXT - 表示值為英數文字字串。BINARY - 表示值是使用 HBase Bytes.toBytes 系列函式編碼。PROTO_BINARY - 表示值是使用序列化 proto 訊息編碼。這項功能只能搭配 JSON 類型使用。您也可以在資料欄系列層級設定「encoding」。不過，如果兩個層級都設定了「編碼」，系統會優先採用這個層級的設定。
onlyReadLatest

boolean

(選用步驟) 如果設定這個值，系統只會顯示這個資料欄的最新值。您也可以在資料欄系列層級設定「onlyReadLatest」。不過，如果兩個層級都設定了「onlyReadLatest」，系統會優先採用這個層級的設定。
protoConfig

object (BigtableProtoConfig)

(選用步驟) Protobuf 專用設定，僅在編碼為 PROTO_BINARY 時生效。
JSON 表示法 
{
  "value": string
}
欄位
value

string (bytes format)

位元組值。

Base64 編碼字串。
JSON 表示法 
{
  "schemaBundleId": string,
  "protoMessageName": string
}
欄位
schemaBundleId

string

(選用步驟) 與這個 protobuf 相關聯的 Bigtable SchemaBundle 資源 ID。ID 應在父項資料表中參照，例如 foo，而非 projects/{project}/instances/{instance}/tables/{table}/schemaBundles/foo。請參閱更多有關 Bigtable SchemaBundle 的詳細資料。
protoMessageName

string

(選用步驟) protobuf 的完整 proto 訊息名稱。格式為「foo.bar.Message」。
JSON 表示法 
{
  "skipLeadingRows": string,
  "range": string
}
欄位
skipLeadingRows

string (Int64Value format)

(選用步驟) BigQuery 讀取資料時會略過的工作表頂端資料列數量。預設值為 0。如果您有應略過的標頭列，這個屬性就非常實用。開啟自動偵測功能後，系統會執行下列動作：* 未指定 skipLeadingRows - 自動偵測功能會嘗試偵測第一列中的標頭。如果系統未偵測到標題，就會將該列視為資料。否則系統會從第二列開始讀取資料。* skipLeadingRows 為 0 - 指示自動偵測沒有標題，且應從第一列開始讀取資料。* skipLeadingRows = N > 0 - Autodetect 會略過 N-1 個資料列，並嘗試偵測第 N 個資料列中的標題。如果系統未偵測到標題，就會直接略過第 N 列。否則系統會使用第 N 列擷取偵測到的結構定義的資料欄名稱。
range

string

(選用步驟) 要查詢的工作表範圍。僅在非空白時使用。一般格式：sheet_name!top_left_cell_id:bottom_right_cell_id 例如：sheet1!A1:B20
JSON 表示法 
{
  "mode": string,
  "sourceUriPrefix": string,
  "requirePartitionFilter": boolean,
  "fields": [
    string
  ]
}
欄位
mode

string

(選用步驟) 設定讀取資料時要使用的 Hive 分區模式。支援的模式如下：

  • AUTO：自動推論分區索引鍵名稱和類型。

  • STRINGS：自動推論分區索引鍵名稱。所有型別都是字串。

  • CUSTOM：分區索引鍵結構定義編碼在來源 URI 前置字串中。

並非所有儲存空間格式都支援 Hive 分區。如果要求對不支援的格式進行 Hive 分區，就會發生錯誤。目前支援的格式包括：JSON、CSV、ORC、Avro 和 Parquet。
sourceUriPrefix

string

(選用步驟) 要求偵測 Hive 分區時，所有來源 URI 都必須有共同前置字串。前置字串結尾必須緊接在分區鍵編碼開始之前。舉例來說，請考量下列資料配置的檔案：

gs://bucket/path_to_table/dt=2019-06-01/country=USA/id=7/file.avro

gs://bucket/path_to_table/dt=2019-05-31/country=CA/id=3/file.avro

如果要求使用 AUTO 或 STRINGS 偵測功能進行 Hive 分區，則通用前置字串可以是 gs://bucket/path_to_table 或 gs://bucket/path_to_table/。

結構定義須編碼入通用前置字串後方的位置，系統才能進行 CUSTOM 偵測作業。如為 CUSTOM 分區模式，請提供下列任一項：

  • gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:INTEGER}

  • gs://bucket/path_to_table/{dt:STRING}/{country:STRING}/{id:INTEGER}

  • gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:STRING}

都是有效的來源 URI 前置字串。
requirePartitionFilter

boolean

(選用步驟) 如果設為 true，查詢這個資料表時，必須指定可用於刪除分區的分區篩選器。

請注意，只有在建立永久外部資料表或查詢臨時外部資料表時，這個欄位才應為 true。

如果 Hive 分區負載明確將 require_partition_filter 設為 true，就會失敗。
fields[]

string

僅供輸出。如果是永久外部資料表，這個欄位會填入推斷順序的 Hive 分區鍵。您可以查看資料表結構定義 (其中會包含分區鍵)，推斷分區鍵的類型。並非所有 API 都會在輸出內容中填入這個欄位。舉例來說，Tables.Get 會填入這項資料，但 Tables.List 不會包含這個欄位。
JSON 表示法 
{
  "useAvroLogicalTypes": boolean
}
欄位
useAvroLogicalTypes

boolean

(選用步驟) 如果 sourceFormat 設為「AVRO」，表示是否將邏輯類型解讀為對應的 BigQuery 資料類型 (例如 TIMESTAMP)，而非使用原始類型 (例如 INTEGER)。
JSON 表示法 
{
  "enumAsString": boolean,
  "enableListInference": boolean,
  "mapTargetType": enum (MapTargetType)
}
欄位
enumAsString

boolean

(選用步驟) 指出是否要預設將 Parquet ENUM 邏輯型別推斷為 STRING，而非 BYTES。
enableListInference

boolean

(選用步驟) 指出是否要專為 Parquet LIST 邏輯型別使用結構定義推論。
mapTargetType

enum (MapTargetType)

(選用步驟) 指出如何表示 Parquet 地圖 (如有)。
JSON 表示法 
{
  "connectionId": string,
  "storageUri": string,
  "fileFormat": enum (FileFormat),
  "tableFormat": enum (TableFormat)
}
欄位
connectionId

string

(選用步驟) 這個連線會指定用於讀取及寫入外部儲存空間 (例如 Cloud Storage) 的憑證。connection_id 的格式可以是 {project}.{location}.{connection_id} 或 `projects/{project}/locations/{location}/connections/{connection_id}"。
storageUri

string

(選用步驟) 儲存資料表的外部資料夾完整路徑前置字元。不允許使用「*」萬用字元。URI 的格式應為 gs://bucket/path_to_table/
fileFormat

enum (FileFormat)

(選用步驟) 儲存資料表資料的檔案格式。
tableFormat

enum (TableFormat)

(選用步驟) 中繼資料快照的儲存表格格式。
JSON 表示法 
{
  "estimatedBytes": string,
  "estimatedRows": string,
  "oldestEntryTime": string
}
欄位
estimatedBytes

string

僅供輸出。串流緩衝區中目前位元組數的下限估計值。
estimatedRows

string

僅供輸出。串流緩衝區中目前資料列數量的下限估計值。
oldestEntryTime

string (uint64 format)

僅供輸出。如果串流緩衝區可用，則包含串流緩衝區中最舊項目的時間戳記，以紀元後毫秒為單位。
JSON 表示法 
{
  "kmsKeyName": string
}
欄位
kmsKeyName

string

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

object (TableReference)

這是必要旗標，說明已建立快照的資料表 ID 的參照。
snapshotTime

string (Timestamp format)

這是必要旗標，基礎資料表建立快照的時間。系統會以 RFC3339 格式，在 JSON 回應中回報這個值。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
JSON 表示法 
{
  "baseTableReference": {
    object (TableReference)
  },
  "cloneTime": string
}
欄位
baseTableReference

object (TableReference)

這是必要旗標，說明複製資料表 ID 的參照。
cloneTime

string (Timestamp format)

這是必要旗標，複製基礎資料表的時間。系統會以 RFC3339 格式，在 JSON 回應中回報這個值。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
JSON 表示法 
{
  "type": enum (RestrictionType)
}
欄位
type

enum (RestrictionType)

僅供輸出。指定資料集/表格限制類型。
JSON 表示法 
{
  "primaryKey": {
    object (PrimaryKey)
  },
  "foreignKeys": [
    {
      object (ForeignKey)
    }
  ]
}
欄位
primaryKey

object (PrimaryKey)

(選用步驟) 代表資料表資料欄的主鍵限制。只有在資料表有主鍵時才會顯示。未強制執行主要金鑰。
foreignKeys[]

object (ForeignKey)

(選用步驟) 只有在資料表有外來鍵時才會顯示。系統不會強制執行外鍵。
JSON 表示法 
{
  "columns": [
    string
  ]
}
欄位
columns[]

string

這是必要旗標，組成主鍵限制的資料欄。
JSON 表示法 
{
  "name": string,
  "referencedTable": {
    object (TableReference)
  },
  "columnReferences": [
    {
      object (ColumnReference)
    }
  ]
}
欄位
name

string

(選用步驟) 只有在外鍵限制條件已命名時才設定。
referencedTable

object (TableReference)

這是必要旗標，保存主鍵的資料表，並由這個外鍵參照。
columnReferences[]

object (ColumnReference)

這是必要旗標，組成外鍵的資料欄。
JSON 表示法 
{
  "referencingColumn": string,
  "referencedColumn": string
}
欄位
referencingColumn

string

這是必要旗標，組成外鍵的資料欄。
referencedColumn

string

這是必要旗標，參照欄參照的主鍵中的資料欄。
JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string
JSON 表示法 
{
  "sourceTable": {
    object (TableReference)
  },
  "replicationIntervalMs": string,
  "replicatedSourceLastRefreshTime": string,
  "replicationStatus": enum (ReplicationStatus),
  "replicationError": {
    object (ErrorProto)
  }
}
欄位
sourceTable

object (TableReference)

這是必要旗標，要複製的來源資料表參照。
replicationIntervalMs

string (int64 format)

(選用步驟) 指定輪詢來源資料表更新的間隔。這個欄位為選填。如未指定，系統會套用預設的複製間隔。
replicatedSourceLastRefreshTime

string (int64 format)

(選用步驟) 僅供輸出。如果來源是具體化檢視區塊，這個欄位會指出來源的上次重新整理時間。
replicationStatus

enum (ReplicationStatus)

(選用步驟) 僅供輸出。已設定複製作業的複製狀態。
replicationError

object (ErrorProto)

(選用步驟) 僅供輸出。複製錯誤，導致系統永久停止複製資料表。
JSON 表示法 
{
  "parameters": {
    string: string,
    ...
  },
  "storageDescriptor": {
    object (StorageDescriptor)
  },
  "connectionId": string
}
欄位
parameters

map (key: string, value: string)

(選用步驟) 定義開放原始碼表格參數和屬性的鍵/值組合對應。對應至 Hive 中繼存放區資料表參數。大小上限為 4 MiB。

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

object (StorageDescriptor)

(選用步驟) 儲存空間描述元，內含這個資料表的實體儲存空間相關資訊。
connectionId

string

(選用步驟) 連線 ID，用於指定讀取外部儲存空間 (例如 Azure Blob、Cloud Storage 或 Amazon S3) 時要使用的憑證。您需要這個連線，才能從 BigQuery 讀取開放原始碼資料表。connection_id 格式必須是 <project_id>.<location_id>.<connection_id> 或 projects/<project_id>/locations/<location_id>/connections/<connection_id>。
JSON 表示法 
{
  "key": string,
  "value": string
}
欄位
key

string
value

string
JSON 表示法 
{
  "locationUri": string,
  "inputFormat": string,
  "outputFormat": string,
  "serdeInfo": {
    object (SerDeInfo)
  }
}
欄位
locationUri

string

(選用步驟) 資料表的實際位置 (例如 gs://spark-dataproc-data/pangea-data/case_sensitive/ 或 gs://spark-dataproc-data/pangea-data/*)。長度上限為 2056 個位元組。
inputFormat

string

(選用步驟) 指定 InputFormat 的完整類別名稱 (例如「org.apache.hadoop.hive.ql.io.orc.OrcInputFormat」)。長度上限為 128 個字元。
outputFormat

string

(選用步驟) 指定 OutputFormat 的完整類別名稱 (例如「org.apache.hadoop.hive.ql.io.orc.OrcOutputFormat」)。長度上限為 128 個字元。
serdeInfo

object (SerDeInfo)

(選用步驟) 序列化器和還原序列化器資訊。
JSON 表示法 
{
  "name": string,
  "serializationLibrary": string,
  "parameters": {
    string: string,
    ...
  }
}
欄位
name

string

(選用步驟) SerDe 的名稱。長度上限為 256 個半形字元。
serializationLibrary

string

這是必要旗標，指定序列化程式庫的完整類別名稱，該程式庫負責在資料表表示法與基礎低階輸入和輸出格式結構之間轉換資料。長度上限為 256 個半形字元。
parameters

map (key: string, value: string)

(選用步驟) 定義序列化程式庫初始化參數的鍵/值組合。大小上限為 10 KiB。

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

string
value

string

工具註解

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