跳转至

CLI 参考

dosi 是 Dosi 的命令行界面:校验一份 Apache Ossie(原 OSI)语义模型、浏览它编译出的 指标/数据集/维度、把一次指标查询或查询明细行编译成方言 SQL, 并把这段 SQL 在数仓上执行。 REST API 通过 HTTP 能做的一切,dosi 都能在 shell 里做: 同一个编译器、同样的结构化错误、同样的 --format json 机器契约。

$ dosi --help
Compile metric queries over OSI semantic models to dialect SQL

Usage: osi [OPTIONS] <COMMAND>

Commands:
  validate  Validate the model: structure, unique names, relationship integrity, and metric compilation
  list      List model objects
  query     Compile a metric query to SQL
  select    Query row-level detail: project fields at one dataset's grain, joining related datasets automatically
  explain   Show the compiled IR shape and logical plan without generating SQL

安装

dosi 发布两种形态:默认版把 DuckDB 官方库 libduckdb 放在可执行文件旁边 —— 这些文件总是一起走,没有别的东西要装;精简版不带它,本地 DuckDB 查询改走 PATH 上的 duckdb 命令行。两种形态都带上了全部数仓连接器。

怎么选、下载命令和校验方式见安装。

Dosi 面向 Linux 和 macOS 发布,可执行文件只依赖标准系统库(Linux 上 glibc ≥ 2.28, macOS 11 及以上);默认版还通过旁边的 libduckdb 带来 libstdc++ 依赖, 精简版则完全没有 C++ 依赖。 连接器里的 TLS 用 rustls,所以不需要安装 OpenSSL,也不需要任何数据库客户端库。

全局选项

以下选项对每条命令都生效(clap 的 global = true):

参数 环境变量 默认值 含义
--model <path> DOSI_MODEL 必填 Ossie 模型文件(.yaml / .yml / .json)
--format <fmt> — text 输出格式:text、json 或 arrow(见输出格式)
--connections <path> DOSI_CONNECTIONS 发现链 --execute 用的连接配置文件(见在数仓上执行)
--osi-datus — 开启 Datus 模式:DATUS nonportable_extensions 会被采纳(datus-extensions.md)
--osi-basic — 关闭 基础模式,严格的标准 Ossie。DATUS 扩展被忽略并给出警告;validate 还会额外运行上游校验器(见下)

--osi-datus 与 --osi-basic 互斥,同时传入属于用法错误。基础模式下, 每个被忽略的扩展都会在 stderr 上打印一行 ! 警告(在 --format json 下则落在 warnings 里);警告永远不改变退出码。

如果设置了 DOSI_MODEL,--model 可以省略;一条需要模型却两者都没找到的命令会以 no model given; pass --model <path> or set DOSI_MODEL 退出。

退出码: 0 成功,1 引擎拒绝了这次查询/执行(带结构化错误), 2 用法/CLI 错误(参数写错、缺模型、参数无法解析)。

命令

dosi info

报告引擎版本、Ossie 规范版本和 datus-ext 版本,以及本引擎会读取的每一个 vendor_name: DATUS 的 nonportable_extensions 键。它不需要模型, 所以也可以当作版本探测命令用。

$ dosi info
dosi       0.2.2
osi spec   0.3.0.dev0
datus-ext  1.14 (accepts 1.0 and up)
mode       datus
build      engine (DuckDB in process)
examples   /home/you/.local/share/dosi/examples

KEY               EXTENSION     CARRIERS         SINCE  IF IGNORED
join_type         D-JOIN        relationship     1.0    documented
fill_nulls_with   D-FILL        metric           1.0    documented
time_dimension    D-TIME        dataset, metric  1.1    degraded
time_granularity  D-GRAIN       field            1.1    documented
window            D-WINDOW      metric           1.2    documented
dataset           D-DATASET     metric           1.1    degraded
derive            D-DERIVE      metric           1.4    degraded
measure           D-MEASURE     metric           1.4    silent
params            D-PARAM       metric, field    1.5    degraded
time              D-FORMAT      field            1.6    silent
is_dimension      D-DIM         field            1.7    documented
cardinality       D-CONFORM     relationship     1.8    silent
lod               D-LOD         field            1.10   degraded
concept_params    D-PARAM       mapping          1.12   degraded
determines        D-DETERMINES  field            1.14   degraded

build 说明这是发布的两种形态里的哪一种 —— engine 在进程内跑 DuckDB, lean 把本地 DuckDB 交给 PATH 上的 duckdb 命令行 (见该下载哪个?)。没有这一行, 装好的可执行文件是哪一种就只能靠 ldd 分辨。

