使用開放原始碼 Dataform CLI

本文說明如何使用開放原始碼 Dataform 指令列介面 (CLI)，透過終端機在本機開發工作流程。

您可以使用開放原始碼 Dataform CLI，在本機初始化、編譯、測試及執行 Dataform Core，不需透過 Google Cloud。

Dataform CLI 支援應用程式預設憑證 (ADC)。 有了 ADC，您可以在各種環境 (例如本機開發環境或正式環境)，為應用程式提供憑證，不用修改應用程式程式碼。如要使用 ADC，您必須先提供憑證給 ADC。

事前準備

安裝 Dataform CLI 前，請先安裝 NPM。

安裝 Dataform CLI

  • 執行下列指令，安裝 Dataform CLI：

    npm i -g @dataform/cli

初始化 Dataform 專案

  • 如要初始化新的 Dataform 專案，請在專案目錄中執行下列指令：

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

    更改下列內容：

    • YOUR_GOOGLE_CLOUD_PROJECT_ID：您的 Google Cloud 專案 ID。
    • DEFAULT_LOCATION：您希望 Dataform 處理及儲存資料的 BigQuery 位置。

更新 Dataform Core

  • 如要更新 Dataform 核心架構，請更新 workflow_settings.yaml 檔案中的 dataformCoreVersion。在 workflow_settings.yaml 中設定 dataformCoreVersion 時，Dataform 會在執行階段自動安裝 @dataform/core。如果專案是在 package.json 檔案中管理 @dataform/core，且 workflow_settings.yaml 中沒有 dataformCoreVersion，請更新 package.json 中的版本，然後執行：

    dataform install

更新 Dataform CLI

  • 如要更新 Dataform CLI 工具，請執行下列指令：

    npm i -g @dataform/cli@^3.0.50

建立憑證檔案

Dataform 需要憑證檔案，才能連線至遠端服務，並在磁碟上建立 .df-credentials.json 檔案。

如要建立憑證檔案，請按照下列步驟操作：

  1. 執行下列指令：

    dataform init-creds

  2. 按照 init-creds 精靈的指示，逐步建立憑證檔案。

建立專案

Dataform Core 3.0.0 以上版本中的空白 Dataform 專案具有下列結構：

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

  • 如要建立 Dataform 專案，將資產部署至 BigQuery，請執行下列指令：

    dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION

    更改下列內容：

    • PROJECT_NAME：專案的目錄名稱。
    • YOUR_GOOGLE_CLOUD_PROJECT_ID：您的 Google Cloud 專案 ID。
    • DEFAULT_LOCATION：BigQuery 位置，也就是 Dataform 處理及儲存資料的位置。

複製專案

如要從第三方 Git 存放區複製現有的 Dataform 專案，請按照 Git 供應商的說明操作。

  • 如果複製的專案在 package.json 檔案中宣告外部依附元件 (workflow_settings.yaml 中沒有 dataformCoreVersion)，請在複製的存放區目錄中執行下列指令：

    dataform install

定義資料表

將定義儲存在 definitions/ 資料夾中。

  • 如要定義資料表，請執行下列指令：

    echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx

    更改下列內容：

    • TABLE_TYPE：資料表類型：table、incremental 或 view。
    • SELECT_STATEMENT：定義資料表的 SELECT 陳述式。
    • FILE：資料表定義檔案的名稱。

下列程式碼範例在 example SQLX 檔案中定義檢視表。

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

定義手動斷言

將定義儲存在 definitions/ 資料夾中。

  • 如要定義手動判斷提示，請執行下列指令：

    echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx

    更改下列內容：

    • SELECT_STATEMENT：定義判斷的 SELECT 陳述式。
    • FILE：自訂 SQL 作業定義檔案的名稱。

定義自訂 SQL 作業

將定義儲存在 definitions/ 資料夾中。

  • 如要定義自訂 SQL 作業，請執行下列指令：

    echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx

    更改下列內容：

    • SQL_QUERY：自訂 SQL 作業。
    • FILE：自訂 SQL 作業定義檔案的名稱。

查看編譯輸出內容

Dataform 會即時編譯程式碼。

  • 如要在終端機中查看編譯程序的輸出內容，請執行下列指令：

    dataform compile

  • 如要以 JSON 物件的形式查看編譯程序的輸出內容，請執行下列指令：

    dataform compile --json

  • 如要查看編譯輸出內容，並使用自訂編譯變數，請執行下列指令：

    dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar

    更改下列內容：

    • SAMPLE_VAR：自訂編譯變數。
    • SAMPLE_VALUE：自訂編譯變數的值。

執行代碼

為執行程式碼，Dataform 會存取 BigQuery 來判斷目前狀態，並據此調整產生的 SQL。

  • 如要執行 Dataform 專案的程式碼，請執行下列指令：

    dataform run

  • 如要使用自訂編譯變數，在 BigQuery 中執行 Dataform 專案的程式碼，請執行下列指令：

    dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2

    更改下列內容：

    • SAMPLE_VAR：自訂編譯變數。
    • SAMPLE_VALUE：自訂編譯變數的值。

  • 如要在 BigQuery 中執行 Dataform 專案的程式碼，並從頭重新建構遞增資料表 (除非標示為 protected)，請執行下列指令：

    dataform run --full-refresh

如果沒有 --full-refresh，Dataform 會更新累加型資料表，而不必從頭重建 (一般資料表和檢視區塊一律會重建)。

  • 如要對 BigQuery 模擬測試程式碼，請執行下列指令：

    dataform run --dry-run

取得說明

  • 如要列出所有可用的指令和選項，請執行下列指令：

    dataform help

  • 如要查看特定指令的說明，請執行下列指令：

    dataform help COMMAND

    將 COMMAND 替換為要瞭解的指令。

後續步驟