跳转至

Datus 对 Apache Ossie 的扩展

  • 状态:草案,Datus 已在用(Dosi 与 Datus 的模型生成 Agent)。
  • 规范版本:datus-ext/1(主版本系列)
  • 当前版本:1.14 —— 每个小版本加了什么、以及版本号如何决定, 见扩展版本。任何引擎都能报告自己实现的版本: dosi info、GET /v1/capabilities,或 dosi_engine.DATUS_EXT_VERSION。
  • 范围:Apache Ossie(原 OSI)核心规范 0.3.0.dev0 还无法表达的那些语义, 统统装在 Ossie 官方认可的 nonportable_extensions 字段内部, 这样文档仍然是完全合法的 Ossie,而每个非 Datus 的消费方都会忽略它们。

这一页是总览:每个扩展控制什么、扩展怎么写,以及几个简单扩展的完整规则。 较大的扩展(窗口指标、细节层次、参数、派生指标、跨事实对齐、时间存储格式) 各有自己的页面,列在较大的扩展一节。

除了模型语义之外,Dosi 的连接配置也讲 Datus: 配置沿用 agent.yml 的 datasources: 词汇表,一份完整的 agent.yml 可以直接作为 --connections 传入 —— 见 connectors.md。

这是一个私有的厂商扩展,不必经 Ossie 工作组接纳即可使用。 当某个扩展所泛化的空缺本该属于核心规范时(时间粒度、累计窗口), 它的长期归宿是一份 Ossie RFC;本文档是 Datus 今天据以发布的过渡载体。

每个扩展做什么

所有扩展都是可选的。只在想改变默认行为的地方加;一个模型一个扩展都不加, 行为就和纯 Ossie 规定的完全一样。

扩展 载体 键 控制什么 不写时的默认
D-JOIN Relationship join_type JOIN 到维度时,没匹配上的事实行是保留还是丢弃 left,孤儿行保留
D-FILL Metric fill_nulls_with 没有数据的分组显示什么数字 纯计数填 0,其余为 NULL
D-TIME Dataset / Metric time_dimension 哪一列是业务时间轴(metric_time) 数据集里唯一的 is_time 字段,否则没有
D-GRAIN 时间 Field time_granularity 列存储时的粒度 从类型或格式推断,推断不出就允许任意粒度
D-DATASET Metric dataset COUNT(*) 归属哪个数据集 从 SQL 推导,推不出就报 count_star_needs_dataset
D-DIM Field is_dimension 字段是否作为维度推荐 从键、关系和被聚合的列推断
D-DETERMINES Field determines 字段的每个值对应哪些字段的唯一值,从而去重计数可以按这些字段拆 键、多对一关系和 fixed 字段
D-MEASURE Metric measure 指标度量的名字 由聚合自动生成
D-WINDOW Metric window 同环比、滚动、累计、排名与取值类窗口 朴素的基础聚合
D-LOD Field / Metric lod、derive 的 lod 类型 按一种粒度计算、按另一种粒度展示 字段就是一个存储的列
D-PARAM Metric / Field params 查询时绑定的窗口宽度和过滤字面量 每个槽位就是它声明的那个字面量
D-DERIVE Metric derive 由其他指标构成的指标(filter、compose) 自包含的指标
D-CONFORM Relationship cardinality 两张事实表按共享维度对齐,而不连接明细 many_to_one,这条边就是一个 JOIN
D-FORMAT 时间 Field time 时间列怎么存日期(20260907、202609) 当作原生 DATE / TIMESTAMP

dosi info 会列出引擎读取的每个键,以及引入它的版本和忽略它的代价。

为什么模型仍然是合法的 Ossie

Ossie 的 schema 很严格(到处都是 additionalProperties: false), 所以我们不能直接加 relationship.join_type 这样的裸字段。 但规范在每个主要对象上都留了一个正式的扩展位置:

nonportable_extensions:
  - vendor_name: <string>
    data: <JSON object>

