数据格式 CLI 参考

本文件是本报告的完整参考 dataform 命令行接口。 命令列表, 使用行和参数/ 选项表来自此寄存器中的 CLI 源(cli/),所以它们匹配 dataform help也涵盖实际案例.

概念文档(项目结构、SQLX语法、JavaScript API等)见 根读取器 和东道主 数据窗体 CLI 指南。 。 。 .

安装

npm i -g @dataform/cli

召集

dataform <command> [project-dir] [options]

project-dir 每个命令和默认值可选 . (当前目录). 以平地扩张解决,所以 ~/my-project 工作时. project-dir 可以通过任何一种姿势(dataform compile my-project)或作为被命名的旗帜 (dataform compile --project-dir=my-project) (中文(简体) ).

运行 dataform 没有争论,或 dataform help,打印命令列表。 运行 dataform help <command> 或者说 dataform <command> --help 为命令的全旗列表.

全球行为

• --help —— 显示当前命令的帮助 .
• --version ——打印已安装的 @dataform/cli 版本号.
• 严格解析 ——未知的命令或旗帜被错误地拒绝,而CLI为打字建议了最接近匹配的命令名.
• 彩色输出 ——产出默认为彩色. 设定 NO_COLOR=1 (或 true编号 :yes要禁用它 .
• 线性调试日志 设置 DATAFORM_LINEAGE_DEBUG=1 以启用 OpenLineage 发射器的动词记录 run --emit-lineage。 。 。 .

图标

• init
• install
• init-creds
• compile
• test
• run
• format

init

dataform init [project-dir] [default-database] [default-location]

创建新的数据窗体项目( E)workflow_settings.yaml, (中文(简体) ), .gitignore, (中文(简体) ), definitions/,以及 includes/(单位:千美元) project-dir失败,如果 workflow_settings.yaml, (中文(简体) ), package.json,或 dataform.json 已存在于 project-dir。 。 。 .

立场参数

project-dir 是创建工程的目录。 所有三种立场论据也可被作为被命名的旗帜传入(--project-dir, (中文(简体) ), --default-database, (中文(简体) ), --default-location),例如. dataform init my_project --default-database=my-gcp-project-id --default-location=US。 。 。 .

选项

何时 --iceberg 已经设定, init 以交互方式提示 Iceberg 桶名称、 表格文件夹根/ 子路径和连接 .

install

dataform install [project-dir]

安装项目对国家预防机制的依赖(通过 npm i --ignore-scripts项目申报的 package.json。 。 。 .

立场参数

选项

无.

注:用于指定项目 dataformCoreVersion 内 workflow_settings.yaml, (中文(简体) ), @dataform/core 在编译/运行时自动安装在一个孤立的临时目录中,并运行 dataform install 丢出出错( e)No installation is needed when using workflow_settings.yaml, as packages are installed at runtime.) (中文(简体) ). 使用 dataform install 仅在管理时 @dataform/core 和外部依赖关系 package.json (无) dataformCoreVersion 内 workflow_settings.yaml) (中文(简体) ).

init-creds

dataform init-creds [project-dir]

交互式创建 .df-credentials.json 文件输入 project-dir dataform 用于连接到 BigQuery. 目前只支持 BigQuery .

提示:

1. 数据集位置( O)US, (中文(简体) ), EU,自定义区域名称,或 auto) (中文(简体) ). 选择 auto 叶子 location 退出证书文件, 所以大查询会动态选择位置 .
2. 认证方法——应用程序默认证书(ADC)或JSON服务账户密钥文件.
   • ADC: 提示您的计费项目 ID .
   • JSON 密钥: 下载服务账户密钥文件的路径提示 .
3. 要冒充的服务账户( 可选的, 按 Enter 以跳过) 。 保存为 impersonateServiceAccount,参见 全权证书文件。 。 。 .

立场参数

选项

compile

dataform compile [project-dir]

编译工程并打印汇编的依赖性图表摘要(或JSON / Graphviz DOT 表示),而不在您的仓库上执行。 可用于验证一个项目并检查其结构.

立场参数

选项

页:1

• --json 输出已编译的图表,不能与 --dot。 。 。 .
• --watch 忽略 node_modules,重新编译出500ms的发音,并运行到被Ctrl+C中断.
• --output-actions, (中文(简体) ), --output-tags, (中文(简体) ), --output-include-deps 财务报告和审定财务报表 --output-include-dependents 整个工程仍在编译. --output-actions 条目精确匹配( 无) * 通配符扩展).

test

dataform test [project-dir]

汇编项目并进行单位测试(type: "test" 行动)反对"大查询".

立场参数

选项

--json 输出测试结果为 JSON.

有代码的退出 1 如果任何测试失败,如果工程未能编译,或者没有找到单位测试. 输出 0 如果所有测试都通过.

run

dataform run [project-dir]

编写并执行针对大查询的项目(或以 --dry-run) (中文(简体) ).

立场参数

选项

页:1

• --actions 条目精确匹配 : * 通配符没有被扩展,一个匹配多个动作的赤色动作名是一个错误.
• --full-refresh 只影响增量表;经常表和视图总是重建.
• --json 输出运行结果为 JSON ,并且仅与 --dry-run; 平面 run --json 被拒绝.
• --timeout 仅限于编译,而不是执行。 如果没有设置 --execution-timeout, (中文(简体) ), run 显示提醒您注意的提示.
• --job-labels 覆盖 defaultJobLabels动作 jobLabels 图表 labels 用同样的钥匙.
• --emit-lineage 需要数据行距 API (datalineage.googleapis.com)和 roles/datalineage.producer 角色; 对于配置和排除出错, 请参见 数据行距指南。 。 。 .

