借助开源 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
文件。
如需创建凭据文件,请按以下步骤操作:
运行以下命令:
dataform init-creds
按照
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:表定义文件的名称。
- 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 会更新增量表
而无需从头开始重新构建。
若要查看针对当前集群的当前状态而设置的最终编译 SQL 代码, 无需在 BigQuery 内执行 运行以下命令:
dataform run --dry-run
获取帮助
要列出所有可用的命令和选项, 运行以下命令:
dataform help
如需查看特定命令的说明,请执行以下操作: 运行以下命令:
dataform help COMMAND
将 COMMAND 替换为您要了解的命令。
后续步骤
- 如需详细了解 Dataform CLI,请参阅 Dataform CLI 参考文档
- 如需详细了解 Dataform,请参阅 Dataform 概览。