examples 是内置示例模型的所在位置:设了 $DOSI_EXAMPLES 就用它, 否则找 $XDG_DATA_HOME/dosi/examples(即 ~/.local/share/dosi/examples)。 两处都没有时这一行不打印。本页的示例都用 $DOSI_EXAMPLES, 先导出一次,下面的命令就都能直接复制运行:

$ export DOSI_EXAMPLES=~/.local/share/dosi/examples

SINCE 是引入该键的 datus-ext 版本,IF IGNORED 是不采纳它要付出的代价, 见扩展版本。 --format json 以机器契约的形式输出同样的内容。 生成模型的 Agent 在决定输出哪些键之前,应该先读它。

dosi validate

加载模型并跑完整的校验流水线:结构、名称唯一性、关系引用完整性、 指标表达式编译,然后报告每一个问题。

$ dosi validate --model $DOSI_EXAMPLES/tpcds/model.yaml
✓ 1 semantic model(s) valid

--format json 会输出 {issues, compile_errors, warnings} 供 CI 把关: 每个 issue 带严重级别和消息,每个编译错误带稳定的 code 和可选的 hint, 每条警告带稳定的 code、location 和 message。有错误的模型以非零码退出; 只有警告则不会。

字段角色提示(datus 模式)。 在 --osi-datus(默认模式)下,校验还会指出 模型没声明、结构也推断不出来的字段角色:没有任何指标聚合的度量列、既不是声明的键 也不是关系列的业务键、没标 dimension.is_time 的时间列。每条警告都点名字段并给出 该写什么(通常是 is_dimension);不管它,这些字段 就会被当作分组维度推荐出去,agent 真的会按它们分组。这项检查总是执行,没有开关 可以关掉;--strict 让它计入退出码,供 CI 使用:

$ dosi validate --strict --model model.yaml
! underdeclared_field in field 'routes.distance_miles': `routes.distance_miles` looks like a
  measurement no metric aggregates, so it is offered as a grouping dimension; write the
  metric it belongs to, or declare `is_dimension: false`
✗ the authoring lint reported findings and --strict is set

上游校验(--osi-basic)。 在基础模式下,当能找到一份 checkout 时, validate 会额外调用上游的 apache/ossie 参考校验器(即 OSSIE_DIR,默认 ~/src/ossie,其下含有 validation/validate.py), 用已发布的规范来要求这份模型。那个校验器把自己的依赖写成了脚本内联元数据, 所以 PATH 上有 uv 时走 uv run --script, 否则走 python3。上游失败会让整条命令失败;但凡是让校验器根本跑不起来的情况 —— 没有 checkout、没有解释器、或者解释器缺 pyyaml / jsonschema / sqlglot —— 都只打印一条提示、退回到只做内置校验,因为「我们问不到」不能读成「这个模型不合法」。 --format json 会额外输出 "upstream": {ran, passed, output, note}。

请使用与 Dosi CI 相同的 Apache Ossie 提交,其中包含 0.3.0.dev0 的规范和校验器。 Dosi 会先升级支持迁移的旧文件,再交给上游校验器。 参见一个文档一个模型。

$ git clone https://github.com/apache/ossie ~/src/ossie
$ git -C ~/src/ossie checkout a0d15d29e9c90f65e0978b8bb32619fd4ef42c5c
$ OSSIE_DIR=~/src/ossie dosi validate --osi-basic --model model.yaml
✓ upstream OSI validation passed
✓ 1 semantic model(s) valid

dosi list <what>

浏览编译后的语义层。三个子命令,在 text 模式下各是一张表, 在 --format json 下则是一个对象数组:

子命令 列
dosi list datasets 名称、来源、主键、字段数、时间维度
dosi list metrics 名称、推断出的种类(aggregate / ratio / expression)、数据集、描述
dosi list dimensions [--metric <名称>] dataset.field、时间标记、是否值得用来分组(DIM)、由谁判定(SOURCE)、描述

不带 --metric 时列出模型的全部字段;带 --metric 时只列出该指标能分组的字段, 推荐的排在前面。DIM 为 no 表示模型声明(或引擎推断)它不是维度 —— 度量列、键、 关系列;SOURCE 说明依据:declared 表示来自 D-DIM 声明,否则是 inferred:<规则>。 no 的字段仍然可以写进 --group-by:这是推荐,不是限制。

