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

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

オープンソースの 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 ファイルを作成するための認証情報ファイルが必要です。

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

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

    dataform init-creds
    
  2. 認証情報ファイルの作成手順が表示される 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: テーブルのタイプ(tableincrementalview のいずれか)。
    • 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 プロジェクトのコードを実行し、すべてのテーブルをゼロから再構築するには、次のコマンドを実行します。

    dataform run --full-refresh
    

--full-refresh を使用しない場合、Dataform は、増分テーブルをゼロから再構築せずに更新します。

  • BigQuery 内で実行せずに、BigQuery の現在の状態に合わせて調整された最終的なコンパイル済み SQL コードを表示するには、次のコマンドを実行します。

    dataform run --dry-run
    

サポートが必要な場合

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

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

    dataform help COMMAND
    

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

次のステップ