运行你的第一个指标查询¶
本教程直接用 dosi 命令行,不经过 Agent。大约十分钟:先看内置的 orders 模型定义了
什么,把一个查询编译成两种数仓的 SQL,再把示例数据导入本地 DuckDB 文件,执行查询并核对
数字。每一步都给出预期输出。想通过对话让编程 Agent 来做,见快速上手。
orders 样例有 4 张表(customers、orders、products、order_lines)、7 个指标、
41 笔订单。
开始之前¶
- Dosi,按手动安装装好。第 1 到 5 步只需要它。
- DuckDB 命令行,第 6 步导入示例数据时用。 查询由 Dosi 自己执行,用的是内置的 DuckDB;精简版则改用这个命令行执行。
把 DOSI_EXAMPLES 指向内置样例,并在一个新目录里操作:
这是安装脚本放样例的位置。手动解压的发布包,改用其中的 examples/ 目录;两种情况下
dosi info 都会打印出这个路径。如果结果和下文不一致,说明样例来自旧版本,重新运行一次
安装脚本即可。
第 1 步 — 看模型提供了什么¶
NAME KIND DATASETS DESCRIPTION
revenue aggregate orders Total order amount
order_count aggregate orders Number of orders
unique_customers aggregate orders Distinct purchasing customers
avg_order_value ratio orders Revenue per order (ratio)
total_margin expression order_lines, orders Revenue minus cost (expression over two aggregates)
line_count aggregate order_lines
line_product_margin expression order_lines, products
每个指标在 model.yaml 里只定义一次,写成基于数据集的 SQL。KIND 这一列没有人声明过,
是 Dosi 从表达式推断出来的:聚合型(aggregate)、两个聚合相除的比率型(ratio),或者
组合多个聚合的表达式型(expression)。查看单个指标的完整定义:
metric: revenue
description: Total order amount
kind: aggregate
expr: SUM(orders.amount)
datasets: orders
group_by: orders, customers
time: metric_time (day, week, month, quarter, year)
group_by 列出可以用来拆分 revenue 的数据集。按不在列表里的数据集拆分会怎样,见第 9 步。
第 2 步 — 确认模型有效¶
validate 检查模型结构、名称是否唯一、每条关联是否指向真实字段,以及每个指标能否编译。
以后自己写模型,每改一次就跑一次。
第 3 步 — 看能按什么分组¶
NAME TIME DIM SOURCE DESCRIPTION
customers.region yes inferred
customers.signup_date time yes inferred:time
orders.order_date time yes inferred:time
orders.status yes inferred
products.category yes inferred
customers.customer_id no inferred:primary_key
order_lines.cost_amount no inferred:measure
order_lines.line_amount no declared
order_lines.line_id no inferred:primary_key
order_lines.order_id no inferred:foreign_key
order_lines.product_id no inferred:foreign_key
order_lines.qty no declared
orders.amount no inferred:measure
orders.customer_id no inferred:foreign_key
orders.order_id no inferred:primary_key
products.product_id no inferred:primary_key
products.unit_cost no declared
DIM 为 yes 的字段用于分组和过滤;键和金额字段也会列出,标为 no。字段名一律是
数据集.字段,--group-by 和 --where 都用这个全名。time 字段还可以带粒度,例如
orders.order_date:month。
第 4 步 — 把第一个查询编译成 SQL¶
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue --group-by orders.status --pretty
SELECT
orders.status AS status,
SUM(orders.amount) AS revenue
FROM orders AS orders
GROUP BY
orders.status
按名字要一个指标,SQL 由 Dosi 写出来。不加 --execute 只编译,这一步不需要数据库。
第 5 步 — 换数仓,模型不动¶
按月看销售额,编译成 MySQL 的 SQL:
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue --group-by orders.order_date:month --dialect mysql --pretty
SELECT
STR_TO_DATE(DATE_FORMAT(orders.order_date, '%Y-%m-01'), '%Y-%m-%d') AS order_date__month,
SUM(orders.amount) AS revenue
FROM orders AS orders
GROUP BY
STR_TO_DATE(DATE_FORMAT(orders.order_date, '%Y-%m-01'), '%Y-%m-%d')
换成默认的 --dialect duckdb 再跑一次,月份就变成 DATE_TRUNC('MONTH', orders.order_date)。
请求和模型都没变,变的只是 SQL。--dialect 只影响生成的 SQL 文本,这一步并不连接 MySQL。
所有方言见连接数仓。
第 6 步 — 真正执行¶
把示例数据导入一个新的 DuckDB 文件,然后加上 --execute:
duckdb orders.duckdb < "$DOSI_EXAMPLES/orders/seed.sql"
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue,order_count --group-by orders.status --order status \
--execute --db orders.duckdb
--execute 在 --db 指定的数据库文件上执行编译出的 SQL。连真正的数仓时改用
--connection <名称>,见连接数仓。加 --format json 可以拿到
便于程序处理的结果。
seed 只导入一次,而且要导入新文件。重复导入时 DuckDB 会报表已存在,但每一行仍会再插入一遍,
所有数字都翻倍;遇到这种情况,删掉 orders.duckdb 重新导入。示例数据刻意做得和真实数据
一样不规整:有的订单没有客户,有的客户没有地区,订单有三种状态。
第 7 步 — 按时间拆分¶
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue --group-by orders.order_date:month \
--start-time 2024-01-01 --end-time 2024-04-01 \
--order order_date__month --execute --db orders.duckdb
order_date__month revenue
2024-01-01 00:00:00 2059
2024-02-01 00:00:00 1059
2024-03-01 00:00:00 33
3 rows
--start-time 和 --end-time 限定指标的时间轴,这里就是下单日期。区间左闭右开,所以是
1 月到 3 月。月份列名为 order_date__month,即字段名加粒度,--order 用的就是这个输出列名。
第 8 步 — 试一个比率型指标¶
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue,order_count,avg_order_value --execute --db orders.duckdb
avg_order_value 是 SUM(orders.amount) / COUNT(orders.order_id),旁边两列可以直接验算:
23835.49 ÷ 41 = 581.35…。Dosi 先在查询粒度上算出两个聚合再相除,所以无论怎么分组,比率
都是对的。
这个总数包含了已取消和待处理的订单。模型里的 revenue 没有状态过滤,查询不主动加就不会有:
只算已完成订单,加上 --where "orders.status = 'completed'"。业务过滤要写在模型或查询里,
不能靠猜。
第 9 步 — 要一个会重复计数的拆分¶
按商品类目拆分销售额:
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics revenue --group-by products.category --execute --db orders.duckdb
error: FanOutRisk: metric "revenue" aggregates Sum over dataset "orders", which has no many→one path to ["products"]; evaluating a duplicate-sensitive aggregate (SUM/AVG/COUNT) across that join would double-count rows
hint: group by dimensions reachable from the metric's dataset, or restate the metric with a duplicate-insensitive aggregate (COUNT DISTINCT/MIN/MAX)
一笔订单可以包含多种商品,从 orders 经 order_lines 关联到 products,每笔订单会按
明细行数重复出现,SUM(orders.amount) 就会多算。这正是第 1 步 group_by 里只有
orders, customers 的原因。Dosi 不返回虚高的数字,而是拒绝并说明原因,这就是扇出保护
(fan-out protection)。定义在订单明细上的指标可以按类目拆分:
dosi query --model "$DOSI_EXAMPLES/orders/model.yaml" \
--metrics line_count --group-by products.category \
--order category --execute --db orders.duckdb