使用开源 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:表的类型: tableincrementalview
    • 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 替换为您要了解的命令。

后续步骤