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
このアクションが密閉型かどうかを宣言します。すべての依存関係が明示的に宣言されている場合、アクションは密閉型です。

このアクションが、依存関係として宣言されていないソースからのデータに依存している場合は、hermeticfalse に設定します。 それ以外の場合は 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
このアクションが密閉型かどうかを宣言します。すべての依存関係が明示的に宣言されている場合、アクションは密閉型です。

このアクションが、依存関係として宣言されていないソースからのデータに依存している場合は、hermeticfalse に設定します。 それ以外の場合は 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 APIprojects.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 アクションの構成オプション(tableviewincremental のテーブルタイプを含む)。

IActionConfigIDependenciesConfigIDocumentableConfigINamedConfigITargetableConfigを拡張します。

assertions ITableAssertions
テーブルで実行するアサーション。

構成されている場合、関連するアサーションが自動的に作成され、このテーブルの依存関係として実行されます。

bigquery IBigQueryOptions
BigQuery 固有のウェアハウス オプション。
columns IColumnsDescriptor
テーブル内の列の説明。
database string
このアクションの出力を作成するデータベース(Google Cloud プロジェクト ID)。
description string
テーブルの説明。
disabled boolean
true に設定した場合、このアクションは実行されません。 アクションは引き続き依存できます。 機能しない操作を一時的に無効にするのに役立ちます。
hermetic boolean
このアクションが密閉型かどうかを宣言します。すべての依存関係が明示的に宣言されている場合、アクションは密閉型です。

このアクションが、依存関係として宣言されていないソースからのデータに依存している場合は、hermeticfalse に設定します。 それ以外の場合は true に設定します。

materialized boolean
テーブルタイプが view の場合にのみ有効です。

true に設定すると、マテリアライズド ビューが作成されます。

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

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