$ dosi list dimensions --metric revenue --model $DOSI_EXAMPLES/orders/model.yaml
NAME                   TIME  DIM  SOURCE                DESCRIPTION
metric_time            time  yes  inferred:time
orders.status                yes  inferred
customers.region             yes  inferred
products.category            yes  inferred
orders.amount                no   inferred:measure
orders.customer_id           no   inferred:foreign_key
orders.order_id              no   inferred:primary_key

带 --metric 时,指标自己的时间列只以 metric_time 出现一次; 一致性维度也只出现一次,用指标这一侧的拼写。

$ dosi list metrics --model $DOSI_EXAMPLES/tpcds/model.yaml
NAME                     KIND        DATASETS               DESCRIPTION
total_sales              aggregate   store_sales            Total sales revenue across all transactions
total_profit             aggregate   store_sales            Total net profit from store sales
customer_lifetime_value  ratio       customer, store_sales  Average lifetime sales value per customer
sales_by_brand           aggregate   store_sales            Total sales by brand (requires grouping by item.i_brand)
store_productivity       expression  store, store_sales     Sales per employee across stores

dosi show <metric|dataset> <名称>

单个对象的完整描述,也就是 list 省掉的那些。--format json 输出的对象和 MCP 的 describe_metric / describe_dataset、REST 的 /v1/metrics/{name} / /v1/datasets/{name} 返回的相同。

子命令 内容
dosi show metric <名称> 描述、种类、expr(怎么算出来:聚合式、<base> FILTER (WHERE …)、复合指标的算式、细节层次声明)、数据集、能分组的数据集、查询能绑定的全部参数(不是它自己声明的会注明声明在哪个指标上)、必填维度、时间粒度
dosi show dataset <名称> 来源、描述、时间轴、主键、每个字段及其表达式(fixed 字段给出 fixed(base, 键…) 声明、它读的数据集和统计期落在哪一列)、从这个数据集看的关系
$ dosi show metric revenue --model $DOSI_EXAMPLES/orders/model.yaml
metric: revenue
description: Total order amount
kind: aggregate
expr: SUM(orders.amount)
datasets: orders
group_by: orders, customers, products
time: metric_time (day, week, month, quarter, year)

名称不存在时以非零状态退出,报 unknown_metric / unknown_dataset,并列出存在的名称。

dosi query

核心命令:把一次指标查询编译成方言 SQL,并可选地执行它。查询本身由下面共用的 query spec 参数来描述;在此之上,query 还接受:

参数 含义
--dialect <name> 目标 SQL 方言(默认取 --connection 所指配置的方言;没有就取 default: true 那个连接的方言;都没有则是 duckdb)
--pretty 美化打印生成的 SQL
--explain 在 SQL 上方一并打印逻辑计划
--execute 把编译出的 SQL 拿到数仓上执行并打印结果行
--connection <name> 连接配置文件里的具名配置(同时决定方言)
--db <path> 不带 --connection 时 --execute 使用的 DuckDB 文件(默认:内存)

只编译(不加 --execute)会打印 SQL(text)或 {dialect, sql}(json)。没有 --dialect、--connection、--db 时,按标了 default: true 的连接的方言编译:只读它的 type,不解析密钥,也不连库。这样 query 和 query --execute 生成的 SQL 一致,stderr 会说明用了哪个方言。默认连接是 DWS 时仍要加 --dws-mode。没有默认连接时按 DuckDB 编译:

$ dosi query --model $DOSI_EXAMPLES/tpcds/model.yaml \
    --metrics total_sales \
    --group-by store.s_state,date_dim.d_date:month \
    --where "item.i_category = 'Books'" \
    --start-time 2024-01-01 --end-time 2025-01-01 \
    --order -total_sales --limit 100 \
    --dialect starrocks
SELECT store.s_state AS s_state, DATE_TRUNC('MONTH', date_dim.d_date) AS d_date__month, ...

(把 total_sales 和基于 store 的指标(比如 store_productivity)放在一起, 会得到 fan_out_risk 错误:按门店计算的度量,无法按门店够不到的日期来分组。 这种保护正是要点所在,见 semantics.md §6。)

查询里某个部分读不到的条件不会被悄悄丢掉:加 --format json 时结果在 warnings 里列出, 文本输出则把每条告警打印到 stderr。见过滤条件(S-FILTER-5)。

query spec 参数(与 explain 共用)