nonportable_extensions 存在于 SemanticModel、Dataset、Field、Relationship 和 Metric 之上。上游的 ossie 校验器接受它,所以一份携带 Datus 扩展的文档 原样通过上游校验。 不认识 vendor_name: DATUS 的消费方直接跳过, 模型的含义仍精确等于纯 Ossie 所说的含义。Datus 扩展只在 Ossie 未作定义之处 细化引擎行为;它们绝不改变一个指标或维度是什么。

扩展怎么写

一个 Datus 扩展就是一条 nonportable_extensions 条目:

nonportable_extensions:
  - vendor_name: DATUS
    data: {"v": "1.1", "<option>": <value>}
  • vendor_name:规范写法是大写常量 "DATUS"(与 Ossie 规范的大写枚举风格一致, 比如 ANSI_SQL)。匹配时不区分大小写;历史上的小写 datus 继续可用。
  • data:一个保存扩展配置的 JSON 对象。每个对象上最多一条 DATUS 条目。 有两个信封键是保留的:v 和 requires。

消费规则(Dosi):

  • 不存在 → 采用写明的 Ossie 默认行为(见总览)。扩展纯粹是增量的, 一个没有任何扩展的模型,行为与今天完全一致。
  • 未知的载荷键会被忽略,而不是被拒绝:这样更新的 Datus Agent 可以输出老引擎不读的键,而不至于把它弄坏(前向兼容)。 例外是下面的 requires。
  • 未知的 vendor_name(除 DATUS 之外的一切,比较时不区分大小写)会被忽略。
  • 格式不对的 DATUS 载荷(例如已知键的类型不对)是一个 结构化错误(invalid_datus_extension),而不是悄悄取默认值: 一份由 Datus 编写的文档要按 Datus 的契约来要求。编译仍会带着默认值继续, 这样一趟就能报出模型里的所有问题。

v —— 声明的版本

v 的形式是 MAJOR.MINOR。字符串形式是规范写法("v": "1.1"); 为方便起见也接受 JSON 数字("v": 1.1,以及裸整数 "v": 1 表示 1.0)。

JSON 数字只能表达 0–9 的小版本号。 1.10 和 1.1 是同一个 f64, 所以数字无法表达小版本 10;带两位及以上小数的数字会被直接拒绝, 并提示你改用字符串形式。一旦当前小版本到达 10,请一律把 "v" 写成字符串。

v 是可选的,省略它永远是安全的 —— 一个未声明版本的载荷, 行为与版本闸门存在之前完全一致,也不会产生任何诊断信息。 版本是按 nonportable_extensions 条目声明的,而不是按文档: 模型级的 v 不会成为它下面数据集、字段、关系或指标的默认值。

给定引擎自身的版本,标注版本能给你带来什么:

情形 引擎的反应 错误码
v 不存在或为 null 静默 —— 行为与闸门出现之前一致 —
v 格式不对(坏字符串、JSON 类型不对、带 ≥2 位小数的数字) 错误 invalid_datus_extension
v 低于 1.0,或主版本比引擎的新 错误 unsupported_datus_ext_version
小版本比引擎的新 告警并点名被丢弃的键;引擎认识的一切仍然生效 datus_ext_version_ahead
某个键比你声明的 v 更新 告警;但该键仍会被采纳 datus_ext_key_newer_than_declared
小版本比引擎的旧,且所用键都在其范围内 静默 —

未来的主版本是唯一一种一刀切的拒绝。主版本号提升意味着至少有一个键改变了含义, 而早于这次改变的引擎无从知道是哪一个,硬着头皮读那个载荷会产生悄无声息的错误数字。 小版本按构造就是增量的,所以它们最多只是告警。

requires —— 不允许被丢弃的键

data: {"v": "1.4", "requires": ["semi_additive"], "semi_additive": {"reduce": "last"}}

requires 是一个键名数组,生产方借此声明这些键不得被悄悄忽略。 没有实现其中某个键的消费方会抛出 datus_ext_key_required 并点名该键, 而不是丢弃它。

