このページは Cloud Translation API によって翻訳されました。

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

`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

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 句を含める必要があります。詳細については、増分テーブルを構成するをご覧ください。

Dataform コアのリファレンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

assert()

CommonContext

Contextable

Dataform

declare()

defaultLocation

IActionConfig

IAssertionConfig

IBigQueryOptions

IColumnsDescriptor

IDeclarationConfig

IDependenciesConfig

IDocumentableConfig

INamedConfig

IOperationConfig

IProjectConfig

IRecordDescriptor

ITableAssertions

ITableConfig

ITableContext

ITarget

ITargetableConfig

onSchemaChange

operate()

publish()

Resolvable

TableType

Dataform コアのリファレンス