参数 含义
--metrics <a,b,…> 必填。 逗号分隔的指标名
--group-by <items> 逗号分隔的 dataset.field 或 dataset.field:grain(粒度:day\|week\|month\|quarter\|year);metric_time[:grain] 表示按每个指标各自的主时间维度分组
--where <sql> 标量布尔 SQL,按 AND 子条件分别放置:引用所选指标的条件筛选结果行(在 --order / --limit 之前);窗口查询里只引用分组维度的条件也筛结果,名次和分区行数仍按全体计算;其余条件在聚合之前筛选输入行。见过滤条件。
--context-filter <sql> 始终在聚合前限定计算总体,也限定每个读得到这些列的固定粒度汇总。与普通 --where 的区别见 LOD 过滤规则
--start-time <YYYY-MM-DD> 时间范围的下界,含该值
--end-time <YYYY-MM-DD> 上界,不含该值
--time-dimension <field> 该范围作用在哪个时间维度上(默认:group-by 里唯一的那个时间维度,否则是每个指标的主时间;metric_time 用于显式指明)。每个固定粒度汇总都在自己数据集的时间字段上取这个统计期。
--order <keys> 逗号分隔的排序键;前缀 - 表示降序。NULL 在每个数仓上都排在最后,键后面加 nulls first 则排在最前:--order "-revenue nulls first"。见排序
--param <name=value[,value…]> 绑定一个 D-PARAM 参数(可重复)。值按指标声明的类型解析;逗号列表把指标展开成每个值一列;含逗号的字符串值请加引号。对多选参数,逗号列表是一组值,每重复一次 --param 多一组(每组一列)。见参数化指标
--limit <n> 行数上限

粒度的输出列怎么命名、排序键可以写什么、时间范围和 metric_time 怎么生效、 每个 --where 条件落在哪一层,都在查询指标里配了例子讲。

dosi select

编译一次明细查询:以某个数据集的粒度返回行级记录,而不是聚合后的指标。 同一个计划器、同一张关系图、同样的结构化错误 —— 完整指南见查询明细行。

$ dosi select --model $DOSI_EXAMPLES/orders/model.yaml \
    --from orders \
    --fields orders.order_id,orders.amount,customers.region \
    --where "customers.region = 'east'" \
    --order -amount --limit 20 --execute --db orders.duckdb

它接受与 query 相同的 --dialect / --dws-mode / --pretty / --explain / --execute / --connection / --db,外加自己的 spec 参数:

参数 含义
--from <dataset> 必填。 结果粒度:一行输出对应该数据集的一行。不是 SQL 的 FROM ——其余数据集会自动连接。
--fields <a,b,...> 必填。 field、dataset.field,或 relationship[.relationship…].field;时间字段可加 :grain 后缀。
--where <sql> 行级过滤。可以引用投影里没有的数据集,引用到就会连上。聚合会被拒绝;可以引用根数据集的固定粒度字段。
--context-filter <sql> 和 --where 一样筛行,同时进入查询读到的每个固定粒度汇总。见固定粒度字段。
--start-time / --end-time 半开区间 [start, end)。
--time-dimension <field> 窗口作用在哪个时间字段上;默认取根数据集的主时间维度。
--order <k,-k,...> 排序键,必须是已投影的列(- 前缀表示降序;NULL 排在最后,键后面加 nulls first 则排在最前)。
--limit <n> 默认 100,截到 10000。
--distinct 去掉投影值完全相同的行(SELECT DISTINCT),用于从事实表上读 ID 名单。
--param NAME=VALUE 绑定查询读到的固定粒度字段的 base 参数(可重复,每个参数一个值,多选参数是一组值 NAME=V1,V2)。见固定粒度字段。

三个值得记住的行为:

  • 输出列名去掉根前缀,其余用 __ 连接:orders.amount 是 amount, customers.name 是 customers__name。
  • 一对多方向的穿越会被拒绝,而不是悄悄产生重复行。问 --from customers --fields orders.order_id 会返回 detail_fanout, 并给出应该改用的根。
  • 两条关系路径都能抵达同一字段时,用关系前缀点名想要的那条 —— ambiguous_join_path 的 suggested_retry 会把两种写法直接打出来。 同样的前缀在 query --group-by 里也能用。

dosi explain

接受与 query 相同的 query spec 参数,但停在逻辑计划这一步,不生成 SQL。 适合在挑定方言之前,用来理解连接路径、扇出分支归属和粒度处理。

$ dosi explain --model $DOSI_EXAMPLES/tpcds/model.yaml \
    --metrics customer_lifetime_value --group-by store.s_state

