オープンソースの Dataform CLI を使用すると、Google Cloud の外部で Dataform コアをローカルで初期化、コンパイル、テスト、実行できます。
Dataform CLI は、アプリケーションのデフォルト認証情報(ADC)をサポートしています。ADC を使用すると、アプリケーション コードを変更することなく、ローカルでの開発環境や本番環境など、さまざまな環境のアプリケーションで認証情報を使用できるようになります。ADC を使用するには、まず ADC に認証情報を指定する必要があります。
始める前に
Dataform CLI をインストールする前に、NPM をインストールします。
Dataform CLI をインストールする
Dataform CLI をインストールするには、次のコマンドを実行します。
npm i -g @dataform/cli@^3.0.0-beta
Dataform プロジェクトを初期化する
新しい Dataform プロジェクトを初期化するには、プロジェクト ディレクトリ内で次のコマンドを実行します。
dataform init . PROJECT_NAME DEFAULT_LOCATION
以下を置き換えます。
- PROJECT_NAME: プロジェクトの名前。
- DEFAULT_LOCATION: Dataform が BigQuery データを書き込むリージョン。BigQuery のリージョンの詳細については、BigQuery のロケーションをご覧ください。
Dataform を更新する
Dataform フレームワークを更新するには、
workflow_settings.yaml
ファイルのdataformCoreVersion
を更新してから、NPM のインストールを再実行します。npm i
Dataform CLI を更新する
Dataform CLI ツールを更新するには、次のコマンドを実行します。
npm i -g @dataform/cli@^3.0.0-beta.2
認証情報ファイルを作成する
Dataform を使用するには、リモート サービスに接続し、ディスクに .df-credentials.json
ファイルを作成するための認証情報ファイルが必要です。
認証情報ファイルを作成する手順は次のとおりです。
次のコマンドを実行します。
dataform init-creds
認証情報ファイルの作成手順が表示される
init-creds
ウィザードの手順に沿って操作します。
プロジェクトを作成する
Dataform コア 3.0.0-beta.0
以降の空の Dataform プロジェクトの構造は次のとおりです。
project-dir
├── definitions
├── includes
└── workflow_settings.yaml
アセットを BigQuery にデプロイする Dataform プロジェクトを作成するには、次のコマンドを実行します。
dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID
以下を置き換えます。
- PROJECT_NAME: プロジェクトの名前。
- YOUR_GOOGLE_CLOUD_PROJECT_ID: Google Cloud プロジェクト ID。
プロジェクトのクローンを作成する
サードパーティの Git リポジトリから既存の Dataform プロジェクトのクローンを作成するには、Git プロバイダの手順に従ってください。
リポジトリのクローンを作成したら、クローンされたリポジトリ ディレクトリ内で次のコマンドを実行します。
dataform install
テーブルを定義する
definitions/
フォルダに定義を保存します。
テーブルを定義するには、次のコマンドを実行します。
echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx
以下を置き換えます。
- TABLE_TYPE: テーブルのタイプ(
table
、incremental
、view
のいずれか)。 - SELECT_STATEMENT: テーブルを定義する
SELECT
ステートメント - FILE: テーブル定義ファイルの名前。
- TABLE_TYPE: テーブルのタイプ(
次のコードサンプルは、example
SQLX ファイルにビューを定義します。
echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx
手動アサーションを定義する
definitions/
フォルダに定義を保存します。
手動アサーションを定義するには、次のコマンドを実行します。
echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx
以下を置き換えます。
- SELECT_STATEMENT: アサーションを定義する
SELECT
ステートメント。 - FILE: カスタム SQL オペレーション定義ファイルの名前。
- SELECT_STATEMENT: アサーションを定義する
カスタム SQL オペレーションを定義する
definitions/
フォルダに定義を保存します。
カスタム SQL オペレーションを定義するには、次のコマンドを実行します。
echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx
以下を置き換えます。
- SQL_QUERY: カスタム SQL オペレーション。
- FILE: カスタム SQL オペレーション定義ファイルの名前。
コンパイルの出力を表示する
Dataform は、コードをリアルタイムでコンパイルします。
ターミナルでコンパイル プロセスの出力を表示するには、次のコマンドを実行します。
dataform compile
コンパイル プロセスの出力を JSON オブジェクトとして表示するには、次のコマンドを実行します。
dataform compile --json
カスタム コンパイル変数を使用してコンパイルの出力を表示するには、次のコマンドを実行します。
dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar
以下を置き換えます。
- SAMPLE_VAR: カスタム コンパイル変数。
- SAMPLE_VALUE: カスタム コンパイル変数の値
コードを実行する
コードを実行するために、Dataform は BigQuery にアクセスして現在の状態を確認し、それに応じて結果の SQL を調整します。
Dataform プロジェクトのコードを実行するには、次のコマンドを実行します。
dataform run
カスタム コンパイル変数を使用して、BigQuery で Dataform プロジェクトのコードを実行するには、次のコマンドを実行します。
dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2
以下を置き換えます。
- SAMPLE_VAR: カスタム コンパイル変数。
- SAMPLE_VALUE: カスタム コンパイル変数の値
BigQuery で Dataform プロジェクトのコードを実行し、すべてのテーブルをゼロから再構築するには、次のコマンドを実行します。
dataform run --full-refresh
--full-refresh
を使用しない場合、Dataform は、増分テーブルをゼロから再構築せずに更新します。
BigQuery 内で実行せずに、BigQuery の現在の状態に合わせて調整された最終的なコンパイル済み SQL コードを表示するには、次のコマンドを実行します。
dataform run --dry-run
サポートが必要な場合
使用可能なすべてのコマンドとオプションを一覧表示するには、次のコマンドを実行します。
dataform help
特定のコマンドの説明を表示するには、次のコマンドを実行します。
dataform help COMMAND
COMMAND は、詳細を確認するコマンドに置き換えます。
次のステップ
- Dataform CLI の詳細については、Dataform CLI のリファレンスをご覧ください。
- Dataform の詳細については、Dataform の概要をご覧ください。