データソースを宣言する

このドキュメントでは、Dataform コアを使用して BigQuery データソースを宣言する方法について説明します。

Dataform では、任意の BigQuery テーブルタイプをデータソースとして宣言できます。Dataform の外部にある BigQuery データソースを宣言すると、これらのデータソースを Dataform オブジェクトとして扱うことができます。

データソースの宣言は任意ですが、次の操作を行う場合に役立ちます。

  • 宣言されたソースを、Dataform の他のテーブルと同じ方法で参照または解決する。
  • 可視化された Dataform グラフで宣言されたソースを表示する。
  • Dataform を使用して、外部で作成されたテーブルのテーブルレベルと列レベルの説明を管理する。
  • 外部データソースのすべての依存関係を含むワークフローの呼び出しをトリガーする。

JavaScript ファイルまたは SQLX ファイルを使用してデータソースを宣言できます。JavaScript ファイルでは、ファイルごとに複数のデータソースを宣言できます。SQLX ファイルでは、ファイルごとに 1 つのデータソースを宣言できます。

始める前に

データソースを宣言する前に、リポジトリで開発ワークスペースを作成して初期化します。

必要なロール

データソースを宣言するために必要な権限を取得するには、ワークスペースに対する Dataform 編集者 （roles/dataform.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

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

複数のデータソース宣言用の JavaScript ファイルを作成する

データソース宣言の JavaScript ファイルを definitions/ ディレクトリに保存します。definitions/ ディレクトリに新しい JavaScript ファイルを作成する手順は次のとおりです。

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

    [Dataform] ページに移動

  2. リポジトリを選択します。

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

  4. [ファイル] ペインで、definitions/ の横にある [その他] メニューをクリックします。

  5. [ファイルを作成] をクリックします。

  6. [新しいファイルを作成] ペインで、次の操作を行います。

    1. [ファイルパスを追加] フィールドにおいて、definitions/ の後で、ファイル名の後に .js を入力します。例: definitions/declarations.js

      ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。

    2. [ファイルを作成] をクリックします。

JavaScript ファイルに宣言を追加する

JavaScript ファイルごとに複数のデータソースを宣言できます。新しい宣言を追加する手順は、次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、データソース宣言の JavaScript ファイルをクリックします。

  2. ファイルで、データソースごとに次のコード スニペットを追加します。

      declare({
    database: "DATABASE_PROJECT_ID",
    schema: "BIGQUERY_SCHEMA",
    name: "RELATION_NAME",
  });

    以下を置き換えます。

    • DATABASE_PROJECT_ID: データソースを含むプロジェクトのプロジェクト ID。
    • BIGQUERY_SCHEMA: データソースが存在する BigQuery データセット。
    • RELATION_NAME: データソースとして使用するテーブルまたはビューの名前。この名前は、後で Dataform でデータソースを参照するために使用できます。

データソース宣言用の SQLX ファイルを作成する

データソース宣言の SQLX ファイルを definitions/ ディレクトリに保存します。definitions/ ディレクトリに新しい SQLX ファイルを作成する手順は次のとおりです。

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

    [Dataform] ページに移動

  2. リポジトリを選択します。

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

  4. [ファイル] ペインで、definitions/ の横にある [その他] メニューをクリックします。

  5. [ファイルを作成] をクリックします。

  6. [新しいファイルを作成] ペインで、次の操作を行います。

    1. [ファイルパスを追加] フィールドにおいて、definitions/ の後で、ファイル名の後に .sqlx を入力します。例: definitions/dataset-declaration.sqlx

      ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。

    2. [ファイルを作成] をクリックします。

データソースを宣言する

SQLX 宣言ファイルごとに 1 つのデータソースを宣言できます。SQLX ファイルの構成ブロックでデータソースを宣言する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、データソース宣言の SQLX ファイルをクリックします。

  2. このファイルに次のコード スニペットを入力します。

    config {
  type: "declaration",
  database: "DATABASE",
  schema: "SCHEMA",
  name: "NAME",
}

    以下を置き換えます。

    • DATABASE: データソースを含むプロジェクトのプロジェクト ID。
    • SCHEMA: データソースが存在する BigQuery データセット。
    • NAME: データソースとして使用するテーブルまたはビューの名前。この名前は、後で Dataform でデータソースを参照するために使用できます。

  3. 省略可: [書式] をクリックします。

次のコードサンプルは、bigquery-public-data プロジェクトの samples データセット内の shakespeare テーブルをデータソースとして宣言する例を示しています。

    config {
      type: "declaration",
      database: "bigquery-public-data",
      schema: "samples",
      name: "shakespeare",
    }

次のステップ