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

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 核心的 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)

將資料集宣告為資料表單資料來源。

僅適用於 /definitions 目錄。

範例：

// definitions/file.js

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

IActionConfig

定義套用至 SQL 工作流程動作的 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`
	資料表、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 為基礎的篩選器。

IColumnsDescriptor

說明表格中的欄。

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

declaration 動作類型的設定選項。

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

IDependenciesConfig

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

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

IDocumentableConfig

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

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

INamedConfig

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

`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 屬性。

以下程式碼範例顯示在工作流程設定中使用 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，系統就會建立具體化檢視表。
`protected`	`boolean`
	僅適用於 `incremental` 表格類型。如果設為 true，執行此動作時會忽略 `full-refresh` 選項。這項功能對於以暫時性資料建立的表格非常實用，可用於驗證歷來資料不會遺失。
`schema`	`string`
	用於建立此動作輸出的結構定義 (BigQuery 資料集)。
`tags`	`string[]`
	套用至此動作的使用者定義標記清單。
`type`	`TableType`
	資料表類型。
`uniqueKey`	`string[]`
	增量資料表合併條件的不重複鍵。如果已設定，系統會更新符合唯一索引鍵的記錄，而不會插入新資料列。

ITableContext

在評估可使用內容的 SQL 程式碼 (例如 SQLX 檔案內)，或使用 Contextable 參數搭配 Dataform 核心時，可使用內容方法。

`incremental`	`() => boolean`
	如果目前的上下文指出資料表將以遞增方式建構，則傳回「是」。
`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

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

`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 核心參考資料