它之所以存在,是因为消费方无法判断自己从没听说过的键有多危险。 对 join_type 这样的键,"未知键被忽略"是正确的默认: 忽略它只是退回到一个有文档的行为。但对 semi_additive 这样的键就是错误的默认: 忽略它意味着把期末余额加总起来,返回一个干脆就是错的数字。 生产方知道哪个是哪个,requires 就是它表达这一点的方式。

对每一个忽略影响为 silent 的键(见版本策略) 都要输出 requires,其余一概不要。让老引擎降级运行,好过直接拒绝为它服务。 dosi info / GET /v1/capabilities 会报告每个键的影响级别。

Datus 模式下,非空的 silent 扩展若未列入 requires,会产生 datus_ext_requires_missing 告警,即使没有声明 v 也会检查。模型仍可编译; 将提示中的键补进 requires,才能防止旧引擎忽略它。

版本号什么时候升、每个小版本加了什么、还有哪些键在排队,都记在 扩展版本: 版本策略、 变更记录和 路线图。

简单扩展

下面每个扩展都只有一个键、取值也简单,完整规则在本节就能讲完。

D-JOIN —— 关系的连接类型

位置:一个 Relationship 的 nonportable_extensions。 载荷键:join_type,枚举 "left" | "inner"。 默认(不存在时):"left"。

假设在 line_items 上度量 revenue,想按 orders.status 拆开看。 有些 line item 指向的订单不在订单表里(迟到的行、软删除的订单、 数据质量缺口)。扇出分支沿这个关系(多→一)把"一"端 JOIN 进来、 去取某个维度或某个不在基上的度量时,join_type 决定这部分营收怎么算:

  • "left"(默认):保留多端没有匹配的行 —— 孤儿事实行会存活下来,落进任何取自缺失那一侧的维度的 NULL 分组里。 对账/审计语义:每一块钱都有交代。
  • "inner":丢弃未匹配的多端行。归因语义 —— 一个度量只在它所归因的实体确实存在时才被统计。
relationships:
  - name: line_items_to_orders
    from: line_items
    to: orders
    from_columns: [order_id]
    to_columns: [order_id]
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.0", "join_type": "inner"}

同一条查询,孤儿营收为 50:

join_type status revenue
left(默认) paid 300
(空白) 50 ← 孤儿行被保留
inner paid 300
(孤儿行被丢弃)

这让 INNER 还是 LEFT 成为关系的一个显式属性,而不是生成器里写死的默认值 (见语义契约里的 S-JOIN),所以每一条走这个 JOIN 的查询口径都一致。 dosi query --explain 会显示每个 JOIN 的类型,可以据此确认扩展已经生效。

D-FILL —— 合并时缺失分组的指标空值填充

位置:一个 Metric 的 nonportable_extensions。 载荷键:fill_nulls_with,一个 JSON 数字。 默认(不存在时):引擎默认 —— 一个纯 COUNT 指标填 0 (语义契约里的 S-FAN-6);其余每个指标保持 NULL。

按 city 看 order_count 和 signups,某个城市这个周期有注册、没有订单。 多分支合并之后,只出现在部分分支里的分组,对那些在缺失分支中计算的指标会投影出 NULL。纯计数在这里已经读作 0,因为什么都没有的计数就是零;但 SUM 仍是空白,因为"零行的求和"可以是 0 也可以是未知。fill_nulls_with: <n> 让你按指标决定:它在合并计划和单分支计划里都把这个指标的输出 COALESCE 成 <n> (通常是 0),对任何种类的指标都适用(SUM、比率、表达式), 并且优先于计数的默认值。

metrics:
  - name: revenue
    expression:
      sql: SUM(orders.amount)
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.0", "fill_nulls_with": 0}

按 city 看 revenue 和 signups,其中 Denver 有注册但没有订单:

city revenue(默认) revenue(fill_nulls_with: 0)
Austin 900 900
Denver (空白) 0

