オープンソースの Dataform CLI を使用する

このドキュメントでは、オープンソースの Dataform コマンドライン インターフェース（CLI）を使用して、ターミナルでワークフローをローカルで開発する方法について説明します。

オープンソースの Dataform CLI を使用すると、の外部で Dataform コアをローカルで初期化、コンパイル、テスト、 Dataform coreを実行できます。 Google Cloud

Dataform CLI は、アプリケーションのデフォルト認証情報（ADC）をサポートしています。ADC を使用すると、アプリケーション コードを変更することなく、ローカルでの開発環境や本番環境など、さまざまな環境のアプリケーションで認証情報を使用できるようになります。ADC を使用するには、まず ADC に認証情報を指定する必要があります。

注: Dataform コア 3.0.0. 以降、 Dataform は Docker イメージを配布していません。Dataform の独自の Docker イメージを構築して、Dataform CLI コマンドと同等のコマンドを実行できます。独自の Docker イメージを構築するには、Docker ドキュメントのアプリケーションをコンテナ化するをご覧ください。

始める前に

Dataform CLI をインストールする前に、NPM をインストールします。

Dataform CLI をインストールする

• Dataform CLI をインストールするには、次のコマンドを実行します。

  npm i -g @dataform/cli
  

注: バージョン 3.0.0-beta はサポートされていません。npm audit が vm2 パッケージに関連する重大度の高い脆弱性を報告した場合、Dataform は vm2 を使用しますが、報告された脆弱性の原因であるサンドボックス化には vm2 を使用しません。新しいバージョンの Dataform CLI は、脆弱な vm2 バージョンに依存していません。

Dataform プロジェクトを初期化する

• 新しい Dataform プロジェクトを初期化するには、プロジェクト ディレクトリ内で次のコマンドを実行します。

  dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION
  

  以下を置き換えます。

  • YOUR_GOOGLE_CLOUD_PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • DEFAULT_LOCATION: Dataform がデータを処理して保存する BigQuery のロケーション。

Dataform コアを更新する

• Dataform コア フレームワークを更新するには、workflow_settings.yaml ファイルの dataformCoreVersion を更新します。workflow_settings.yaml で dataformCoreVersion が設定されている場合、Dataform は実行時に @dataform/core を自動的にインストールします。プロジェクトで workflow_settings.yaml に dataformCoreVersion がなく、package.json ファイルで @dataform/core を管理している場合は、package.json のバージョンを更新して、次を実行します。

  dataform install
  

Dataform CLI を更新する

• Dataform CLI ツールを更新するには、次のコマンドを実行します。

  npm i -g @dataform/cli@^3.0.50
  

認証情報ファイルを作成する

Dataform を使用するには、リモート サービスに接続し、ディスクに .df-credentials.json ファイルを作成するための認証情報ファイルが必要です。

警告:ソース管理システムを使用する場合、 アクセス権認証情報を保護するために、.df-credentials.json ファイルをリポジトリに commit しないでください。.df-credentials.json ファイルを .gitignore に追加することをおすすめします。

認証情報ファイルを作成する手順は次のとおりです。

1. 次のコマンドを実行します。

   dataform init-creds
   

2. 認証情報ファイルの作成手順を説明する init-creds ウィザードに従います。

プロジェクトを作成

Dataform コア 3.0.0 以降の空の Dataform プロジェクトの構造は次のとおりです。

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

• アセットを BigQuery にデプロイする Dataform プロジェクトを作成するには、次のコマンドを実行します。

  dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
  

  以下を置き換えます。

  • PROJECT_NAME: プロジェクトのディレクトリ名。
  • YOUR_GOOGLE_CLOUD_PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • DEFAULT_LOCATION: Dataform がデータを処理して保存する BigQuery のロケーション。

プロジェクトのクローンを作成する

サードパーティの Git リポジトリから既存の Dataform プロジェクトのクローンを作成するには、Git プロバイダの手順に従ってください。

• クローンされたプロジェクトが package.json ファイルで外部依存関係を宣言している場合（workflow_settings.yaml に dataformCoreVersion がない場合）、クローンされたリポジトリ ディレクトリ内で次のコマンドを実行します。

  dataform install
  

注: workflow_settings.yaml でdataformCoreVersionを指定するプロジェクトでは、実行時に@dataform/coreが自動的にインストールされるため、 dataform installを実行する必要はありません。

テーブルを定義する

definitions/ フォルダに定義を保存します。

• テーブルを定義するには、次のコマンドを実行します。

  echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx
  

  以下を置き換えます。

  • TABLE_TYPE: テーブルのタイプ（table、incremental、view のいずれか）。
  • SELECT_STATEMENT: テーブルを定義する SELECT ステートメント
  • FILE: テーブル定義ファイルの名前。

次のコードサンプルは、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 オペレーション定義ファイルの名前。

カスタム 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 プロジェクトのコードを実行し、増分テーブル（protected とマークされていない場合）をゼロから再構築するには、次のコマンドを実行します。

  dataform run --full-refresh
  

--full-refresh を指定しない場合、Dataform は増分テーブルをゼロから再構築せずに更新します（通常のテーブルとビューは常に再構築されます）。

• BigQuery に対してコードのドライランを実行するには、次のコマンドを実行します。

  dataform run --dry-run
  

注: Dataform コア 3.0.2 以降では、Dataform はコンパイル出力の各アクションのドライランを BigQuery に対して実行し、対応する IAM 権限を必要とします。 ドライランなしでコンパイルを確認するには、 コンパイルの出力を表示します。

サポートが必要な場合

• 使用可能なすべてのコマンドとオプションを一覧表示するには、次のコマンドを実行します。

  dataform help
  

• 特定のコマンドの説明を表示するには、次のコマンドを実行します。

  dataform help COMMAND
  

  COMMAND は、詳細を確認するコマンドに置き換えます。

次のステップ

• Dataform CLI コマンドとフラグの詳細については、 Dataform CLI リファレンス と GitHub の Dataform CLI リファレンスをご覧ください。
• Dataform の詳細については、 Dataform の概要をご覧ください。