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

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"})

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`
	這是必要旗標，要使用的預設 BigQuery 位置。如要進一步瞭解 BigQuery 位置，請參閱 https://cloud.google.com/bigquery/docs/locations。
`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 屬性。

下列程式碼範例顯示在工作流程設定中設定的 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 中的 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，系統就會建立具體化檢視表。
`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`
	應建立此動作輸出的結構定義。

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()

IActionConfig

IAssertionConfig

IBigQueryOptions

IColumnsDescriptor

IDeclarationConfig

IDependenciesConfig

IDocumentableConfig

INamedConfig

IOperationConfig

IProjectConfig

IRecordDescriptor

ITableAssertions

ITableConfig

ITableContext

ITarget

ITargetableConfig

operate()

publish()

可解決

TableType

Dataform 核心參考資料