声明的填充是指标取值的一部分,在哪里读都生效:作为它自己的列、作为组合指标的成员 (无论是被内联,还是在窗口阶段之后按列读取),以及作为 window.base 排名、汇总或位移的序列。 一个指标被排名或求平均时,读到的就是它单独查询时显示的那个数。 除数只要读到填充过的成员,引擎就给整个除数套上 NULLIF(…, 0):除数可以是这个成员本身, 也可以是含有它的表达式(如 y * 2)、读到它的组合指标,或者以它为 base 的窗口指标(窗口读到的是补过的值)。这样填出来的 0 做除数得到 NULL, 和没填充时的 NULL 一样。窗口指标自己声明的填充,在别的指标读它时不生效,也不作用于它自己的输出。

计数默认值(S-FAN-6)的范围更窄:它只作用于指标的输出,绝不作用于嵌在比率/表达式里的 某个度量 —— 一个计数作为分母时不能变成字面量 0 除数。在窗口阶段之下,合并出来的度量列 保持 NULL,计数默认值在裸计数指标作为输出投影时才应用。没有声明填充的计数,被组合或比率当作 成员读取时 —— 或者位于 window.base 序列之内时 —— 保持 NULL。往查询里加一个窗口指标, 绝不会把一个被选中的计数从 0 变成 NULL。

D-TIME —— 主(聚合)时间维度

位置:一个 Dataset 或一个 Metric 的 nonportable_extensions。 载荷键:time_dimension,一个字符串名称引用 —— 在数据集上, 是它自己某个 is_time 字段的名字;在指标上,是 "field" 或 "dataset.field"。 默认(不存在时):一个恰好只有一个 is_time 字段的数据集, 会把它作为隐含的主时间(这条推断不读取任何扩展,所以在基础模式下同样适用); 零个或多个 is_time 字段 → 没有主时间。

"上季度按月看营收和库存变动" —— 可哪一列才是时间? orders 既有 order_date 又有 ship_date,库存表则是 move_date。 time_dimension 声明哪一列是一张表/一个指标的业务时间轴 —— 也就是当查询要求某个时间范围或粒度却没有点名列时,引擎会使用的那一列。 每个指标的解析顺序(S-TIME-5):

  1. 该指标自己的 time_dimension(优先级最高);
  2. 否则取该指标所涉数据集中唯一的那个主时间(数据集显式的 time_dimension, 否则是单 is_time 推断)。

指标级的裸 "field" 先在该指标自己的数据集里解析 (像 etl_dt 这样的时间字段名会在多个数据集里重复出现), 只有当它们都没有这个字段时,才放宽到整个模型。

datasets:
  - name: orders
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_dimension": "order_date"}
    fields:
      - name: order_date
        dimension: { is_time: true }
      - name: ship_date
        dimension: { is_time: true }
metrics:
  - name: shipped_revenue          # 同一个 SUM,但按发货时间算
    expression:
      sql: SUM(orders.amount)
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_dimension": "ship_date"}

查询通过保留名 metric_time 来消费它 (--group-by metric_time:month、--time-dimension metric_time):

dosi query --metrics revenue,moves --group-by metric_time:month

每个指标各按自己那张表的主时间列截断,结果在共享的 metric_time__month 输出上对齐。一个没有点名维度、group-by 里也没有时间项的时间范围, 会去过滤每个指标的主时间 —— 按聚合分支分别进行,用该分支自己的那一列。 一个无法解析出主时间的指标会产生 no_primary_time_dimension。 同一底表上主时间不同的几个指标不会报错:每条时间轴在这张底表上各开一个分支, 再按分组键合并,所以每个指标返回的都是它单独查询时的结果。

被引用的字段必须存在,且 is_time 实际为 true(显式声明或由核心 datatype 默认规则得出),否则 invalid_datus_extension。

D-GRAIN —— 原生时间粒度

位置:一个 Field 的 nonportable_extensions(该字段必须是 dimension.is_time: true,可以显式声明,也可以由核心 datatype 默认规则得出)。 载荷键:time_granularity,枚举 "day" | "week" | "month" | "quarter" | "year"。 默认(不存在时):从 time.format 推断,或由核心 datatype: Date 得出日粒度; 其余情况为未知,可以请求任意查询粒度。

