借助开源 Dataform CLI,您可以在 Google Cloud 外部在本地初始化、编译、测试和运行 Dataform core。
Dataform 分发 Docker 映像,您可以使用该映像运行等效的 Dataform CLI 命令。
Dataform CLI 支持应用默认凭据 (ADC)。借助 ADC,您可以在本地开发或生产环境等各种环境中为应用提供凭据,而无需修改应用代码。如需使用 ADC,您必须先向 ADC 提供您的凭据。
准备工作
在安装 Dataform CLI 之前,请先安装 NPM。
安装 Dataform CLI
如需安装 Dataform CLI,请运行以下命令:
npm i -g @dataform/cli@^3.0.0-beta.2
初始化 Dataform 项目
如需初始化新的 Dataform 项目,请在项目目录中运行以下命令:
dataform init
更新 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
文件。
如需创建凭据文件,请按以下步骤操作:
运行以下命令:
dataform init-creds
按照
init-creds
向导中的说明创建凭据文件。
创建项目
空的 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 替换为表定义文件的名称。
- 将 TABLE_TYPE 替换为表的类型:
以下代码示例在 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 操作定义文件的名称。
- 将 SELECT_STATEMENT 替换为用于定义断言的
定义自定义 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 的当前状态定制的最终已编译 SQL 代码(而不是在 BigQuery 内执行),请运行以下命令:
dataform run --dry-run
获取帮助
如需列出所有可用的命令和选项,请运行以下命令:
dataform help
如需查看特定命令的说明,请运行以下命令:
dataform help COMMAND
将 COMMAND 替换为您想要了解的命令。
后续步骤
- 如需详细了解 Dataform CLI,请参阅 Dataform CLI 参考文档
- 如需详细了解 Dataform,请参阅 Dataform 概览。