使用開放原始碼 Dataform CLI

您可以使用開放原始碼 Dataform CLI，在 Google Cloud以外的本機上初始化、編譯、測試及執行 Dataform 核心。

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

事前準備

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

安裝 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 核心架構，請更新 workflow_settings.yaml 檔案中的 dataformCoreVersion，然後重新執行 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 替換為您要瞭解的指令。

後續步驟

• 如要進一步瞭解 Dataform CLI，請參閱 Dataform CLI 參考資料
• 如要進一步瞭解 Dataform，請參閱「Dataform 總覽」。