声明该列存储时所用的粒度(比如一份按月快照的 etl_dt)。 请求一个严格更细的粒度(在一个 month 列上请求 :day, 无论是通过显式 group-by 项还是通过 metric_time)会得到一个结构化的 grain_too_fine 错误,而不是悄无声息的错误数据。 截断到原生粒度或更粗的粒度则不受影响。 这是上游 RFC 里 dimension.time.granularity 的过渡载体。 用字符串或整数存日期的列,粒度和存储格式一起声明,见 D-FORMAT。

fields:
  - name: etl_dt
    dimension: { is_time: true }
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_granularity": "month"}

D-DATASET —— 指标的归属数据集

位置:一个 Metric 的 nonportable_extensions。 载荷键:dataset,一个字符串,点名模型里的某个数据集。 默认(不存在时):归属只从指标 SQL 本身推导。

COUNT(*) 没有点名任何列,所以在一个多数据集模型里、 又没有别的聚合把某个数据集钉住时,Ossie 让它的归属处于未定义状态, 引擎会报错(count_star_needs_dataset)。这个提示恰好解决那种歧义。 它绝不会覆盖从 SQL 推导出的归属 —— 一个其聚合点名了列的指标, 无论有没有这个提示都保留它们各自的数据集(扩展绝不重新定义 SQL 所说的东西)。 一个不存在的数据集名会是 invalid_datus_extension。

metrics:
  - name: chat_message_count
    expression:
      sql: "COUNT(*)"
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "dataset": "chat_record"}

D-DIM —— 哪些字段可以作为维度推荐

位置:Field 的 nonportable_extensions。 载荷键:is_dimension,布尔。 缺省(不写):由引擎推断该字段的角色(见下)。

Ossie 把每个非时间字段都当作普通维度,于是模型无法表达一列其实是度量 (unit_cost)、标识(c_customer_id)、自由文本或 PII。按这样的列分组 并不是结构错误 —— SQL 跑得通,数字也对,只是这个分析没有意义。 is_dimension 让模型在建模时把这件事说一次,而不是每个调用方在每次调用时 重新判断一遍。

它是列举信号,不是权限:

写法 效果
不写 走下面的推断
false 不推荐该字段:list_dimensions 标记 is_dimension: false,归因不把它列为候选。显式写进 group_by 仍然可用。
true 即使推断会排除它也照样推荐 —— 数值列要分桶分析时就这么写

因为它到不了规划器,忽略这个键不会改变任何数字,只会让调用方拿到一份更差的 候选清单(documented 影响级别)。

datasets:
  - name: store_sales
    fields:
      - name: ss_quantity            # 没有任何指标聚合它的度量列
        expression: { sql: ss_quantity }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.7", "is_dimension": false}
      - name: i_current_price        # 数值,但要按价位段分析
        expression: { sql: i_current_price }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.7", "is_dimension": true}

不写这个键时的推断。 引擎只看模型结构,绝不探测数仓(对高基数列做 COUNT(DISTINCT …) 不是引擎有权强加的代价)。以下字段不会被推荐:主键成员、 指标自身归属数据集上的单列唯一键、多对一关系连接列对中出现的列(D-CONFORM 配对不是连接,配对列就是维度本身)、以及被某个指标度量过的列 (SUM/AVG/STDDEV*/VAR* 读到的那个值)。其余都推荐; list_dimensions 会用 source 说明命中的是哪条规则。

有三类聚合只是提到了某列,并没有度量它,因此该列仍然是维度:

  • COUNT —— COUNT(DISTINCT region)("活跃区域数")是正常指标,region 是正常维度。 对正在被列举的那个指标同样成立:同一个字段,从哪个指标问都是同一个答案。
  • MIN / MAX —— 它们对字符串和日期同样成立,MIN(activity_code) 是"随便取一个标识",不是度量。
  • 聚合里的条件 —— SUM(CASE WHEN is_instant THEN 1 ELSE 0 END) 是"按标志计数", 标志本身仍是维度;只有 THEN/ELSE 的取值才是被度量的。D-DERIVE 的 filter 折叠出的正是这个形状, 行为一致。

