使用开源 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 Core 框架，请更新 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：您希望 Dataform 处理和存储数据的 BigQuery 位置。

克隆项目

如需从第三方 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 替换为您要了解的命令。

后续步骤