退出代码 : 0 关于成功, 1 如果编译失败,大查询工作将获得超过64个标签(在任何动作或单位测试运行前检查),单位测试失败(与 --run-tests),运行失败,出错,或取消(Ctrl+C).

format

dataform format [project-dir]

格式 .sqlx 财务报告和审定财务报表 .js 使用 Dataform 内建的 formatter 的文件.

立场参数

选项

页:1

• 虽有同旗名, --actions 这里要针对 project-dir,而不是动作名称。 与 --ignore-js-files,默认值变为 {definitions,includes}/**/*.sqlx。 。 。 .
• --check 有代码的出口 1 如果任何文件会被重新编排.

共享项目配置旗

compile, (中文(简体) ), test,以及 run 全部接受下面的旗帜,这些旗帜将覆盖工程中的等同设置 workflow_settings.yaml 仅用于援引:

全权证书文件

init-creds 写入 .df-credentials.json 文件( 文件名固定,不可配置) 输入项目目录。 此文件存储连接细节 Dataform 需要到达您的仓库 :

• 基于ADC数字 : { "projectId": ..., "location": ... }
• 基于 JSON 键数字 : { "projectId": ..., "credentials": "<service account key JSON as a string>", "location": ... }

详细情况:

• 地点 以上两种选择(init-creds 如果 auto 选择)
• 服务账户冒充 (可选,有上述任一):增加 "impersonateServiceAccount": "<service account email>" 以该服务账户运行大查询查询(和分行排放)。 您的 ADC 身份或上面的密钥被用来冒用它和需要 roles/iam.serviceAccountTokenCreator 在服务帐户. init-creds 要求作为可选的最后一步.

只支持大查询 init-creds 和这个代码库中捆绑的大查询适配器。 处理 .df-credentials.json 作为一个秘密.. dataform init 加上来 .gitignore 自动; 从不承诺 .

实例

首次项目设置

dataform init my_project my-gcp-project-id US
cd my_project
dataform init-creds
dataform run

在不接触仓库的情况下编集和检查一个项目

# Human-readable summary
dataform compile

# Full compiled graph as JSON, e.g. to pipe into jq
dataform compile --json | jq '.tables[].target'

# Visualize the dependency graph
dataform compile --dot > graph.dot && dot -Tpng graph.dot -o graph.png

# Only show a subset of the graph (by unambiguous action name or full database.schema.name target)
dataform compile --output-actions=my_table --output-include-deps
dataform compile --output-actions=my-gcp-project-id.my_schema.my_table --output-include-deps

部署更改前运行单元测试

dataform test
# ...or fail a run early if tests don't pass:
dataform run --run-tests

只运行管道的一部分

# Run a specific table (by bare name or full database.schema.name) and anything downstream of it
dataform run --actions=my_table --include-dependents
dataform run --actions=my-gcp-project-id.my_schema.my_table --include-dependents

# Run everything tagged "daily", including their dependencies
dataform run --tags=daily --include-deps

# Force a full rebuild of the "my_incremental_table" incremental table
dataform run --actions=my_incremental_table --full-refresh

在不应用更改的情况下验证运行

dataform run --dry-run --json > dry-run-result.json

{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}能跑多长

# Compilation must finish within 30s; the whole run (compile + execute) within 15 minutes
dataform run --timeout=30s --execution-timeout=15m

# Cap each JiT-compiled model's own compilation step at 1 minute
dataform run --execution-timeout=15m --jit-timeout=1m

以不同的环境为目的进行一项援引

dataform run \
  --default-database=my-staging-project \
  --schema-suffix=staging \
  --vars=env=staging,region=eu

开发期间使用SQLX

dataform compile --watch

在不修改文件的情况下检查格式

dataform format --check

从运行中跟踪和标记工作

dataform run --job-prefix=nightly --job-labels=team=analytics,pipeline=nightly-etl

为运行代理家族事件

DATAFORM_LINEAGE_DEBUG=1 dataform run --emit-lineage

对运行一个大查询任务的每个动作,都会发出线条事件:表格(包括视图和增量表格)、操作、断言和财产图表。 打开 COMPLETE 事件, inputs 财务报告和审定财务报表 outputs 用于实现大查询对象的动作 table, (中文(简体) ), view, (中文(简体) ), incremental, (中文(简体) ), assertion, (中文(简体) ), propertyGraph,以及 operations 与 hasOutput: true) (中文(简体) ). 断言似乎是对断言数据集的断言观点的一种过程,断言的依赖性作为投入报告。 属性图输入来自动作的依赖性(dependencyTargets因此,节点和边缘表格通过 ref 以输入方式列报,而图表定义中的原始表格路径则不列报。 申报没有公布。 行动类型在 gcp_bq_pipelines_job.actionType 属性为 TABLE, (中文(简体) ), OPERATIONS, (中文(简体) ), ASSERTION 或者说 PROPERTY_GRAPH,匹配Google Cloud中Dataform使用的数值。 作为先决条件, workflow_settings.yaml 配置和排除出问题,参见 数据行距指南。 。 。 .

线条事件被发送到由 defaultLocation 内 workflow_settings.yaml 或者,如果未确定,则由 location 内 .df-credentials.json。如果两者都未设定,则用警告跳过排出分界线,运行正常进行.