Apache Ossie 是什么?为什么用 Dosi?¶
Apache Ossie(原名 Open Semantic Interchange,简称 OSI)是一个开放规范,用于在 BI 工具、AI Agent 和数据平台之间交换语义模型、指标、维度和业务上下文。
一份 Ossie 模型就是一个普通 YAML 文件。指标在里面定义一次,所有支持 Ossie 的工具 读的都是这同一份定义,不再各自重写。Dosi 是首个 Apache Ossie 原生的语义层引擎:加载 Ossie 模型,按上游规范校验,再把指标请求编译成 20 种数仓方言各自正确的 SQL。
Apache Ossie 速览¶
| 是什么 | 开放、厂商中立的语义模型规范 |
| 原名 | Open Semantic Interchange(OSI) |
| 格式 | YAML(或 JSON) |
| 描述内容 | 数据集、关系、字段与维度、指标,以及各对象上的 AI 上下文 |
| 交给引擎的部分 | 怎样把指标变成某个数仓上正确的 SQL |
| 上游 | ossie.apache.org 与 apache/ossie:核心规范和参考校验器;格式转换器在 apache/ossie-converters |
| 本站的引擎 | Dosi:校验、编译并执行 Ossie 模型 |
Dosi 支持 Ossie 0.3.0.dev0。首次打开 0.2.0.dev0 的模型、本体或映射文件时,Dosi 会原地升级。通过 Python 或 REST 传入的文本只在内存中升级。共享这些文件的应用应一起升级。新模型可用 expression.sql 编写可移植表达式,厂商扩展以对象形式写入 nonportable_extensions。聚合的 FILTER (WHERE ...) 仍未支持。需要按条件求和时,可以使用 SUM(CASE WHEN … THEN amount END)。
问题:人人都在重新定义"营收"¶
从头写一句"8 月营收"的 SQL,至少有三处会出错:JOIN(营收在哪张表,连上
以后会不会扇出、把总数悄悄翻倍)、维度(按下单日期还是发货日期,算毛额
还是净额,日粒度还是月粒度)、表达式(是 SUM(amount),还是从明细表算
SUM(unit_price * quantity)——却漏了折扣列,还是要用
SUM(CASE WHEN status != 'refunded' THEN amount ELSE 0 END) 才能扣掉退款)。
任何一处出错,算出来的数字看着照样像那么回事。
这正是 BI 看板、财务报表、手写查询算出三个不同"营收"的原因:一处过滤了 已取消订单,另一处没过滤,第三处 JOIN 了一张表、把总额悄悄翻倍。AI Agent 拿着裸表名写查询,也会犯一模一样的三种错误,只是更快、更有把握。结果大家 都熟悉:两个都"正确"却对不上的数字,外加一场"该信哪个"的会。
语义模型的解法是把每个指标只定义一次:revenue 是什么意思、来自哪张表、
表与表如何关联,作为唯一事实来源。之后所有查询都从这份定义派生,不再各写各的。
Apache Ossie 就是把这份模型写下来的一种开放、标准的方式。
Apache Ossie 模型长什么样¶
模型里列出数据集(表)及其字段、表与表之间的关系,以及用普通 SQL 表达式 写成的指标。下面这份是完整、合法的模型:
version: "0.3.0.dev0"
name: orders_model
description: Orders, the customers who placed them, and revenue
datasets:
- name: orders
source: main.orders
primary_key: [order_id]
fields:
- name: order_id
expression:
sql: order_id
- name: customer_id
expression:
sql: customer_id
- name: order_date
expression:
sql: order_date
dimension:
is_time: true
- name: amount
expression:
sql: amount
- name: customers
source: main.customers
primary_key: [customer_id]
fields:
- name: customer_id
expression:
sql: customer_id
- name: region
expression:
sql: region
relationships:
- name: orders_to_customers
from: orders
to: customers
from_columns: [customer_id]
to_columns: [customer_id]
metrics:
- name: revenue
description: Total order amount
expression:
sql: SUM(orders.amount)
ai_context:
synonyms: [sales, order revenue]
- 数据集与字段:对应物理表,以及可以分组、过滤的列;
dimension: {is_time: true}标记时间维度。 - 关系:说明表怎么 JOIN,消费方不用再猜关联键。
- 指标:基于这些字段的 SQL 聚合表达式,只写一次。
ai_context:业务上下文(同义词、说明、示例),给读模型的 AI Agent 用。
Ossie 描述的是指标是什么。至于怎么把它们变成某个数仓的正确 SQL,规范刻意不管。 这正是 Dosi 要补的那块。
一个文档一个模型¶
一个文档只放一个语义模型:version 和模型自己的字段都直接写在文档根上,就像上面
的示例。上游 schema 从 apache/ossie#383
起只认这种写法。
Dosi 在正常加载历史模型文件时,会自动转换为根结构并覆盖文件。替换采用原子写入,
不在模型旁留下备份或锁文件;需要保留原始排版的,请先纳入版本管理。加载新版结构的模型时,
旧版本留在旁边的隐藏 .bak 和 .dosi.lock 文件也会被删除;解析不了的文件会保留它们。
已经是新版的文件不会重写。新建模型和文本输入
(包括 REST/MCP 验证与 Python model_text)都必须使用根结构。
历史文件无法写回、包含多个模型、字段冲突,或无法保证转换后字段值不变时,会报错并 保留原文件。文件安全转换后,仍可能存在模型校验或编译错误,此时直接编辑新版文件 修复。自动转换需要模型目录的写权限,不需要单独执行迁移命令。
是交换标准,不只是一种格式¶
原名里的 Interchange(交换)依然是关键:上游 Apache Ossie 项目维护着 Ossie 与其他 语义层格式之间的双向转换器 —— dbt、Snowflake、Databricks、Salesforce/Tableau、GoodData、Honeydew、Omni 等。一个中立的枢纽,省掉格式之间两两点对点的迁移。
Dosi 直接读取标准 Ossie 模型,只要指标是 SQL 表达式(见 S-EXPR-1), 转换器的产出拿来就能用:模型今天可以从 dbt 转进来, 明天再转去 Snowflake,指标定义不会被扣在任何一家的格式里。定义一次,自由迁移。
Dosi 与 Apache Ossie 的关系¶
Apache Ossie 是契约,Dosi 是执行它的引擎。Dosi 没有自己的模型格式:输入就是 Ossie 模型;它额外提供的能力,要么发生在查询时,要么放在规范自带的扩展点里。
| Apache Ossie 定义 | Dosi 补充 |
|---|---|
| 数据集、关系、字段,以及用 SQL 表达式写的指标 | 带扇出保护的 JOIN 规划,20 种方言的 SQL |
| 参考校验器 | dosi validate --osi-basic 在自身检查之外一并运行它 |
nonportable_extensions,规范的厂商扩展点 |
Datus 扩展(窗口、派生指标、JOIN 类型、空值填充、时间粒度)就放在里面 |
| 每个对象上的 AI 上下文 | 原生 MCP 服务,把模型提供给 Agent,错误结构化 |
| 与其他格式互转的转换器 | 指标为 SQL 的转换结果原样作为输入 |
Dosi 有两种模式,每次调用时选择:
- 基础模式(
--osi-basic):严格的标准 Apache Ossie,模型的含义与规范完全一致; Datus 扩展忽略并给出警告。 - Datus 模式(
--osi-datus,默认):Apache Ossie 加上 Datus 扩展。
Datus 扩展都放在 nonportable_extensions 里,不会让模型变得不合法:其他 Ossie 工具照样
能读,不认识的扩展直接跳过。但 Datus 模式有一点比规范宽松:它还接受 POSTGRESQL
这类核心规范没有定义的厂商 SQL 方言标签。模型需要给其他 Ossie 工具使用时,请用
dosi validate --osi-basic 校验。
Dosi 由 Datus 开发,实现了 Apache Ossie 规范,但本身不是 Apache 软件基金会的项目。
Dosi 做什么¶
Dosi 是一个小巧快速的 Rust 引擎,读一份纯 Apache Ossie 模型,把一次指标请求变成对应数仓的 正确 SQL,还可以顺手执行:
flowchart LR
A["你的 Apache Ossie 模型<br/><small>指标只定义一次</small>"] --> B["Dosi"]
B --> C["正确的 SQL<br/><small>面向你的数仓</small>"]
C --> D["结果"]
给出一个指标、几个分组维度、一种数仓方言,剩下的 JOIN、聚合,以及那个方言特有的 SQL 写法,都由 Dosi 算出来。同一份模型可以为 20 种方言生成正确 SQL: DuckDB、Postgres、MySQL、ClickHouse、Snowflake、BigQuery、StarRocks、Trino、 Databricks、Oracle 等。换数仓改一个参数,指标定义不动。
用法有四种:命令行工具、REST + Arrow 服务、面向 AI Agent 的原生 MCP 服务、Python 绑定。底下是同一个引擎,给出同样的答案。
AI Agent 需要指标体系回答什么¶
当指标的消费者从看板前的人变成 AI Agent,过去靠分析师经验拿捏的问题, 指标层必须给出明确答案。每个指标有四个属性,决定了它能被怎样安全地使用:
- 可加(additive) —— 能否沿某个维度直接求和,还是一加就重复计数 (去重计数、比率)?
- 可上卷(rollable) —— 日粒度的值能否直接卷成月值,还是必须从明细重算?
- 可预测(predictable) —— 是可以外推预测的流量,还是外推毫无意义的存量?
- 无扇出(fan-out-safe) —— JOIN 会不会让行数翻倍、总数虚高?
Dosi 把这些当作引擎必须掌握的属性,而不是分析师脑子里的约定。目前它会推断 每个指标的类型(聚合型 / 比率型 / 表达式型),并且绝不悄悄重复计数: 当一个指标要 JOIN 不同明细层级的表 —— 也就是会把营收翻倍的经典扇出 —— 要么各部分在各自粒度上正确计算,要么带着结构化错误停下。 它不会把一个虚高的总数交给你。
内置归因:Agent 问"营收为什么跌了",一次调用按指标的公式拆变化, 另一次按任意字段的分组拆。每一部分都得到它的 Shapley 贡献,各部分贡献加起来等于总变化, 推理过程可观察、可核对,而不是幻觉。
在生成侧,datus-agent(Datus 自家的开源数据 Agent)是目前最好的一方选择:它能直接产出符合 Dosi 规范、带 Datus 扩展的 Apache Ossie YAML —— 扩展里有更高级的窗口与 派生指标,以及比基础规范更完整的 JOIN 关系检测。消费侧保持开放:任何 Agent 都能通过 MCP 服务查询,比如在 Claude Code 或 Codex 里通过 Dosi 插件查询。
这些数字凭什么可信¶
除了上面的指标代数,引擎还挡住了日常制造"对不上的数字"的错误:
- 时间范围没有歧义。 2024 年 1 月 表示
[2024-01-01, 2025-01-01), 含起始、不含结束,月份边界上的天数不会被算两次。 - 错误会告诉你怎么修。 指标名写错,换来的不是一段堆栈,而是一条列出最接近选项的
提示。
--format json下每个错误都带稳定错误码和修复建议,自动化工具和 AI Agent 据此就能自我纠正。
这些保证都精确写进了一份规范性契约,见语义契约。 不读也能用 Dosi;想确切知道引擎承诺了什么,再去查也不迟。
适合谁¶
- 分析与数据工程师 —— 想要一份指标定义,在每个数仓、每个消费端都保持正确。
- 正在迁移或多数仓并存的团队 —— 不愿为每个引擎重写一遍指标 SQL。
- 以 Apache Ossie 为标准的团队 —— 需要一个直接运行现有模型的引擎,中间不夹私有格式。
- 数据应用与 AI Agent 的开发者 —— 需要一个带结构化、机器可读错误的指标 API, 而不是自由格式的 SQL。
常见问题¶
OSI 和 Apache Ossie 是一回事吗?¶
是。Open Semantic Interchange(OSI)是这个规范的旧名,Apache Ossie 是现在的名字。 写着 OSI 的模型、工具和文档,指的都是同一个规范。
Dosi 能用任意 Apache Ossie 模型吗?¶
指标用 SQL 写的模型都能用。Ossie 还允许 MDX、TABLEAU、MAQL 表达式,但 Dosi
只编译 SQL:没有任何 SQL 写法的指标会报编译错误,字段则只给警告(见
S-EXPR-1)。dosi validate --osi-basic 除了 Dosi 自己的规则,
还会用上游 Apache Ossie 校验器检查一遍。Datus 扩展是可选的。
为什么 Dosi 的一些参数还叫 osi?¶
--osi-basic、--osi-datus 以及几个环境变量是在更名之前命名的。保留原名,
现有脚本和配置才能继续用。
下一步¶
-
拿到
dosi可执行文件,几分钟内验证通过。 -
10 分钟动手走一遍,从 Apache Ossie 模型到真实结果。
-
"绝不悄悄重复计数"背后的精确规则。
-
Dosi 实现的上游规范。
数据集级指标¶
一个聚合只属于一个数据集时,可以把它写在该数据集的 metrics 下。表达式里直接写已声明的字段名,用 source.column 读取本数据集的物理列。同一数据集的字段和指标不能重名。如果声明了名为 source 的字段,source 就指这个字段,指标无法再用此前缀访问物理列。
version: "0.3.0.dev0"
name: shop
datasets:
- name: orders
source: order_rows
fields:
- name: net_amount
expression: {sql: gross_amount - discount}
metrics:
- name: revenue
expression: {sql: SUM(net_amount)}
- name: order_count
expression: {sql: COUNT(*)}
- name: gross
expression: {sql: SUM(source.gross_amount)}
metrics:
- name: average_order_value
expression: {sql: "AGG(orders.revenue) / NULLIF(AGG(orders.order_count), 0)"}
查询 orders.revenue 返回的列名是 revenue。一次查询中的输出列名必须互不相同。模型级指标可以用 AGG(数据集.指标) 引用数据集级指标。示例中的两个聚合都属于订单;公式跨多个数据集时,每个聚合仍从自己的数据集取数,COUNT(*) 也是如此。
指标编译失败时,直接查询它或查询依赖它的指标都会收到相应错误,其他指标仍可查询。dosi validate 会报告有问题的定义。名称重复、关系指向未知数据集等结构错误仍会阻止加载模型。
如果数据集级指标声明了 DATUS 的 derive.type: lod、window 或 params,两种模式都会在查询该指标时返回错误。对数据集级指标上的其他 DATUS 扩展,两种模式都会提示警告,并按指标的表达式计算。