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

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

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

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

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

始める前に

  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 パッケージの最新バージョンに置き換えます。

    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 ファイルに追加された、オープンソースの緩やかに変化するディメンション パッケージ パッケージを示しています。

 ```
 {
   "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 ブロックにインポートされた postoffice パッケージの getDomain 関数を示し、SQLX ファイルの SELECT ステートメントで使用します。

/*
 * 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

次のステップ