使用开源 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 数据写入的位置。如果未设置，Dataform 会根据 SQL 查询引用的数据集确定位置。其工作原理如下：

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

更新 Dataform 核心

  • 如需更新 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 数据写入的位置。如果未设置，Dataform 会根据 SQL 查询引用的数据集确定位置。其工作原理如下：

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

克隆项目

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

后续步骤