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

defaultLocation

defaultLocation プロパティは、デフォルトの BigQuery データセットのロケーションを指定します。Dataform はこのロケーションを使用してコードを処理し、結果を保存します。この処理ロケーションは、BigQuery データセットのロケーションと一致する必要があります。ただし、Dataform リポジトリのロケーションと一致する必要はありません。

defaultLocation プロパティを設定しない場合、Dataform は SQL クエリが参照するデータセットに基づいてロケーションを決定します。これは次のように機能します。

• クエリが同じロケーションのデータセットを参照している場合、Dataform はそのロケーションを使用します。
• クエリが 2 つ以上の異なるロケーションのデータセットを参照している場合、エラーが発生します。この制限の詳細については、クロスリージョン データセット レプリケーションをご覧ください。
• クエリがデータセットを参照していない場合、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
	テーブル、ビュー、マテリアライズド ビューの 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

ワークフロー アクションの依存関係を定義します。

dependencies	Resolvable| Resolvable[]
	このアクションの 1 つ以上の明示的な依存関係。依存関係のアクションは、依存アクションの前に実行されます。 通常、ほとんどの依存関係は 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 プロパティにアクセスできます。

次のコードサンプルは、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 に設定すると、マテリアライズド ビューが作成されます。
onSchemaChange	onSchemaChange
	テーブルタイプが incremental の場合にのみ有効です。 Dataform が SELECT クエリをチェックして、列が追加または削除されたかどうかを判断した後に実行されるアクション。 この機能はプレビュー版です。
protected	boolean
	incremental テーブルタイプでのみ使用できます。 true に設定した場合、このアクションを実行しても full-refresh オプションは無視されます。 これは、一時データから構築されるテーブルで、履歴データが失われないことを確認するのに役立ちます。
schema	string
	このアクションの出力を作成するスキーマ（BigQuery データセット）。
tags	string[]
	このアクションに適用されるユーザー定義のタグのリスト。
type	TableType
	テーブルのタイプ。
uniqueKey	string[]
	増分テーブルのマージ条件の一意のキー。 構成された場合、新しい行を挿入する代わりに、一致する一意のキーを持つレコードが更新されます。

ITableContext

コンテキスト メソッドは、SQLX ファイル内など、コンテキスト可能な SQL コードを評価する場合や、Dataform コアで 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" の値に個別の引数を使用して呼び出すこともできます。 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

ワークフロー アクションのターゲット データベースとスキーマを定義します。

database	string
	このアクションの出力を作成する必要があるデータベース。BigQuery に設定する必要があります。
schema	string
	このアクションの出力を作成する必要があるスキーマ。

onSchemaChange

プレビュー版

このプロダクトまたは機能は、 サービス固有の規約の対象となります。 pre-GA のプロダクトと機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: フィードバックやサポートのリクエストについては、[e-mail] までお問い合わせください。

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

Resolvable

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

string | ITarget

TableType

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

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

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

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