mz-ontology-design

Materialize 本体设计

在源数据形态的数据与面向使用者的输出之间，构建一个规范的语义图。共享含义属于本体；呈现方式和工作流策略属于边界层。

架构

使用共享的 raw 数据库、共享的 core 数据库，以及每个用例各自的数据库。 保持以下依赖方向：

raw.<source_system>  ->  core.<source_system>  ->  core.internal
                                                    |
                                                    v
                                               core.public
                                                    |
                                                    v
                                         <use_case>.<schema>

• raw 包含源数据形态的摄取对象。保留源表标识；重新创建源表可以重新快照上游系统。
• core.<source_system> 包含私有的、源内的类型标注、清理、去重和命名。
• core.internal 包含私有的跨源集成和身份解析。
• core.public 是有文档说明的本体，也是使用者唯一可读取的 core 架构。
• 每个用例拥有一个数据库。其架构包含该应用或工作负载所需的投影、聚合、评分、筛选和索引。用例之间绝不共用数据库。

只有 core 可以读取 raw。每个用例数据库只能读取 core.public。应通过授权和依赖验证来强制执行这些边界，而不能只依赖命名约定。

语义对象

语义对象是一个规范关系，其行具有一种有文档说明的粒度、一种持久的身份规则、明确的时间语义，以及独立于任何使用者的含义。它表示以下其中一种：

• 实体：具有身份的持久事物；
• 事件：具有事件身份和事件时间的发生；
• 度量：在某个主体、指标和观测时间上的观测；或
• 关系对象：具有属性、证据、历史或多对多含义的关联。

聚合、评分、显示类别、报告行、源副本或一对一投影，不会仅仅因为某个使用者需要它，就成为语义对象。

添加公共对象之前，必须满足以下所有条件：

1. 其粒度和身份可以明确无歧义地表述。
2. 其含义不依赖于特定的仪表板、警报、模型或工作流。
3. 它对多个使用者有用，或是另一个公共对象的基础。
4. 其属性属于相同粒度，来源清晰，并且适合通过公共边界公开。

如果某个用例需要缺失的数据，应先判断是向现有对象添加属性、添加事件、度量或关系对象，还是将面向使用者的派生结果保留在边界层。绝不可绕过私有边界。

身份与时间

如果上游标识符不可变且具有全局意义，应优先使用。当身份受父级范围限定时，应使用明确的复合键。在 core.internal 中一次性解析跨源身份，并保留源标识符以追踪数据沿袭。只有在不存在持久键时，才使用确定性的合成标识符；并记录其输入和稳定性边界。

不要发布仓库哨兵成员，也不要在所编码的键旁重复发布替代哈希值。在未解析、未匹配、存在歧义和已解析等区别有意义时，应明确表示这些状态。

每个公共对象都应声明其表示的是当前状态、不可变事件、某一时点的度量，还是有效期历史。当事件时间、有效时间和摄取时间中有多个会影响解释时，应将它们区分开来。

公共对象与用例对象

每个 core.public 语义对象都要精确定义一次，使用领域名词命名， 并将其作为物化视图发布到转换计算层。这样，服务集群就能使用维护后的结果，而无需重建语义图。

规范化共享含义：每条事实只有一个规范所有者。只有在其派生方式符合规范，且关系文档将其标明为非规范化副本时，才允许保留非规范化副本。

用例数据库可以将其数据面组织到一个或多个 schema 中，并将本体转换为星型结构、宽表、队列、排名、评分或警报状态。它们不得重新定义身份，也不得维护共享概念的独立版本。转换计算与服务计算仍须分离；当服务工作负载的所有权、隔离、资源配置和可用性要求兼容时，可以共用同一集群。

关系

使用以下两种关系形式：

• 引用边通过一个公共对象上的列表示，这些列标识另一个公共对象中的一行。从引用方看，其基数为 many_to_one 或 one_to_one。
• 如果关联具有属性、时间、证据、置信度或多对多含义，则应将其建模为公共语义对象，即关系对象。它对参与实体的引用属于普通引用边。

不要将启发式匹配公开为类似外键的边。应将匹配建模为关系对象，并包含其方法、状态、证据、置信度和生效时间。

core.public.relationships 是所有引用边的机器可读注册表。创建或审查该注册表时，请阅读 references/relationships.sql。复合引用应按位置列出列；对于可选引用，所有列必须全部为空或全部非空。

根据编译后的 schema 验证该注册表：关系名称唯一；对象和列均存在；列数和类型匹配；被引用列构成唯一键；必需引用没有空值或孤立项；一对一引用在引用方唯一；枚举值有效；并且每个公共引用都已注册。

文档与测试

使用 comment on 编写面向使用者的契约。每个公共对象都要说明其粒度、身份、时间行为、含义和重要排除项。为键、时间戳、单位、状态字段、可空关系、敏感字段和不明显的派生逻辑添加注释。当语义溯源会影响解读时，应将其纳入文档；不应包含源数据机制、连接实现和性能说明。

在 SQL 注释中保留实现说明。测试公共键的唯一性和非空性、可接受的状态、关系完整性、粒度保持情况以及不明显的语义规则。CI 还应拒绝反向层依赖、用例数据库访问私有 schema、缺少文档的公共对象，以及转换计算层上的使用者索引。