跳转至

运行你的第一个指标查询

本教程直接用 dosi 命令行,不经过 Agent。大约十分钟:先看内置的 orders 模型定义了 什么,把一个查询编译成两种数仓的 SQL,再把示例数据导入本地 DuckDB 文件,执行查询并核对 数字。每一步都给出预期输出。想通过对话让编程 Agent 来做,见快速上手。

orders 样例有 4 张表(customers、orders、products、order_lines)、7 个指标、 41 笔订单。

开始之前

  • Dosi,按手动安装装好。第 1 到 5 步只需要它。
  • DuckDB 命令行,第 6 步导入示例数据时用。 查询由 Dosi 自己执行,用的是内置的 DuckDB;精简版则改用这个命令行执行。

把 DOSI_EXAMPLES 指向内置样例,并在一个新目录里操作:

export DOSI_EXAMPLES=~/.local/share/dosi/examples
mkdir orders-tutorial && cd orders-tutorial

这是安装脚本放样例的位置。手动解压的发布包,改用其中的 examples/ 目录;两种情况下 dosi info 都会打印出这个路径。如果结果和下文不一致,说明样例来自旧版本,重新运行一次 安装脚本即可。

第 1 步 — 看模型提供了什么

dosi list metrics --model "$DOSI_EXAMPLES/orders/model.yaml"
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)。查看单个指标的完整定义:

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
time: metric_time (day, week, month, quarter, year)

group_by 列出可以用来拆分 revenue 的数据集。按不在列表里的数据集拆分会怎样,见第 9 步。

第 2 步 — 确认模型有效

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

validate 检查模型结构、名称是否唯一、每条关联是否指向真实字段,以及每个指标能否编译。 以后自己写模型,每改一次就跑一次。

第 3 步 — 看能按什么分组

dosi list dimensions --model "$DOSI_EXAMPLES/orders/model.yaml"
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
status     revenue   order_count
cancelled  10        1
completed  23825.49  39
pending    0         1
3 rows

--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
revenue   order_count  avg_order_value
23835.49  41           581.3534146341464
1 row

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
category  line_count
books     28
toys      25
2 rows

下一步

  • 查询指标:dosi query 的全部选项,包括过滤、行数限制、时间窗口和输出格式。
  • 查询明细:dosi select 走同一个模型,返回明细行而不是汇总。
  • 连接数仓:在自己的数据库上跑同样的查询。
  • LOD 和五个电商问题:自己固定粒度的指标。
  • 快速上手:让编程 Agent 为你的数据建模,并通过模型回答问题。