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

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

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

オープンソースの 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 データを書き込むロケーション。設定されていない場合、Dataform は SQL クエリが参照するデータセットに基づいてロケーションを決定します。この機能は次のように動作します。
  - クエリが同じロケーションのデータセットを参照している場合、Dataform はそのロケーションを使用します。
  - クエリが 2 つ以上の異なるロケーションのデータセットを参照している場合、エラーが発生します。この制限の詳細については、クロスリージョンデータセットレプリケーションをご覧ください。
  - クエリがデータセットを参照していない場合、Dataform のデフォルトのロケーションは US マルチリージョンです。別の場所を選択するには、デフォルトの場所を設定します。または、クエリで @@location システム変数を使用します。詳細については、ロケーションを指定するをご覧ください。

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

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

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

次のコマンドを実行します。
```
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-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
```
次のように置き換えます。
- PROJECT_NAME: プロジェクトの名前。
- YOUR_GOOGLE_CLOUD_PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- DEFAULT_LOCATION（省略可）: Dataform が BigQuery データを書き込むロケーション。設定されていない場合、Dataform は SQL クエリが参照するデータセットに基づいてロケーションを決定します。この機能は次のように動作します。
  - クエリが同じロケーションのデータセットを参照している場合、Dataform はそのロケーションを使用します。
  - クエリが 2 つ以上の異なるロケーションのデータセットを参照している場合、エラーが発生します。この制限の詳細については、クロスリージョンデータセットレプリケーションをご覧ください。
  - クエリがデータセットを参照していない場合、Dataform のデフォルトのロケーションは US マルチリージョンです。別の場所を選択するには、デフォルトの場所を設定します。または、クエリで @@location システム変数を使用します。詳細については、ロケーションを指定するをご覧ください。

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

サードパーティの 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: テーブル定義ファイルの名前。

次のコードサンプルは、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 に対してコードのドライランを実行するには、次のコマンドを実行します。
```
dataform run --dry-run
```

サポートが必要な場合

使用可能なすべてのコマンドとオプションを一覧表示するには、次のコマンドを実行します。
```
dataform help
```
特定のコマンドの説明を表示するには、次のコマンドを実行します。
```
dataform help COMMAND
```
COMMAND は、詳細を確認するコマンドに置き換えます。

次のステップ

Dataform CLI の詳細については、Dataform CLI のリファレンスをご覧ください。
Dataform の詳細については、Dataform の概要をご覧ください。