宣告資料來源

本文件說明如何使用 Dataform core 宣告 BigQuery 資料來源。

您可以將任何 BigQuery 表格類型宣告為 Dataform 中的資料來源。宣告 Dataform 外部的 BigQuery 資料來源，可讓您將這些資料來源視為 Dataform 物件。

您不一定要宣告資料來源，但如果您想執行下列操作，這麼做會很有幫助：

  • 以與 Dataform 中其他任何資料表相同的方式，參照或解析已宣告的來源。
  • 在 Dataform 視覺化圖表中查看已宣告的來源。
  • 使用資料表單管理外部建立的資料表的資料表層級和資料欄層級說明。
  • 觸發包含外部資料來源所有依附元件的工作流程叫用作業。

您可以使用 JavaScript 或 SQLX 檔案宣告資料來源。在 JavaScript 檔案中，您可以為每個檔案宣告多個資料來源。在 SQLX 檔案中，您可以為每個檔案宣告一個資料來源。

事前準備

宣告資料來源前，請先在存放區中建立並初始化開發工作區。

必要的角色

如要取得宣告資料來源所需的權限，請要求管理員為您授予工作區的 Dataform Editor (roles/dataform.editor) 身分與存取權管理角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

建立用於多個資料來源宣告的 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. 在開發工作區的「Files」窗格中，按一下 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 宣告檔案中宣告一個資料來源。如要在 SQLX 檔案的設定區塊中宣告資料來源，請按照下列步驟操作：

  1. 在開發工作區的「Files」窗格中，按一下 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",
    }

後續步驟