在資料表單中使用 JavaScript

本文說明如何使用 JavaScript 在 Dataform 中開發工作流程。本文也說明如何使用 JavaScript 建立工作流程動作，以及如何建立 JavaScript 包含項目，以便在 Dataform 中重複使用程式碼。

Dataform 核心可讓您使用 SQLX 和 JavaScript 建立工作流程動作。雖然是選用功能，但您可以使用 JavaScript 和 SQLX，在工作流程中重複建立類似元素。舉例來說，您可以使用 JavaScript 建立工作流程中每個表格的檢視畫面，並移除特定使用者 ID。您也可以完全使用 JavaScript 開發工作流程動作。

事前準備

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取或建立存放區。

  3. 選取或建立開發工作區。

此外，您也必須熟悉 JavaScript 語法和下列 JavaScript 概念：

  • 變數
  • 陣列
  • 條件陳述式
  • For 迴圈
  • 地圖
  • 函式
  • 物件
  • 匯出及匯入模組

必要的角色

如要取得使用 JavaScript 開發工作流程，以及透過 JavaScript 包含項目重複使用程式碼所需的權限，請要求系統管理員授予您工作區的「Dataform 編輯者 」(roles/dataform.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

在 SQLX 檔案中加入 JavaScript 程式碼

您可以透過兩種方式將 JavaScript 程式碼新增至 SQLX 檔案：內嵌或在 JavaScript 區塊內。

您可以在 SQLX 檔案中使用 JavaScript 區塊定義函式或常數。您可以使用內嵌 JavaScript 動態修改 SQLX 或 SQL 查詢。

下列程式碼範例顯示 self Dataform Core 內建 JavaScript 函式，已內嵌至 SQLX 檔案的 post_operations 區塊：

config {type: "table"}

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer`
  ON
  TABLE ${self()}
  TO "group:allusers@example.com", "user:otheruser@example.com"
}

下列程式碼範例顯示在 JavaScript 區塊中定義的常數，並在 SQLX 檔案的查詢中內嵌使用：

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

透過 JavaScript 封裝，在單一 SQLX 檔案中重複使用程式碼

您可以在 Dataform 中重複使用 JavaScript 程式碼，簡化開發作業。 如要在單一 SQLX 檔案中重複使用 JavaScript 常數和函式，可以將這些常數和函式封裝在 JavaScript 區塊中。如要在單一 Dataform 存放區中重複使用 JavaScript 程式碼，可以建立 include。如要在多個 Dataform 存放區中重複使用 JavaScript 程式碼，可以建立或匯入套件。

如要建立可在單一 SQLX 檔案中重複使用的 SQL 程式碼部分，您可以將函式和常數封裝在 JavaScript 區塊中。您只能在定義 JavaScript 區塊的 SQLX 檔案中，重複使用該區塊定義的程式碼。詳情請參閱 Dataform 核心。

下列程式碼範例顯示在 JavaScript 區塊中定義的常數和函式，並在 SQLX 檔案的查詢中內嵌使用：

js {
 const foo = 1;
 function bar(number){
     return number+1;
 }
}

select
 ${foo} as one,
 ${bar(foo)} as two

透過 include 在單一存放區中重複使用程式碼

包括是您存放區的全域 JavaScript 常數或函式。您可以在存放區的 includes 目錄中定義包含項目。然後在 JavaScript 和 SQLX 檔案中，跨存放區重複使用這些變數。

下列程式碼範例顯示 includes/constants.js 檔案中 launch_date 常數的定義：

// filename is includes/constants.js
const launch_date = "11.11.2011";
module.exports = { launch_date };

下列程式碼範例顯示 SQLX 檔案中資料表定義查詢所參照的 launch_date 常數：

config {type: "table"}

SELECT * FROM source_table WHERE date > ${constants.launch_date}

建立 JavaScript 檔案以供納入

如要在 includes/ 目錄中建立新的 JavaScript 檔案，請按照下列步驟操作：

  1. 在「Files」(檔案) 窗格中，點按 includes/ 旁的 「更多」。

  2. 點選「建立檔案」。

  3. 在「建立新檔案」窗格中，執行下列步驟：

    1. 在「Add a file path」(新增檔案路徑) 欄位中，在 includes/ 後方輸入檔案名稱，然後輸入 .js。例如：includes/constants.js。

      檔案名稱只能包含數字、英文字母、連字號和底線。

    2. 點選「建立檔案」。

建立 JavaScript 常數

如要建立可在專案中重複使用的常數，請按照下列步驟操作：

  1. 前往開發工作區。

  2. 在「檔案」窗格中，展開 includes/。

  3. 建立或選取副檔名為 .js 的 JavaScript 檔案。

  4. 在檔案中輸入下列程式碼片段：

     const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };

    更改下列內容：

    • CONSTANT_NAME：常數名稱
    • CONSTANT_VALUE：常數值

  5. 選用：按一下「格式」。

下列程式碼範例會在 includes/constants.js 檔案中定義 PROJECT_ID 常數：

  // filename is includes/constants.js
  const PROJECT_ID = "my_project_name";
  module.exports = { PROJECT_ID };

下列程式碼範例會在 SQLX 檔案的資料表定義查詢中參照 PROJECT_ID 常數：

  config { type: "table" }
  SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name

下列程式碼範例顯示編譯成 SQL 的先前 Dataform 核心資料表定義查詢：

  SELECT * FROM my_project_name.my_schema_name.my_table_name

建立自訂 JavaScript 函式

如要建立可在專案中重複使用的自訂 JavaScript 函式，請按照下列步驟操作：

  1. 前往開發工作區。

  2. 在「檔案」窗格中，展開 includes/。

  3. 建立或選取副檔名為 .js 的 JavaScript 檔案。

  4. 在檔案中編寫自訂 JavaScript 函式。

  5. 在檔案中輸入下列程式碼片段：

     module.exports = { FUNCTION_NAME }

    以您的函式名稱取代 FUNCTION_NAME。

  6. 選用：按一下「格式」。

下列程式碼範例顯示名為 renderScript 的自訂 JavaScript 函式，並儲存在 includes/functions.js 檔案中。函式會產生 SQL 指令碼：

  function renderScript(table, dimensions, metrics) {
    return `
        select
        ${dimensions.map(field => `${field} as ${field}`).join(",")},
        ${metrics.map(field => `sum(${field}) as ${field}`).join(",\n")}
        from ${table}
        group by ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
      `;
  }

  module.exports = { renderScript };

下列程式碼範例顯示如何在 Dataform 核心資料表定義查詢中使用自訂 renderScript JavaScript 函式：

  config {
      type: "table",
      tags: ["advanced", "hourly"],
      disabled: true
  }

  ${functions.renderScript(ref("source_table"),
                                ["country", "device_type"],
                                ["revenue", "pageviews", "sessions"]
                                )}

下列程式碼範例顯示編譯為 SQL 的先前 Dataform 核心資料表定義查詢：

  select
    country as country,
    device_type as device_type,
    sum(revenue) as revenue,
    sum(pageviews) as pageviews,
    sum(sessions) as sessions

  from "dataform"."source_table"

  group by 1, 2

在 SQLX 檔案中參照 include

您可以在 SQLX 檔案中參照任何 include 函式或常數。參考 include 的語法取決於 include 檔案的位置。頂層包含檔案位於 includes/ 目錄中。巢狀包含檔案位於 includes/ 的子目錄中。

在 SQLX 檔案中參照頂層 include

  • 如要在 Dataform 核心查詢中參照頂層 include 函式或常數，請輸入 include 定義檔案名稱 (不含 .js 副檔名)，然後輸入匯出物件的名稱。

下列程式碼範例會在資料表定義 SQLX 檔案中，參照 includes/constants.js 檔案中定義的 firstDate 常數：

  config {type: "table"}
  select * from source_table where date > ${constants.firstDate}

在 SQLX 檔案中參照巢狀包含項目

如要參照 definitions 子目錄中的 include，請使用 JavaScript require 函式和 js {} 區塊匯入 include。

如要使用 require JavaScript 函式參照巢狀內含項目，請按照下列步驟操作：

  1. 前往開發工作區。

  2. 在「檔案」窗格中，展開 definitions/。

  3. 選取 SQLX 檔案。

  4. 在 config 區塊中，輸入下列程式碼片段：

     js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }

    更改下列內容：

    • VARIABLE_NAME：要匯入的常數或函式名稱
    • SUBDIRECTORY_INCLUDE：巢狀 includes 檔案的路徑

  5. 選用：按一下「格式」。

下列程式碼範例會在資料表定義 SQLX 檔案中，參照巢狀 includes/allConstants/constants.js 檔案中定義的 firstDate 常數：

  config {type: "table"}
  js {
    var { firstDate } = require("includes/allConstants/constants");
  }
  select * from source_table where date > ${firstDate}

搭配 Dataform 核心 ref 函式使用 JavaScript 納入函式

如要搭配 Dataform 核心 ref 函式使用 JavaScript 納入函式，您需要在 SQLX 檔案中，將 ref 做為 JavaScript 納入函式的引數傳遞。

下列程式碼範例顯示 includes/script_builder.js 檔案，其中包含 renderScript JavaScript 函式，可使用 SUM 匯總指標，並依維度分組：

function renderScript(table, dimensions, metrics) {
  return `
      SELECT
      ${dimensions.map((field) => `${field} AS ${field}`).join(",\\n")},
      ${metrics.map((field) => `SUM(${field}) AS ${field}`).join(",\\n")}
      FROM ${table}
      GROUP BY ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
    `;
}
module.exports = { renderScript };

下列程式碼範例顯示 renderScript 檔案中使用的 JavaScript 函式，並將 Dataform 核心 ref 函式做為引數傳遞：definitions/stats_per_country_and_device.sqlx

${script_builder.renderScript(
  ref("source_table"),
  ["country", "device_type"],
  ["revenue", "pageviews", "sessions"])}

下列程式碼範例顯示編譯為 SQL 的 definitions/stats_per_country_and_device.sqlx 查詢：

SELECT country AS country,
       device_type AS device_type,
       SUM(revenue) AS revenue,
       SUM(pageviews) AS pageviews,
       SUM(sessions) AS sessions
FROM my_schema.source_table
GROUP BY 1, 2

如要進一步瞭解 Dataform 核心 ref 函式，請參閱 Dataform 核心。

透過套件在多個存放區中重複使用程式碼

套件是 JavaScript 程式碼的集合，您可以在多個 Dataform 存放區中匯入及使用，簡化工作流程開發。

您可以在 Dataform 中建立自己的自訂套件，也可以使用開放原始碼的 Dataform 套件，這些套件可在 GitHub 開放原始碼 Dataform 頁面上取得。

如要在 Dataform 中使用套件內容，您必須先在 Dataform 存放區中安裝套件，然後將套件匯入要使用套件的個別 JavaScript 或 SQLX 檔案。詳情請參閱「安裝套件」。

如要在 Dataform 存放區中安裝私人 npm 套件，您需要驗證套件。

完全使用 JavaScript 建立工作流程

本節說明如何在 Dataform 中使用 JavaScript 建立工作流程動作。您可能想使用 JavaScript，而不是 Dataform 核心，在工作流程中重複建立類似元素。

除了使用 SQLX 或 SQLX 搭配 JavaScript 開發工作流程，您也可以只使用 JavaScript，在 .js 檔案中建立工作流程動作。您可以在一個 JavaScript 檔案中，使用 Dataform 全域方法和任意 JavaScript ES5 程式碼 (例如迴圈和常數)，建立多個工作流程動作。每個 Dataform 全域 JavaScript 方法都包含可用於設定所建立物件的屬性。

您可以在 Dataform 中只使用 JavaScript，建立下列工作流程動作：

  • 資料來源聲明
  • 資料表
  • 手動聲明