使用开源 Dataform CLI

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

借助开源 Dataform CLI，您可以初始化、编译、测试 并在本地运行 Dataform core， 外部 Google Cloud

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：您的目标区域 用于写入 BigQuery 数据的 Dataform。更多信息 有关 BigQuery 区域的信息，请参阅 BigQuery 位置。

更新 Dataform

  • 如需更新 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-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    替换以下内容：

    • PROJECT_NAME：您的项目的名称。
    • YOUR_GOOGLE_CLOUD_PROJECT_ID：您的 Google Cloud 项目 ID。

克隆项目

如需从第三方 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 会更新增量表 而无需从头开始重新构建。

  • 若要查看针对当前集群的当前状态而设置的最终编译 SQL 代码， 无需在 BigQuery 内执行 运行以下命令：

    dataform run --dry-run

获取帮助

  • 要列出所有可用的命令和选项， 运行以下命令：

    dataform help

  • 如需查看特定命令的说明，请执行以下操作： 运行以下命令：

    dataform help COMMAND

    将 COMMAND 替换为您要了解的命令。

后续步骤