推断看不见这几类:既非声明的键、也不是关系列的业务键;没有任何指标读过的数值列; 自由文本;PII —— 这些正是值得显式声明的字段。

D-DETERMINES —— 一个字段决定哪些字段

位置:Field 的 nonportable_extensions。 载荷键:determines,非空数组,元素是同一数据集里其他字段的名字。 缺省(不写):只用模型已经说明的部分:键、多对一关系和 fixed 字段。

determines 表示:在这个数据集读到的每一行里,该字段的每个值只对应列出的每个字段的一个值。它影响的是对该字段做的 COUNT(DISTINCT …):这时没有哪个值会在列出字段的两个组里重复计数,各组的去重数加起来正好是总数,attribute_dimensions 就能按这个字段拆这个计数。

大多数情况下模型已经说明了,不用声明:主键或唯一键决定所在数据集的全部字段;从多对一关系出发的字段决定它通往的数据集以及更远数据集的全部字段(按查询连接时走的路径;到某个数据集有两条路径时都不算);关联关系上的一列,只要与它配对的列被决定,它也被决定,因为连接匹配上的行里两者相等。fixed 字段是例外:时间范围也会限制 fixed 的计算,所以一个用户的订单数可能在一个对比期是 1、在另一个是 2。它由自己的键决定(也可以经由通往这些键的键或关联关系),前提是任何时期都改变不了它的值:时期落不到它的基础指标的行上,或者它的键决定了时期落在的那个时间字段,即默认的时间字段,或请求在 baseline.dimension 里指定的那个;同时计数这一侧也按这个字段取期(如果用户按下单日计数,而某一期里他的订单都没有送达,那一期读到的送达单数就是在零行上算的)。订单在哪一天,证明不了它所属用户的订单数不变:这个用户的其他订单在别的日子,两个时期也可能重叠。读 fixed 字段的字段(它的别名或分档)在它读到的东西都被决定时才算被决定:fixed 字段本身,以及读到的每一列。字段表达式里的名字指的是存储的列,所以一列被决定,要么是它所在的行被决定,要么有一个被决定的字段原样读这一列;对这一列做了变换的同名字段不算。声明会和这些规则串起来推导。需要声明的,是冗余存放在事实表行上、背后没有维表的字段,比如每张工单上的工程师所属区域:

datasets:
  - name: work_orders
    fields:
      - name: engineer_id
        expression: { sql: engineer_id }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.14", "is_dimension": false, "determines": ["region", "city"]}

这是一条声明:引擎直接信任,不读数据检查。它必须在任何时期能读到的每一行上、任何时间都成立(某个工程师换过一次区域就不成立)。任何时期能读到的行,是计数这个字段的指标所用的时间字段(这里是 d)有值的行;这个字段没有值的行不属于任何时期。NULL 也算一个值,该字段本身和列出的字段都是:声明会串起来推导,所以该字段为 NULL 的那些行也必须一致。声明前先核对数据:对每个列出的字段,下面的查询都查不出行。

SELECT engineer_id
FROM work_orders
WHERE d IS NOT NULL
GROUP BY engineer_id
HAVING COUNT(DISTINCT region) + MAX(CASE WHEN region IS NULL THEN 1 ELSE 0 END) > 1
LIMIT 5

数据只能说明现在已有的行。以后进来的行是否仍然成立,是业务规则,要由模型的负责人确认。