计划以文本渲染,其中包含每个 JOIN 的类型(left / inner), 据此可以确认 Datus 的 join_type 扩展是否生效。 这里的 --format json 只作用于错误路径,成功的计划只有文本形式。

dosi attribute-metrics 和 dosi attribute-dimensions

解释指标在两个 [start, end) 时期之间的变化。attribute-metrics 按指标的公式拆,attribute-dimensions 按 --dimensions 里字段的分组拆。需要的查询都由命令自己执行。返回内容与解读方式见指标归因。

$ dosi attribute-metrics --model model.yaml \
    --metric avg_order_value \
    --baseline 2025-01-01..2025-02-01 --current 2025-02-01..2025-03-01 \
    --db warehouse.duckdb
$ dosi attribute-dimensions --model model.yaml \
    --metric avg_order_value --dimensions customers.region,orders.status \
    --baseline 2025-01-01..2025-02-01 --current 2025-02-01..2025-03-01 \
    --db warehouse.duckdb

时期是 START..END 的 ISO 区间,默认在指标自己的时间轴上,--time-dimension 可以换一个。--where、--context-filter、--param、--group-by 与指标查询的同名参数相同;--group-by 是指标按什么粒度计算,不是按什么拆变化。--dimensions 写多个字段时是一条下钻路径,逐层拆;--top-groups 设定结果列出多少个分组(默认 20)。--request FILE(- 表示标准输入)以 JSON 给出整个请求,代替这些参数。--connection/--db 选择数仓,与 query --execute 完全一致;--dry-run 编译全部语句但不发送。结果是 JSON;请求本身不成立时,在 stderr 输出 code 和 field_path,退出码为 1。

原来的 dosi attribute 命令在移除之前仍可运行,会打印过期警告,见从 attribute 迁移。

dosi lineage

指标血缘图——物理表 → 数据集 → 原子指标 → 派生指标,加载了 ontology 时还有它的概念层—— 以 JSON 输出,或渲染成一个可以直接打开的页面。图里有什么见指标血缘。

$ dosi lineage dump --model model.yaml > graph.json
$ dosi lineage view --mapping mapping.yaml

dump 打印图的 JSON(--out <path> 写到文件;契约本身就是 JSON,--format 对它不起作用)。 view 生成一个自包含的 HTML 页面并用默认浏览器打开;--out <path> 指定页面位置, --no-open——或者机器上没有浏览器——则改为打印文件路径,退出码仍为 0。 页面不需要网络,通过 file:// 就能打开。

两者都接受 --redact-sql:把每一段 SQL 文本和不透明的扩展负载替换成 "<redacted>", 图的形状不变,用于分享模型结构而不暴露表达式。--osi-basic 按严格 OSI 编译, 并在输出上标记 "mode": "basic"。

dosi migrate conf

把你已经为 dbt(以及读同一份 profiles.yml 的 MetricFlow)或 Cube(.env)配好的数仓连接, 转换成 dosi-connections.yaml。不需要模型。

$ dosi migrate conf
found: dbt  /home/me/.dbt/profiles.yml
  ✓ analytics.dev                snowflake   default
  ⚠ analytics.prod               snowflake   needs SNOWFLAKE_PROD_KEY_PASS
  ✗ analytics.sso                snowflake   unsupported_auth: target analytics.sso authenticates with browser SSO (authenticator), ...
wrote dosi-connections.yaml (gitignored)
参数 含义
--from dbt\|cube 只读一种工具(metricflow 是 dbt 的别名)。默认:存在的都读
--detect 只报告会迁移什么,不写文件
--project-dir <dir> dbt_project.yml、profiles.yml、.env 所在目录(默认当前目录;不会向上查找)
--out <path> 要写入或合并的文件(默认 dosi-connections.yaml)

报告从不打印任何字段的值——不打印密码,连 host 也不打印——只有连接名、类型、状态、 未设置的环境变量的名字和原因。值本身怎么处理,见 连接器 → 从 dbt 或 Cube 迁移。--format json 时:

{
  "sources": [{"kind": "dbt", "path": "/home/me/.dbt/profiles.yml"}],
  "connections": [
    {"name": "analytics.dev", "dialect": "snowflake", "source": "dbt", "status": "ok",
     "missing_env": [], "code": null, "reason": null, "default": true}
  ],
  "written": "dosi-connections.yaml",
  "gitignored": true
}

