Dataform コアのリファレンス

このドキュメントでは、Dataform コアのメソッド、プロパティ、構成オプションについて説明します。Dataform コアは、SQLX ファイルと JavaScript ファイルで使用できます。

assert()

assert (name: string, query?: AContextable)

コンパイルされたグラフに Dataform アサーションを追加します。

/definitions ディレクトリでのみ使用できます。

例:

// definitions/file.js

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

CommonContext

コンテキストメソッドは、SQLX ファイル内など、コンテキスト可能な SQL コードを評価する場合や、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"` の値に個別の引数を使用して呼び出すこともできます。 2 つの値のみを指定すると、デフォルトのデータベースが使用され、値は `"schema"` および `"name"` として解釈されます。値を 1 つだけ指定した場合は、デフォルトのデータベースとスキーマが使用され、指定された値は「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

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

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`
	テーブル、ビュー、マテリアライズドビューの Key-Value ペア。 `partitionExpirationDays` などの一部のオプションには、専用の型 / 有効性チェックフィールドがあります。このようなオプションに対して、専用フィールドを使用します。文字列値は、二重引用符で囲む必要があります（例: `additionalOptions: {numeric_option: "5"`、`string_option: '"string-value"'}`）。オプション名に特殊文字が含まれている場合は、名前を引用符で囲みます（例: `additionalOptions: { "option-name": "value" }`）。
`clusterBy`	`string[]`
	クラスタ分割のパーティション分割に使用するキー。
`labels`
	BigQuery ラベルの Key-Value ペア。ラベル名にハイフンなどの特殊文字が含まれている場合は、名前を引用符で囲みます（例: `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[]`
	このアクションの明示的な依存関係が 1 つ以上ある。依存関係のアクションは、依存アクションの前に実行されます。通常は設定されません。ほとんどの依存関係は、`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 プロパティにアクセスできます。

次のコードサンプルは、SQL プロパティファイルの SELECT ステートメントでアクセスされる、projectConfig.vars プロパティを持つワークフロー設定に設定された myVariableName カスタムコンパイル変数を示しています。

  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 ポリシータグの完全な識別子。BigQuery ポリシータグの完全な識別子には、プロジェクト名、ロケーション、分類が含まれます。例: `"projects/1/locations/eu/taxonomies/2/policyTags/3"` BigQuery では 1 列あたり 1 つのタグがサポートされています。
`columns`	`IColumnsDescriptor`
	構造体、オブジェクト、レコード内の列の説明。
`description`	`string`
	構造体、オブジェクト、レコードの説明。

ITableAssertions

テーブル定義の一部としてアサーションを作成するためのオプション。

`nonNull`	`string \| string[]`
	`NULL` にできない列。設定されている場合、これらの列に `NULL` 値が格納されている行がある場合、対応するアサーションは失敗します。
`rowConditions`	`string[]`
	テーブル内のすべての行で true になる一般的な条件。設定されている場合、いずれかの行がこれらの条件に違反すると、対応するアサーションは失敗します。
`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

`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"` の値に個別の引数を使用して呼び出すこともできます。 2 つの値のみを指定すると、デフォルトのデータベースが使用され、値は `"schema"` および `"name"` として解釈されます。値を 1 つだけ指定した場合は、デフォルトのデータベーススキーマが使用され、指定された値は「name」として解釈されます。 `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	`ref` に似ていますが、依存関係を追加する代わりに、作成された参照を「from」式などで SQL で使用できるように解決します。
`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");

Resolvable

resolvable は、string としてのテーブルの名前か、そのリレーションへのフルパスを記述するオブジェクトのいずれかです。

string | ITarget

TableType

サポートされているテーブルアクションのタイプ。

view タイプのテーブルは、ビューとして作成されます。

table タイプのテーブルは、テーブルとして作成されます。

incremental 型のテーブルには、where 句を含める必要があります。詳細については、増分テーブルを構成するをご覧ください。