如果某一期的数据违反了声明,这次拆分会被拒绝,而不是算出结果:各组加起来的计数比整体大,调用报 dimension_not_aligned。按关联关系上的列拆、而有些行没匹配上时也一样,这时同一个值既计在 NULL 组,又计在另一个组里:比如某家门店所在的区域,在统计期的一个月里是考核市场,另一个月里不是。如果关联还用到了被计数字段决定不了的字段(比如门店旁边的月份),这家门店还可能在一个对比期里落进 NULL 组、在另一个对比期里落进它的区域,而单看哪一期都发现不了:按这样的字段拆,只要任一期出现 NULL 组就会被拒绝。可以改按关联用的那个字段拆,或者用 context_filter 只保留匹配上的行。经过这样的关联之后,只有直接取列的字段才算被决定:在列上做计算的字段(如 COALESCE(area, 'unknown'))会把没匹配上的行的 NULL 变成一个普通的组,按它拆会在取数之前就被拒绝。一个值在两个对比期之间换了组(工程师 7 月在一个区域、8 月在另一个),则发现不了:按这个字段拆比率或排名时,这个值会被算两次。查询从不读这条声明,所以它不会改变任何查询结果。模型已经能推出的字段又被列出时,dosi validate 会报 redundant_determines;fixed 字段除外,因为换一个时间字段的请求可能正需要这条声明。引擎忽略这个键时,这些指标的 attribute_dimensions 照旧被拒(degraded 级影响)。

D-MEASURE —— 显式度量名

位置:一个 Metric 的 nonportable_extensions。 载荷键:measure,形如 {"name": <identifier>}。 默认(不存在时):由净化器生成的 stem(S-MEASURE-1)。

显式命名该指标唯一的那个合成度量。不写时度量名由聚合参数生成(S-MEASURE-1): 任何文字的字母和数字都保留,所以 '新品' / '老品' 这样的 CASE 字面量会得到不同的名字; 只差运算符的聚合加签名 tag 区分(…_sum_1f3a9c0e,见 S-MEASURE-2)。 这样的名字可能很长,不是纯 ASCII 时在生成的 SQL 里会加引号;显式名字可以给它一个短名字。 显式名字是一个标签:去重仍然以聚合签名为键(一个没有声明的文本孪生体会共享这个 已声明的名字),这个名字也会进入同一套冲突检查(一个签名上有两个显式名字, 或一个名字落在两个签名上,同样会大声冲突),并且它只适用于单聚合指标。 由于度量名会出现在结果列和元数据里,忽略这个键等于悄悄改名 —— 所以请把它列进 requires,让更旧的引擎直接拒绝 (这是 requires 发布以来第一个 silent 影响级别的键)。

metrics:
  - name: 新品收入
    expression:
      sql: "SUM(CASE WHEN orders.category = '新品' THEN orders.amount END)"
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.4", "requires": ["measure"], "measure": {"name": "orders_new_product_amount_sum"}}

measure 和 derive 一样,通常由建模工具写出,而不是手写。

较大的扩展

下面这几个扩展会改变指标或字段算出什么,或者改变两张表怎么碰到一起, 每个都有自己的规范页。本节只说明它们各自解决什么问题、去哪里继续读。

D-WINDOW —— 窗口指标

指标上的 window 键声明同环比、滚动和累计聚合、排名,以及首/末/第 n 个取值, 作用在指标自己的聚合之上,不需要在表达式里写裸窗口 SQL(引擎会以 window_in_metric 拒绝)。时间轴来自 D-TIME。先看快速上手, 窗口指标页的其余部分是完整规范。

D-LOD —— 细节层次

字段写 lod: {expr: ...},指标写 derive: {type: "lod", expr: ...}: 先按一种方式分组算出结果,再在按另一种方式分组的查询里使用它,对应 Tableau 的 FIXED、INCLUDE 和 EXCLUDE。理解 LOD 讲概念并跑通第一个模型, 电商建模实践搭一个完整模型, 编写参考收录全部规则:

D-PARAM —— 查询期参数

params 键把窗口宽度、偏移期数、排名分桶数或过滤条件里的字面量,变成查询时绑定的 类型化参数:一个 moving_avg(n) 取代 r7_revenue / r30_revenue / r90_revenue。 multiple 参数取一组值,单独构成 IN 的值列表(color IN (:colors)),所以多选是一个 参数,而不是固定个数的槽位。参数只填类型化的洞,绝不填 SQL 文本。规范见 参数化指标,其中包括 多选参数、 字段自己的参数、 细节层次字段的 base 和派生子类型的阈值。

D-DERIVE —— 派生指标

