Dataform 核心參考資料

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

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 為基礎的篩選器，用於套用增量更新時。

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
(選用步驟) 應加到所有資料表名稱的前置字串。
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 值。移除原始結構定義中的資料欄，但這些資料欄現在已從目前的查詢中消失。

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 子句。 詳情請參閱「設定遞增資料表」。