Dataform にパッケージをインストールする

このドキュメントでは、JavaScript パッケージを Dataform リポジトリにインストールし、JavaScript ファイルと SQLX ファイルにインポートして、パッケージを使用して Dataform で SQL ワークフローを開発する方法について説明します。

Dataform でパッケージを使用するには、リポジトリにパッケージをインストールする必要があります。

Dataform には、次の種類のパッケージをインストールできます。

次に、JavaScript ファイルまたは SQLX ファイルでパッケージを使用するには、パッケージの選択した内容をファイルにインポートする必要があります。選択したコンテンツではなく、パッケージ全体を JavaScript ファイルまたは SQLX ファイルにインポートすることもできます。

本番環境でのパッケージのインストールに関する問題を回避するには、次の手順を行うことをおすすめします。

  • package.json でパッケージ バージョンを明示的に指定します（例: 3.0.0）。package.json の他の dependencies オプション（>version など）は使用しないでください。

  • 新しいパッケージのバージョンを非本番環境でテストします。さまざまなコード ライフサイクル環境の構成の詳細については、コード ライフサイクルの管理をご覧ください。

始める前に

  1. Google Cloud コンソールの [Dataform] ページに移動します。

    [Dataform] ページに移動

  2. リポジトリを作成または選択します。

  3. 開発ワークスペースを作成または選択します。

  4. 省略可: 非公開パッケージをインストールするには、非公開パッケージを認証します。

必要なロール

パッケージをインポートするために必要な権限を取得するには、Dataform 編集者 （roles/dataform.editor）IAM ワークスペースに対するロールの付与を管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Dataform リポジトリにパッケージをインストールする

Dataform リポジトリ内にパッケージをインストールするには、package.json ファイルに依存関係として追加する必要があります。package.json ファイルの依存関係定義の形式は、パッケージのタイプによって異なります。workflow_settings.yaml ファイルに dataformCoreVersion が指定されているために package.json ファイルがない場合は、workflow_settings.yaml から dataformCoreVersion を削除してから作成します。それから package.json ファイルを作成し、依存関係として @dataform/core を追加します。

Dataform リポジトリにパッケージをインストールする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、package.json を選択します。

  2. パッケージを dependencies ブロックに追加します。

    1. 公開されている一般公開の NPM パッケージを次の形式で追加します。

      "PACKAGE-NAME": "PACKAGE-VERSION"

      以下を置き換えます。

      • PACKAGE-NAME をパッケージ名に置き換えます。
      • PACKAGE-VERSION を、公開されている最新バージョンの公開 NPM パッケージに置き換えます。パッケージのインストールに関する問題を回避するため、バージョンを明示的に指定します（例: 3.0.0）。

    2. 次の形式で、未公開のパブリック NPM パッケージを追加します。

      "PACKAGE-NAME": "PACKAGE-URL"

      以下を置き換えます。

      • PACKAGE-NAME をパッケージ名に置き換えます。
      • PACKAGE-URL は、サードパーティ パッケージ リポジトリの tar.gz URL に置き換えます（例: https://github.com/user/sample-package-repository/archive/master.tar.gz）。

    3. 次の形式で、認証済みの非公開 NPM パッケージを追加します。

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      以下を置き換えます。

      • REGISTRY-SCOPE はパッケージの名前に置き換えます。REGISTRY-SCOPE は、リポジトリの .nmprc ファイルで定義されたレジストリ スコープと一致する必要があります。
      • PACKAGE-NAME をパッケージ名に置き換えます。
      • PACKAGE-URL を、パッケージ リポジトリの tar.gz URL（https://github.com/user/sample-package-repository/archive/master.tar.gz など）に置き換えます。

  3. [パッケージをインストール] をクリックします。

  4. 変更を commit して push します。

次のコードサンプルは、公開されているオープンソースの変化が緩やかなディメンション パッケージ パッケージを .package.json ファイルに追加したものです。

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Dataform の JavaScript ファイルにパッケージ関数または定数をインポートする

Dataform の JavaScript ファイル内でパッケージの関数または定数を使用するには、まずその関数または定数をファイルにインポートする必要があります。

関数または定数をパッケージから JavaScript ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。

  2. ファイルで、次の形式の関数または定数をインポートします。

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. EXPORT-NAME は、使用する関数または定数の名前に置き換えます。この名前は、パッケージ index.js ファイルの module.exports で宣言します。
    2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、JavaScript ファイルでインポートされ使用される postoffice パッケージの getDomain 関数を示しています。

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Dataform でパッケージ全体を JavaScript ファイルにインポートする

選択した関数や定数を JavaScript ファイルにインポートするのではなく、パッケージ全体を JavaScript ファイルにインポートするには、次の手順を行います。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。

  2. ファイルで、次の形式でパッケージをインポートします。

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. CONSTANT-NAME は、定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、JavaScript ファイルで使用されるインポートされた postoffice パッケージの getDomain 関数を示しています。

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Dataform の SQLX ファイルにパッケージ関数または定数をインポートする

SQLX ファイル内のパッケージの関数または定数を使用するには、まずそのファイルをインポートする必要があります。

関数または定数をパッケージから SQLX ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。

  2. ファイルに次の js ブロックを入力します。

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. EXPORT-NAME は、パッケージ index.js ファイルの module.exports で宣言されている、使用する関数または定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、js ブロックでインポートされ、SQLX ファイルの SELECT ステートメントで使用される postoffice パッケージの getDomain 関数を示しています。

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Dataform でパッケージ全体を SQLX ファイルにインポートする

選択した関数または定数を JavaScript ファイルにインポートするのではなく、パッケージ全体を SQLX ファイルにインポートするには、次の手順を行います。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。

  2. ファイルで、次の形式でパッケージをインポートします。

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. CONSTANT-NAME は、定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、js ブロックでインポートされた postoffice パッケージと、SQLX ファイルの SELECT ステートメントで使用される getDomain 関数を示しています。

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

次のステップ