derive 键记录一个指标如何由同一模型里的其他指标派生:基础指标的 filter 变体、 几个指标的 compose,或建在另一个指标序列上的窗口。引擎会检查指标的 expression 与声明一致,并把这份结构提供给 dosi list、血缘和归因。它通常由建模工具写出。 见派生指标。

D-CONFORM —— 事实表之间的一致性关系

关系上的 cardinality: many_to_many 把两张事实表按共享的维度(日期、平台)配对, 而不连接它们的明细:每张事实表各自聚合,再合并结果。忽略它的影响是 silent, 所以请列进 requires。见跨事实对齐。

D-FORMAT —— 时间存储格式

时间字段上的 time 键声明列不是原生日期时日期是怎么存的('20260907'、202609、 '2026年09月07日'),这样引擎既能按月或按年对它分组,过滤时又能保持有利于分区裁剪的 裸比较。忽略它的影响是 silent,所以请列进 requires。 时间存储格式一页依次讲 什么时候需要配置、 快速上手、 过滤条件怎么写、 支持的格式、 分组粒度与时间边界、 校验范围与已知限制 和生成的 SQL。

校验与引擎模式

  • 上游 Ossie 校验(dosi validate --osi-basic,见 CLI 参考):不受影响 —— nonportable_extensions 是合法 Ossie, 所以携带 Datus 扩展的模型照样能通过。
  • Datus 自校验(引擎处于 --osi-datus 模式,即默认模式,且读到一条 DATUS 条目时):载荷必须是一个 JSON 对象;已知键必须匹配其声明的类型/枚举; 否则 invalid_datus_extension。未知键放行(前向兼容), 除非它被 requires 点名。信封的版本闸门(见上)在这里运行, 每个载荷一次 —— 包括 SemanticModel 这个载体,它自己不定义任何键,但仍要遵守信封规则。
  • 基础模式(--osi-basic):引擎把 DATUS 当作任何未知厂商来对待 —— 扩展是惰性的(符合规范的原样透传),编译过程会为每个携带它的元素收集一条 ignored_vendor_extension 告警 —— SemanticModel、Dataset、Field、 Relationship、Metric 一视同仁 —— 并点名改为适用的那个默认值 (D-JOIN → LEFT,D-FILL → 除 S-FAN-6 外不做填充, D-TIME → 只做单 is_time 推断,D-GRAIN → 任意粒度, D-DATASET → 只做 SQL 推导的归属,D-WINDOW → 朴素的基础聚合, D-FORMAT → 该列被当作原生日期,对字符串或整型列而言这意味着一个数仓类型错误、 或者悄无声息的错误行,D-LOD → 字段被丢弃,D-CONFORM → 这条边成为普通的 many→one join,两张事实表被逐行连接、对重复敏感的聚合被扇出)。D-LOD 是唯一一个没法降级成某个 值的:没有那份声明,字段的表达式就是一个裸聚合,而聚合不是合法的行级属性, 所以字段会带着一条 aggregate_field_dropped 告警被丢掉,引用它的指标和查询 随后以 unknown_field / unknown_column 失败。另一条路是让 AVG(COUNT(DISTINCT …)) 打到数仓上。 载荷不会被解析,所以格式不对的载荷同样只是被忽略并告警 —— 而且在基础模式下根本不会产生任何版本诊断。同一个模型文件在两种模式下都合法; 区别只在语义。(单 is_time 的主时间推断不是扩展 —— 它在基础模式下同样适用,所以只要纯 Ossie 能确定一条唯一的时间轴, metric_time 就仍然可用。)

非目标/边界

  • Datus 扩展绝不重新定义一个 Ossie 对象的身份或一个指标的 SQL —— 只在 Ossie 未定义的接缝处影响引擎行为。
  • 它们不是夹带厂商 SQL 的地方。指标表达式仍然放在 Ossie 的 expression.dialects 里;引擎依旧从那段 SQL 推断指标语义。
  • 那些本该属于 Ossie 核心的语义(粒度、时间轴表、窗口/累计指标) 未来可能由上游标准统一定义; 一旦在那里被采纳,对应的 Datus 扩展(D-GRAIN、D-WINDOW)就会退役, 改用核心字段。