使用開放原始碼 Dataform CLI

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

透過開放原始碼的 Dataform CLI，您可以在 Google Cloud外部，於本機初始化、編譯、測試及執行 Dataform Core。

Dataform CLI 支援應用程式預設憑證 (ADC)。 透過 ADC，您可以在各種環境 (例如本機開發或實際工作環境) 中，為應用程式提供憑證，不必修改應用程式程式碼。如要使用 ADC，必須先向 ADC 提供憑證。

事前準備

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

安裝 Dataform CLI

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

    npm i -g @dataform/cli@^3.0.0-beta

初始化 Dataform 專案

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    更改下列內容：

    • PROJECT_NAME：專案名稱。
    • DEFAULT_LOCATION：您希望 Dataform 寫入 BigQuery 資料的區域。如要進一步瞭解 BigQuery 區域，請參閱 BigQuery 位置。

更新 Dataform Core

  • 如要更新 Dataform 核心架構，請更新 dataformCoreVersion 檔案中的 workflow_settings.yaml，然後重新執行 NPM 安裝：

    npm i

更新 Dataform CLI

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

    npm i -g @dataform/cli@^3.0.0-beta.2

建立憑證檔案

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

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

  1. 執行下列指令：

    dataform init-creds

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

建立專案

Dataform 核心 3.0.0-beta.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：您希望 Dataform 寫入 BigQuery 資料的區域。如要進一步瞭解 BigQuery 區域，請參閱 BigQuery 位置。

複製專案

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

  • 複製存放區後，請在複製的存放區目錄中執行下列指令：

    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 專案的程式碼，並從頭重建所有資料表，請執行下列指令：

    dataform run --full-refresh

如果沒有 --full-refresh，Dataform 會更新增量資料表，而不會從頭重建。

  • 如要對 BigQuery 執行程式碼的試算，請執行下列指令：

    dataform run --dry-run

取得說明

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

    dataform help

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

    dataform help COMMAND

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

後續步驟