本頁面由 Cloud Translation API 翻譯而成。

Dataform 核心參考資料

本文說明 Dataform Core 的方法、屬性和設定選項。您可以在 SQLX 和 JavaScript 檔案中使用 Dataform 核心。

assert()

assert (name: string, query?: AContextable)

將 Dataform 判斷結果新增至已編譯的圖表。

僅適用於 /definitions 目錄。

範例：

// definitions/file.js

assert("name").query(ctx => "select 1");

CommonContext

評估可設定環境的 SQL 程式碼時 (例如在 SQLX 檔案中)，或使用 Dataform Core 的 Contextable 引數時，即可使用環境方法。

`database`	`() => string`
	傳回這個資料集的資料庫 (如適用)。
`name`	`() => string`
	傳回這個資料表的名稱。
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	參照另一個動作，將其新增為這個動作的依附元件，並傳回可在 `from` 運算式中使用的有效 SQL。這個函式可使用 `Resolvable` 物件呼叫，例如： `${ref({ name: "name", schema: "schema", database: "database" })}` 您也可以使用 `"database"`、`"schema"` 和 `"name"` 值的個別引數呼叫此函式。如果只提供兩個值，系統會使用預設資料庫，並將這些值解讀為 `"schema"` 和 `"name"`。如果只提供一個值，系統會使用預設資料庫和結構定義，並將提供的值解讀為 `"name"`。 `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	與 `ref` 類似，但不會將參照的動作新增為這個動作的依附元件。
`self`	`() => string`
	等同於 `resolve(name())`。傳回有效的 SQL 字串，可用於參照這個動作產生的資料表。
`schema`	`() => string`
	傳回這個資料集的結構定義。

Contextable

可提供背景資訊的引數可以傳遞其泛型型別的純值 T，也可以傳遞函式，並使用這類作業的背景資訊物件呼叫該函式。

T | (ctx: Context) => T

Dataform

包含 IProjectConfig 物件的全域變數。取得 IProjectConfig 屬性時必須提供，例如：

dataform.projectConfig.vars.myVariableName === "myVariableValue"

declare()

declare (dataset: dataform.ITarget)

將資料集宣告為 Dataform 資料來源。

僅適用於 /definitions 目錄。

範例：

// definitions/file.js

declare({name: "a-declaration"})

defaultLocation

defaultLocation 屬性會指定預設的 BigQuery 資料集位置。Dataform 會使用這個位置處理程式碼並儲存結果。這個處理位置必須與 BigQuery 資料集的位置相符。不過，這項設定不需要與 Dataform 存放區位置相符。

如未設定 defaultLocation 屬性，Dataform 會根據 SQL 查詢參照的資料集判斷位置。運作方式如下：

如果查詢參照相同位置的資料集，Dataform 會使用該位置。
如果查詢參照來自兩個以上不同位置的資料集，就會發生錯誤。如要進一步瞭解這項限制，請參閱「跨區域資料集複製」。
如果查詢未參照任何資料集，Dataform 的預設位置為 US 多地區。如要選擇其他位置，請設定 defaultLocation 屬性。或者，在查詢中使用 @@location 系統變數。

詳情請參閱「指定位置」。

IActionConfig

定義套用至工作流程動作的 Dataform 標記和依附元件。

`tags`	`string[]`
	請列出要套用到動作的使用者定義標記。
`dependencies`	`Resolvable\| Resolvable[]`
	動作的依附元件。
`disabled`	`boolean`
	如果設為 true，系統不會執行這項動作。不過，動作仍可依附於此。適合用來暫時關閉失效的動作。

IAssertionConfig

assertion 動作類型的設定選項。

`database`	`string`
	要在其中為這項判斷建立對應檢視區塊的資料庫 (Google Cloud 專案 ID)。
`description`	`string`
	這項判斷的說明。
`disabled`	`boolean`
	如果設為 `true`，系統不會執行這項動作。但仍可依據該動作。適合用來暫時關閉損壞的動作。
`hermetic`	`boolean`
	宣告這個動作是否為密封動作。如果動作的所有依附元件都已明確宣告，該動作就是密封動作。如果這項動作依附於未宣告為依附元件的來源資料，請將 `hermetic` 設為 `false`。否則請設為 `true`。
`schema`	`string`
	要為這項判斷建立對應檢視區塊的結構定義 (BigQuery 資料集)。
`tags`	`string[]`
	套用至這項動作的使用者定義標記清單。

IBigQueryOptions

BigQuery 專屬的倉儲選項。

`additionalOptions`
	資料表、檢視畫面和具體化檢視畫面選項的鍵/值組合。部分選項 (例如 `partitionExpirationDays`) 設有專用的類型/效期檢查欄位。如要使用這類選項，請使用專用欄位。字串值必須以雙引號括住，例如： `additionalOptions: {numeric_option: "5"`、 `string_option: '"string-value"'}` 如果選項名稱含有特殊字元，請將名稱放在引號中，例如：`additionalOptions: { "option-name": "value" }`。
`clusterBy`	`string[]`
	用來叢集分區的鍵。
`labels`
	BigQuery 標籤的鍵/值組合。如果標籤名稱含有特殊字元 (例如連字號)，請加上引號，例如 `labels: { "label-name": "value" }.`
`partitionBy`	`string`
	用來分割資料表的索引鍵。通常是時間戳記或日期資料欄的名稱。
`partitionExpirationDays`	`number`
	BigQuery 在每個分區中儲存資料的天數。這項設定會套用至資料表中的所有分區，但系統會根據分區時間，分別計算每個分區的費用。
`requirePartitionFilter`	`boolean`
	宣告分區資料表是否需要 `WHERE` 子句述詞篩選器，以篩選分區資料欄。
`updatePartitionFilter`	`string`
	以 SQL 為基礎的篩選器，用於套用增量更新時。
`iceberg`	`IIcebergOptions`
	BigQuery 中 BigLake Iceberg 資料表的 Apache Iceberg 專屬選項。

IIcebergOptions

BigQuery 中 BigLake Iceberg 資料表的 Apache Iceberg 專屬選項。

`connection`	`string`
	(選用步驟) Cloud Storage 連線的資源名稱，可提供從外部儲存空間讀取及寫入資料的憑證。格式如下： `PROJECT_ID.LOCATION.CONNECTION_ID` 替換下列值： `PROJECT_ID`：專案 ID Google Cloud `LOCATION`：連線的位置名稱 `CONNECTION_ID`：連線的名稱或 ID `projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID` `DEFAULT` 預設值為 `DEFAULT`。詳情請參閱「預設連線總覽」。
`file_format`	`string`
	(選用步驟) 資料表資料的檔案格式。系統僅支援 `PARQUET`。預設值為 `PARQUET`。
`bucket_name`	`string`
	資料表或工作流程層級皆可。儲存資料表的 Cloud Storage bucket 名稱。您必須在資料表定義檔的 `config` 區塊中提供 `bucket_name`，或在 `workflow_settings.yaml` 檔案中設定工作流程層級的預設值。如果兩者皆未提供，編譯就會失敗。詳情請參閱「為 Iceberg 表格設定工作流程層級的預設值」。
`table_folder_root`	`string`
	(選用步驟) Cloud Storage bucket 內第一層資料夾的名稱，用於儲存資料表資料。如未設定這項屬性，Dataform 會使用 `workflow_settings.yaml` 中的工作流程層級預設值 (如有設定)。否則預設為 `_dataform`。
`table_folder_subpath`	`string`
	(選用步驟) `tableFolderRoot` 中的子資料夾。如未設定此屬性，Dataform 會使用 `workflow_settings.yaml` 中的工作流程層級預設值 (如有設定)。如果未設定屬性或工作流程層級預設值，子路徑預設為 `DATASET_NAME/TABLE_NAME`。

這些值會建構以下格式的 Cloud Storage URI： gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH。

IColumnsDescriptor

說明資料表中的資料欄。

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

declaration 動作類型的設定選項。

`columns`	`IColumnsDescriptor`
	資料表中的資料欄說明。
`database`	`string`
	要建立來源資料表的資料庫 (Google Cloud 專案 ID) 存在。
`description`	`string`
	資料表的說明。
`schema`	`string`
	來源資料表所在的結構定義 (BigQuery 資料集)。

IDependenciesConfig

定義工作流程動作的依附元件。

`dependencies`	`Resolvable\| Resolvable[]`
	這項動作的一或多個明確依附元件。依附元件動作會在依附動作之前執行。通常會保持未設定狀態，因為大多數依附元件都是使用 `ref` 函式時的副產品。
`hermetic`	`boolean`
	聲明這個動作是否為密封動作。如果動作明確宣告了所有依附元件，就是密封動作。如果這項動作依附於未宣告為依附元件的來源資料，則應將 `hermetic` 明確設為 `false`。否則，如果這項動作只依附於明確宣告的依附元件資料，則應設為 `true`。

IDocumentableConfig

定義資料集及其資料欄的說明。

`columns`	`IColumnsDescriptor`
	資料集內資料欄的說明。
`description`	`string`
	資料集的說明。

INamedConfig

定義工作流程動作的類型和名稱。

`type`	`string`
	動作類型。
`name`	`string`
	動作的名稱。

IOperationConfig

operations 動作類型的設定選項。

`columns`	`IColumnsDescriptor`
	資料表中的資料欄說明。
`database`	`string`
	要在其中建立這項動作輸出內容的資料庫 (Google Cloud 專案 ID)。
`description`	`string`
	資料表的說明。
`disabled`	`boolean`
	如果設為 `true`，系統不會執行這項動作。但仍可依賴該動作。可用於暫時關閉失效的動作。
`hasOutput`	`boolean`
	宣告此 `operations` 動作會建立可使用 `ref` 函式參照的資料表。如果設為 `true`，這項動作會使用 `self()` 內容函式，建立具有設定名稱的表格。例如： `create or replace table ${self()} as select ...`
`hermetic`	`boolean`
	宣告這個動作是否為密封動作。如果動作的所有依附元件都已明確宣告，該動作就是密封動作。如果這項動作依附於未宣告為依附元件的來源資料，請將 `hermetic` 設為 `false`。否則請設為 `true`。
`schema`	`string`
	要建立這項動作輸出內容的結構定義 (BigQuery 資料集)。
`tags`	`string[]`
	套用至這項動作的使用者定義標記清單。

IProjectConfig

包含 Dataform 存放區的編譯設定。

`defaultDatabase`	`string`
	這是必要旗標，預設資料庫 (Google Cloud 專案 ID)。
`defaultSchema`	`string`
	這是必要旗標，預設結構定義 (BigQuery 資料集 ID)。
`defaultLocation`	`string`
	(選用步驟) Dataform 建立資料表的預設 BigQuery 位置。
`assertionSchema`	`string`
	這是必要旗標，斷言的預設結構定義 (BigQuery 資料集 ID)。
`vars`	`map (key: string, value: string)`
	(選用步驟) 編譯期間可供專案程式碼使用的使用者定義變數。這個物件中包含 `"key": value` 組合的清單。例如：`{ "name": "wrench", "mass": "1.3kg", "count": "3" }`。
`databaseSuffix`	`string`
	(選用步驟) 應附加至所有資料庫 (Google Cloud 專案 ID) 名稱的尾碼。
`schemaSuffix`	`string`
	(選用步驟) 應附加至所有結構定義 (BigQuery 資料集 ID) 名稱的後置字元。
`tablePrefix`	`string`
	(選用步驟) 應加到所有資料表名稱的前置字串。
`defaultIcebergConfig`	`object`
	(選用步驟) BigQuery 中 Apache Iceberg 專用 BigLake 資料表的工作流程層級預設值。包含下列欄位： `bucketName`：選用。Cloud Storage bucket 的預設名稱。 `tableFolderRoot`：選用。Cloud Storage bucket 內第一層資料夾的預設名稱。 `tableFolderSubpath`：選用。`tableFolderRoot` 內的子資料夾預設名稱。詳情請參閱「為 Iceberg 表格設定工作流程層級的預設值」。
`warehouse`	`string`
	這是必要旗標，必須設為 `bigquery`。

您可以在存放區層級設定工作流程設定中的 IProjectConfig 屬性。

您可以覆寫個別表格的 defaultSchema 和 defaultDatabase 屬性。

您可以在 SQLX 或 JavaScript 檔案的 SQL SELECT 陳述式中存取所有 IProjectConfig 屬性。

下列程式碼範例顯示在工作流程設定中，使用 projectConfig.vars 屬性設定的 myVariableName 自訂編譯變數，並在 SQLX 檔案的 SELECT 陳述式中存取：

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

如要進一步瞭解如何為個別編譯結果覆寫專案設定，請參閱 Dataform API 中的 projects.locations.repositories.compilationResults#CodeCompilationConfig REST 資源。

IRecordDescriptor

說明資料表中具有巢狀資料欄的結構體、物件或記錄。

`bigqueryPolicyTags`	`string \| string[]`
	套用至這個資料欄的 BigQuery 政策標記完整 ID。BigQuery 政策標記的完整 ID 包含專案名稱、位置和分類，例如：`"projects/1/locations/eu/taxonomies/2/policyTags/3"` BigQuery 支援每個資料欄一個標記。
`columns`	`IColumnsDescriptor`
	結構體、物件或記錄中的資料欄說明。
`description`	`string`
	結構體、物件或記錄的說明。

ITableAssertions

建立斷言的選項，做為資料表定義的一部分。

`nonNull`	`string \| string[]`
	絕不會是 `NULL` 的資料欄。如果設定此選項，且任何資料列含有這些資料欄的 `NULL` 值，對應的判斷就會失敗。
`rowConditions`	`string[]`
	一般條件，資料表中的所有資料列都應符合此條件。如果設定了條件，只要有任何資料列違反其中任一條件，對應的判斷就會失敗。
`uniqueKey`	`string \| string[]`
	構成資料表不重複索引鍵的資料欄。如果設定此條件，當表格中有多個資料列在所有這些資料欄中的值都相同時，產生的判斷就會失敗。
`uniqueKeys`	`[]`
	資料欄組合，每個組合都是資料表的唯一鍵索引。如果設定此項，當資料表中有多個資料列的唯一鍵資料欄值相同時，產生的判斷就會失敗。

ITableConfig

table 動作的設定選項，包括 table、view 和 incremental 資料表類型。

擴充 IActionConfig、IDependenciesConfig、IDocumentableConfig、INamedConfig 和 ITargetableConfig。

`assertions`	`ITableAssertions`
	要在資料表上執行的判斷。如果已設定，系統會自動建立相關的斷言，並以這個表格的依附元件形式執行。
`bigquery`	`IBigQueryOptions`
	BigQuery 專屬的倉儲選項。
`columns`	`IColumnsDescriptor`
	資料表內資料欄的說明。
`database`	`string`
	要在其中建立這項動作輸出內容的資料庫 (Google Cloud 專案 ID)。
`description`	`string`
	資料表的說明。
`disabled`	`boolean`
	如果設為 `true`，系統不會執行這項動作。但仍可依賴該動作。可用於暫時關閉損壞的動作。
`hermetic`	`boolean`
	宣告這個動作是否為密封動作。如果動作明確宣告了所有依附元件，就是密封動作。如果這項動作依附於未宣告為依附元件的來源資料，請將 `hermetic` 設為 `false`。否則請設為 `true`。
`materialized`	`boolean`
	只有在資料表類型為 `view` 時才有效。如果設為 True，系統就會建立具體化檢視表。
`onSchemaChange`	`onSchemaChange`
	只有在資料表類型為 `incremental` 時才有效。 Dataform 檢查查詢後執行的動作，判斷是否新增或移除資料欄。`SELECT` 這項功能為預先發布版。
`protected`	`boolean`
	僅適用於 `incremental` 表格類型。如果設為 true，執行這項動作時會忽略 `full-refresh` 選項。這項功能適用於以暫時性資料建構的表格，可驗證歷來資料是否從未遺失。
`schema`	`string`
	要建立這項動作輸出內容的結構定義 (BigQuery 資料集)。
`tags`	`string[]`
	套用至這項動作的使用者定義標記清單。
`type`	`TableType`
	資料表類型。
`uniqueKey`	`string[]`
	遞增資料表的合併條件專屬鍵。如果已設定，系統會更新具有相符不重複鍵的記錄，而不是插入新資料列。

ITableContext

評估可設定環境的 SQL 程式碼時 (例如在 SQLX 檔案中)，或使用 Dataform Core 的 Contextable 引數時，即可使用環境方法。

`incremental`	`() => boolean`
	如果目前的內容指出資料表會以遞增方式建構，則傳回 true。
`name`	`() => string`
	傳回這個資料表的完整名稱。
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	參照另一個動作，將其做為這個動作的依附元件加入，並傳回可在 from 運算式中使用的有效 SQL。這個函式可以使用 `Resolvable` 物件呼叫，例如： `${ref({ name: "name", schema: "schema", database: "database" })}` 您也可以使用 `"database"`、`"schema"` 和 `"name"` 值的個別引數呼叫這個函式。如果只提供兩個值，系統會使用預設資料庫，並將這些值解讀為 `"schema"` 和 `"name"`。如果只提供一個值，系統會使用預設資料庫結構定義，並將提供的值解讀為 `"name"`。 `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	與 `ref` 類似，但不是新增依附元件，而是解析提供的參照，以便在 SQL 中使用，例如在 `from` 運算式中。
`self`	`() => string`
	等同於 `resolve(name())`。傳回有效的 SQL 字串，可用於參照這個動作產生的資料表。
