Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Dataform 核心參考資料

本文說明 Dataform 核心的方法、屬性和設定選項。您可以在 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`
	table、view 和 materialized view 選項的鍵/值組合。部分選項 (例如 `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`
	Iceberg 代管資料表的 Apache Iceberg 專屬選項。

IIcebergOptions

Iceberg 代管資料表的 Apache Iceberg 專屬選項。

`connection`	`string`
	選用。Cloud Storage 連線的資源名稱，可提供從外部儲存空間讀取及寫入資料的憑證。格式設定方式如下： `PROJECT_ID.LOCATION.CONNECTION_ID` 替換下列值： `PROJECT_ID`： Google Cloud 專案 ID `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`
	選用。Apache Iceberg 代管資料表的工作流程層級預設值。包含下列欄位： `bucketName`：選用。Cloud Storage bucket 的預設名稱。 `tableFolderRoot`：選用。Cloud Storage bucket 中第一層資料夾的預設名稱。 `tableFolderSubpath`：選用。`tableFolderRoot` 內子資料夾的預設名稱。詳情請參閱「設定 Iceberg 表格的工作流程層級預設值」。
`preserveGovernanceControls`	`boolean`
	選用。如果設為 `true`，Dataform 會自動在工作流程執行期間，為存放區中的所有資料表保留現有的 BigQuery 資料政策和資料治理標記 (預先發布版)。
`warehouse`	`string`
	這是必要旗標，必須設為 `bigquery`。

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

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

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

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

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

如要進一步瞭解如何覆寫個別編譯結果的專案設定，請參閱 Dataform API 中的 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`查詢後執行的動作，判斷是否新增或移除資料欄。這項功能為預先發布版。
`preserveGovernanceControls`	`boolean`
	選用。如果設為 `true`，Dataform 會在完整重新整理期間，重新建立資料表、檢視表或漸進式資料表時，備份並重新套用現有的 BigQuery 資料政策和資料治理標記 (預先發布版)。覆寫在 `workflow_settings.yaml` 中設定的工作流程層級預設值。
`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 核心參考資料