status 为 ok、missing_env(已写入;设好列出的变量即可)或 unsupported (不写入;code 为 unsupported_auth、unsupported_dialect 或 unsupported_config)。 某个来源有一部分无法迁移时(比如写在代码里的 Cube driverFactory),它会带一条 note。 --detect 下 written 为 null。--from 指定的来源不存在时以 source_not_found 退出,退出码 1。

dosi connection

连接配置文件里的连接。两个子命令都不需要模型,也都不打印字段值。

$ dosi connection list
file: dosi-connections.yaml
  ✓ analytics.dev                snowflake   default
  ⚠ analytics.prod               snowflake   needs SNOWFLAKE_PROD_KEY_PASS
$ dosi connection test analytics.dev
✓ connected analytics.dev (snowflake, 812 ms)

list --format json 每个连接输出一个对象:name、dialect、source_file、default、 available、missing_env 和 code(missing_env、invalid_config 或 null)。

test <name> 建立连接并执行 SELECT 1;--format json 时输出 {"name", "dialect", "ok": true, "latency_ms"}。失败时退出码为 1,stderr 上是一个 JSON 错误 {code, message, hint, fields?, missing_env?, candidates?}。message 和 hint 都是 dosi 自己的措辞: 驱动或解析器的原始消息从不转发,因为它们会引用字段值(带密码的 uri、host); 改由 fields 列出涉及的配置键。 code 说明下一步该做什么:

code 含义
missing_env 配置引用的环境变量没有设置;missing_env 列出它们
auth_failed 数仓拒绝了凭据
network_blocked 进程根本无法解析域名或建立连接——通常是 agent 沙箱没有网络权限
connection_failed 连不上数仓(被拒绝、host 写错、DuckDB 文件不存在)
timeout 超时无响应
unsupported_dialect 当前构建没有该 type 的连接器
invalid_config 配置解析失败
connection_not_found 没有这个名字;candidates 列出最接近的几个
结果始终是 JSON。

dosi workload check

实验性功能:JSON 以后可能增加字段。

把已有的 SQL 对着模型读一遍。对每条语句回答:同样的结果能不能用 dosi query 或 dosi select 查出来;不能时,模型缺什么。

$ dosi --model model.yaml workload check queries/ --dialect duckdb
answerable  queries/sales_by_region_month.sql
  dosi query --metrics sales --group-by stores.region,order_items.order_date:month --where 'stores.store_id IS NOT NULL'
needs_metric  queries/region_pivot_by_month.sql
  add metric east_sales, over sales
  dosi query --metrics east_sales,sales --group-by order_items.order_date:month
unsupported  queries/aov_avg_of_orders.sql
  note aggregate_over_aggregate: the block aggregates an aggregated input

additions to the model
# metric east_sales, used by 1 statement(s)
- name: east_sales
  expression:
    dialects:
    - dialect: ANSI_SQL
      expression: SUM(CASE WHEN stores.region = 'East' THEN order_items.amount END)

3 statements: 1 answerable, 1 needs_metric, 0 needs_model, 1 unsupported
判定 条件 返回什么
answerable 每个聚合都是模型里的指标,分组、过滤、排序和截断能写成一个查询 查询
needs_metric 表、列、连接都在模型里,但其上的某个聚合不在 指标的模型 YAML,以及用到它的查询
needs_model 有列、分组表达式、连接或表没有声明 字段、关系或数据集的模型 YAML,以及补上之后的查询
unsupported 语句超出了目前能读的范围 原因码