`when`	`(cond: boolean, trueCase: string, falseCase: string) => string`
	`if` 條件的簡寫。等同於 `cond ? trueCase : falseCase`。 `falseCase` 為選用欄位，預設值為空字串。

ITarget

BigQuery 中的資料表參照。

`database`	`string`
`name`	`string`
`schema`	`string`

ITargetableConfig

定義工作流程動作的目標資料庫和結構定義。

`database`	`string`
	應建立這項動作輸出內容的資料庫。必須設為 BigQuery。
`schema`	`string`
	應建立此動作輸出的結構定義。

onSchemaChange

設定 onSchemaChange 屬性後，Dataform 會檢查 SELECT 查詢，判斷是否新增或移除資料欄。接著，Dataform 會執行 onSchemaChange 屬性值指定的動作。您可以將動作設為下列其中一項：

IGNORE (預設)：忽略新增的資料欄，並針對缺少的資料欄顯示錯誤。如未設定 onSchemaChange，這是結構定義變更時的預設行為。
FAIL：如果 Dataform 偵測到任何結構定義變更，就會停止動作，有助於維持結構定義一致性。
EXTEND：將查詢中的新資料欄新增至累加資料表，並為先前的記錄新增 NULL 值。如果查詢中原始結構定義的資料欄遭到移除或遺失，系統就會顯示錯誤。您可以在執行階段使用這項設定，在增量資料表中新增資料欄。
SYNCHRONIZE：將查詢中的新資料欄新增至增量資料表，並為先前的記錄新增 NULL 值。移除原始結構定義中的資料欄，但這些資料欄現在已從目前的查詢中消失。

