使用开源 Dataform CLI

本文档介绍了如何使用开源 Dataform 命令行界面 (CLI) 通过终端在本地开发工作流。

借助开源 Dataform CLI，您可以在本地（而非 Google Cloud）初始化、编译、测试、 和运行 Dataform 核心 。

Dataform CLI 支持 应用默认凭证 (ADC)。借助 ADC，您可以在各种环境（例如本地开发或生产环境）中为您的应用提供凭据，而无需修改应用代码。如需使用 ADC，您必须先 向 ADC 提供您的凭据。

准备工作

在安装 Dataform CLI 之前，请先安装 NPM。

安装 Dataform CLI

  • 如需安装 Dataform CLI，请运行以下命令：

    npm i -g @dataform/cli

初始化 Dataform 项目

  • 如需初始化新的 Dataform 项目，请在项目目录中运行以下命令：

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    替换以下内容：

    • PROJECT_NAME：您的项目的名称。

    • DEFAULT_LOCATION （可选）：您希望 Dataform 将 BigQuery 数据写入的位置。如果未设置，Dataform 会根据 SQL 查询引用的数据集确定位置。具体工作方式如下：

      • 如果查询引用了来自同一位置的数据集，Dataform 会使用该位置。
      • 如果查询引用了来自两个或更多不同位置的数据集，则会发生错误。如需详细了解此限制，请参阅 跨区域数据集复制。
      • 如果查询未引用任何数据集，Dataform 的默认位置是 US 多区域位置。如需选择其他位置，请设置默认位置。或者，您也可以在查询中使用 @@location系统变量 in your query. 如需了解详情，请参阅 指定位置。

更新 Dataform 核心

  • 如需更新 Dataform 核心框架，请更新 workflow_settings.yaml 文件中的 dataformCoreVersion，然后重新运行 NPM 安装：

    npm i

更新 Dataform CLI

  • 如需更新 Dataform CLI 工具，请运行以下命令：

    npm i -g @dataform/cli@^3.0.50

创建凭据文件

Dataform 需要凭据文件才能连接到远程服务，并在您的磁盘上创建 .df-credentials.json 文件。

如需创建凭据文件，请按以下步骤操作：

  1. 运行以下命令：

    dataform init-creds

  2. 按照 init-creds 向导的说明创建凭据文件。

创建项目

Dataform 核心 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 数据写入的位置。如果未设置，Dataform 会根据 SQL 查询引用的数据集确定位置。具体工作方式如下：

      • 如果查询引用了来自同一位置的数据集，Dataform 会使用该位置。
      • 如果查询引用了来自两个或更多不同位置的数据集，则会发生错误。如需详细了解此限制，请参阅 跨区域数据集复制。
      • 如果查询未引用任何数据集，Dataform 的默认位置是 US 多区域位置。如需选择其他位置，请设置默认位置。或者，您也可以在查询中使用 @@location系统变量 in your query. 如需了解详情，请参阅 指定位置。

克隆项目

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

后续步骤