参数是 SQL 文件,或者目录(在其中查找 .sql 文件)。一个文件里有多条语句时逐条检查 (script.sql#2)。INSERT … SELECT、CREATE TABLE … AS 和 CREATE VIEW … AS 按它写入的那个查询来读。

比较的是语句算出了什么,不是它怎么写。连接写成 ON、USING、逗号加 WHERE、派生表、 CTE、IN (SELECT …) 还是相关的 EXISTS,都是同一条关系;模型把指标写成一个表达式, 还是写成对其他指标的 derive,都能匹配上。STRFTIME(d, '%Y-%m') 和 DATE_TRUNC('month', d) 都是月粒度的时间字段。没有聚合的 GROUP BY 返回的是去重后的键, 落到带 distinct 的 dosi select 上。

只有被连接的一侧在连接列上唯一时,连接才读作关系:模型用 primary_key、unique_keys 或一条已有的关系来说明这一点。内连接还会丢掉没有匹配的行,而关系不会,所以查询里会带上 表达这一点的条件(上面的 stores.store_id IS NOT NULL)。--facts 可以去掉它。

选项 含义
--dialect SQL 的方言。默认取 --connection 的;否则取 default: true 的连接的;否则 duckdb
--facts <file> 模型没法声明的、关于表的事实(见下)
--execute 在连接上分别执行语句和它的查询,比较结果行。有一对不相等时退出码为 1
--connection、--db --execute 在哪里执行,与 dosi query 相同

事实文件列出数仓保证、而模型里没有位置写的性质。有外键且键列非空时,内连接不需要额外的条件; 键列可空时,条件收窄为「键不为空」。

not_null:
  - {table: fact_order_item, columns: [store_id, amount, discount]}
foreign_keys:
  - {table: fact_order_item, columns: [store_id], references: dim_store, ref_columns: [store_id]}

--format json 输出 {summary, additions, statements}。每条语句有:

字段 内容
statement 文件名;脚本里的第 n 条语句带 #n
verdict answerable、needs_metric、needs_model 或 unsupported
plane、query metrics 加一个指标查询的 JSON,或 select 加一个明细查询的 JSON:可以原样交给 REST API、Python 的 Engine 和 MCP 工具。有 additions 时,查询假定它们已经加进模型
columns SQL 的每个输出列对应查询结果的哪一列:{sql, query};SQL 把期间写成文本(%Y-%m)而查询返回期间首日时带 format;不读任何行的列带 constant
additions {kind, name, dataset?, yaml, based_on?, used_by}:每项是模型 YAML 的一个列表元素。顶层的 additions 把每项列一次,并列出所有需要它的语句
equivalence keys:same、empty_groups 或 subset;values:same 或 null_zero(把 NULL 和 0 看作同一个值时相等,例如 SUM(CASE … ELSE 0 END) 对上一个带过滤的指标)。在除法里,分母为 0 的组一侧是 NULL、另一侧是 NaN 或除零错误;可能出现这种情况时 detail 会写明
proof 用到的改写定律和事实,每条事实带来源
needs_facts 成立的话能化简查询的事实,各带一条 probe_sql:恰在事实不成立时返回一行
executed rows_equal、rows_differ、error 或 not_run
reason、detail 语句为什么是 unsupported:原因码和文字说明

每个结果都满足两条,引擎自己的测试检查的也是这两条:把 additions 加进模型后再检查, 得到 answerable;查询返回的行在声明的 equivalence 下等于语句返回的行。

目前还不能读的形态,各有原因码:对聚合子查询再聚合(aggregate_over_aggregate)、 聚合子查询之间或与明细行的连接(join_of_aggregates)、窗口函数(window_function)、 UNION(set_operation)、会放大行数的连接(fanout_join)、NOT IN / NOT EXISTS 以及对没有已知键的行集做的测试(subquery_test)、标量子查询(scalar_subquery)、 去重(dedupe)。

因为查询会返回不同的行而拒绝的:

  • aggregate_off_main:在主表的行上聚合被连接表的列,例如 facts f JOIN dims d 上的 SUM(d.w)。指标在它自己的数据集上聚合,每行只算一次。
  • integer_division:在整数相除会截断的方言上(PostgreSQL、Trino、Redshift 等) 两个聚合之间的 /,且两侧都没有转换成带小数的类型。指标的比率保留小数。
  • unread_clause:* EXCLUDE、* REPLACE 和 * RENAME,以及 QUALIFY、OFFSET 等查询里没有位置的子句。
  • query_surface:引擎不接受的查询,例如既没有指标也没有字段。每个打印出的查询都先编译, 通过了才报告。

输出格式

--format 接受三个值之一:

  • text(默认):面向人,结果行/列表是对齐的表格,编译结果是原始 SQL, 计划是缩进的树。NULL 单元格以灰显渲染。颜色会自动探测终端。
  • json:所有输出(以及所有错误)都是机器可读的。query 的编译结果是 {dialect, sql};--execute 会再加上 {columns, rows: [{col: val}], …}; validate 是 {issues, compile_errors};list 是一个对象数组。 错误带有稳定的 code、涉及到的名字、当一个错误引用存在备选时给出的 candidates,以及当某种改写能成功时给出的 suggested_retry, Agent 类调用方无需解析自然语言就能自我纠正。稳定 API 是错误码,不是错误文本。
  • arrow:在 stdout 上输出一个 Arrow IPC 流,仅用于 query --execute(其它命令会报错:--format arrow only applies to 'query --execute')。结果批次从数仓适配器直通 stdout,不做行物化, 可以零 JSON 解析地管进 DuckDB、Polars 或 pyarrow。需要支持 Arrow 的构建 (默认构建,或任意 exec-*-arrow / exec-flightsql / exec-duckdb feature; 一个不含这些 feature 的 --no-default-features 构建会在运行时拒绝 --format arrow)。
# Stream results into DuckDB for further analysis
dosi query --model model.yaml --metrics revenue --group-by orders.status \
    --execute --connection prod-ch --format arrow \
    | duckdb -c "SELECT * FROM read_arrow('/dev/stdin')"

# Or into Polars
dosi query ... --execute --format arrow \
    | python -c "import polars as pl,sys; print(pl.read_ipc_stream(sys.stdin.buffer))"

在数仓上执行

--execute 会执行编译出的 SQL 并打印结果行。不指定连接就用本地 DuckDB, 默认进程内、原生 Arrow(内置的 exec-duckdb);--db <file> 指向 DuckDB 文件,不指定则用内存库。带上 --connection <name>, 则指向该配置对应的数仓和方言。

$ dosi query --model model.yaml --metrics revenue --group-by orders.status \
    --execute --connection prod-sr

连接配置沿用 Datus agent.yml 的 datasources: 词汇表。可以把 --connections 指向一份完整的 agent.yml(读取 services.datasources),或一份独立的 datasources: 文件。不带该参数时, 按以下顺序发现该文件:DOSI_CONNECTIONS 环境变量 → ./dosi-connections.yaml → ./osi-connections.yaml → ~/.config/dosi/connections.yaml → ~/.config/osi/connections.yaml, 改名之前的 osi- 路径仍然有效。Datus 的 agent.yml 只有用 --connections 指定时才会读。密钥以 ${VAR} 的形式从环境变量插值。

datasources:
  prod-sr:
    type: starrocks
    host: sr.internal
    port: 9030
    arrow_flight_port: 9408      # opt into Arrow Flight SQL (SR ≥3.5.1)
    username: osi
    password: ${SR_PASSWORD}
    database: analytics
    default: true                # used by --execute without --connection
  prod-ch:
    type: clickhouse
    uri: http://ch.internal:8123
    username: default
    database: analytics

解析规则:

  • --execute 不带 --connection 时用标了 default: true 的那份配置; 一份都没标就退回本地 DuckDB(--db 或内存)。标了 default: true 却解析失败的配置(比如 ${VAR} 没设置)会在 stderr 上告警, 而不是悄悄用一个空的 DuckDB。
  • --dialect 与 --connection 同时使用时,方言必须与配置一致, 否则命令报错。去掉 --dialect,让配置来决定就行。

从源码构建时,数仓驱动是按 feature 开关的,所以自己编出来的可执行文件 只带上你点名要的那些(官方发布版则全都带上)。按需构建(或直接用 exec-all):

Feature 引擎 结果通路
exec-duckdb(默认) DuckDB(进程内) 原生 Arrow
exec-mysql MySQL、TiDB、StarRocks、Doris(MySQL 协议) 行
exec-postgres Postgres 行
exec-hologres Hologres(Postgres 协议;隐含 exec-postgres) 行
exec-dws 华为云 DWS(Postgres 协议;隐含 exec-postgres) 行
exec-gaussdb GaussDB / openGauss(原生 SHA256 认证驱动) 行
exec-oracle Oracle Database(ODPI-C;运行时需要 Instant Client) 行
exec-http ClickHouse、Trino 行
exec-http-arrow ClickHouse FORMAT ArrowStream 原生 Arrow
exec-flightsql StarRocks / Doris 的 Arrow Flight SQL(arrow_flight_port:) 原生 Arrow
exec-snowflake Snowflake(SQL API v2 + 密钥对 JWT) 行
exec-bigquery BigQuery(jobs.query REST + 服务账号 JWT) 行

各引擎的配置方式与 Arrow 结果通路的支持状态见 connectors.md 和 arrow.md。

另请参阅

  • semantics.md:CLI 所编译到的那份规范性行为契约 (指标推断、连接、扇出保护、时间处理)。
  • rest-api.md:同样的能力,通过 HTTP 提供。
  • datus-extensions.md:可选的 Datus 模型扩展 (join_type、fill_nulls_with、time_dimension、time_granularity、 time、dataset,以及几个较大的扩展);版本策略见 扩展版本。
  • connectors.md:数仓连接器的配置。
  • arrow.md:如何启用 Arrow 结果传输,以及哪些环节会变快。