注意：SYNCHRONIZE 操作無法復原，且使用這個選項移除資料欄時，可能會遺失資料。
注意：系統不支援刪除已分割和叢集化的資料欄，因為刪除這些資料欄可能會造成負面影響。如果仍要刪除已分割或叢集化的資料欄，請使用 ALTER TABLE DROP COLUMN 陳述式處理。Dataform 不會執行檢查或驗證，防止在分區或叢集資料欄上執行 ALTER TABLE DROP COLUMN 陳述式。因此，如果捨棄這類資料欄，請謹慎操作，並留意可能造成的負面影響。

operate()

operate (name: string, queries?: Contextable)

定義 SQL 作業。

僅適用於 /definitions 目錄。

範例：

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

建立資料表或檢視區塊。

僅適用於 /definitions 目錄。

範例：

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

可解決

可解析的項目可以是資料表的名稱 (如 string)，也可以是描述關係完整路徑的物件。

string | ITarget

TableType

支援的資料表動作類型。

系統會將 view 類型的資料表建立為檢視區塊。

系統會將 table 類型的表格建立為資料表。

incremental 類型的資料表必須包含 where 子句。詳情請參閱「設定遞增資料表」。

Dataform 核心參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

assert()

CommonContext

Contextable

Dataform

declare()

defaultLocation

IActionConfig

IAssertionConfig

IBigQueryOptions

IIcebergOptions

IColumnsDescriptor

IDeclarationConfig

IDependenciesConfig

IDocumentableConfig

INamedConfig

IOperationConfig

IProjectConfig

IRecordDescriptor

ITableAssertions

ITableConfig

ITableContext

ITarget

ITargetableConfig

onSchemaChange

operate()

publish()

可解決

TableType

Dataform 核心參考資料