Datus 编写的指南 · Apache Ossie(孵化中)

Apache Ossie。语义模型的开放标准。

Apache Ossie(孵化中)原名 Open Semantic Interchange(OSI),是一套开放、中立的语义模型交换规范。它描述数据集、字段、关系、指标与业务上下文,让兼容的工具能够复用同一套业务定义。

Apache-2.0 · 厂商中立的开放规范

开放规范

让业务含义走出单一工具。

语义模型记录数据如何表达业务。Apache Ossie 为这些定义提供交换格式,让支持该规范的分析平台、应用和 AI Agent 复用兼容的建模成果。

01

统一的格式

将数据集、计算、关系与上下文保存在可读的模型文档中,便于团队检查与维护。

02

共通的语言

在工具之间交换兼容定义。先检查转换诊断和运行时支持范围,再验证实际行为。

03

明确的分工

规范负责描述模型;兼容的运行时负责校验请求、规划查询并提供执行能力。

为什么采用 Apache Ossie

让业务定义持续复用。

继续使用现有 BI 和分析工具。Ossie 为兼容的业务定义提供共同格式,方便团队审核、维护,并在不同工具间复用。

现有做法

在各 BI 或分析工具里分别维护定义。

采用 Ossie 的价值

用共同模型承载兼容的数据集、指标与关系,减少重复建模。
1 / 3

Ossie 定义交换格式,DOSI 为兼容模型提供执行能力。它们不替代现有 BI 工具或数仓;转换覆盖范围与计算行为仍需在目标运行时中验证。

了解受支持的转换路径
模型内容

不只是一个指标名称。

模型把源数据连接到业务含义,为团队和软件提供可以检查的定义。

Ossie 模型可以使用 YAML 或 JSON。每个文档声明所用的规范版本;请确认校验器和目标使用方支持该版本。

northstar-explained.yaml

当前高亮: 数据集

# Educational subset adapted from the Northstar Premier demo.
# Source queries, field expressions and booked_revenue are preserved.
# Root layout updated; ai_context is an added explanatory annotation.
version: 0.2.0.dev0
name: northstar_premier_excerpt
description: Northstar retail orders and booked revenue — educational subset
datasets:
  - name: customers
    source: northstar_living.dim_customer
    primary_key:
      - customer_id
    fields:
      - name: customer_id
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: customer_id
        dimension: {}
      - name: city
        datatype: String
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: city
        dimension: {}
  - name: orders
    source: SELECT o.* FROM northstar_living.fct_orders o JOIN northstar_living.dim_customer c
      USING(customer_id) WHERE o.status='delivered' AND NOT o.is_test AND
      o.delivered_at>=DATE '2025-09-20' AND o.delivered_at<DATE '2026-09-20' AND NOT
      c.is_employee AND c.identity_status='resolved' AND EXISTS (SELECT 1 FROM
      northstar_living.fct_order_lines l WHERE l.order_id=o.order_id AND
      l.delivered_qty>0)
    primary_key:
      - order_id
    fields:
      - name: order_id
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: order_id
        dimension: {}
      - name: customer_id
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: customer_id
      - name: ordered_at
        datatype: Date
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: ordered_at
        dimension: {}
  - name: lines
    source: SELECT l.* FROM northstar_living.fct_order_lines l JOIN
      northstar_living.fct_orders o ON l.order_id=o.order_id JOIN
      northstar_living.dim_customer c ON o.customer_id=c.customer_id WHERE
      o.status='delivered' AND NOT o.is_test AND o.delivered_at>=DATE '2025-09-20' AND
      o.delivered_at<DATE '2026-09-20' AND NOT c.is_employee AND
      c.identity_status='resolved' AND l.delivered_qty>0
    primary_key:
      - order_line_id
    fields:
      - name: order_line_id
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: order_line_id
        dimension: {}
      - name: order_id
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: order_id
      - name: gross_sales_cents
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: gross_sales_cents
      - name: discount_cents
        datatype: Integer
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: discount_cents
relationships:
  - name: lines_to_orders
    from: lines
    to: orders
    from_columns:
      - order_id
    to_columns:
      - order_id
  - name: orders_to_customers
    from: orders
    to: customers
    from_columns:
      - customer_id
    to_columns:
      - customer_id
metrics:
  - name: booked_revenue
    expression:
      dialects:
        - dialect: ANSI_SQL
          expression: SUM((lines.gross_sales_cents-lines.discount_cents)*0.01)
ai_context:
  instructions: Booked revenue uses gross sales less discounts, in currency units. Inspect
    source filters and do not treat booked revenue as customer margin.
  synonyms:
    - booked sales
    - sales before refunds

点击属性即可定位对应定义。此示例覆盖页面展示的五类核心内容,并非 Ossie 的全部可选属性。它保留 Northstar 中选取的源查询、字段、关系和 booked_revenue,外层结构调整为当前草案格式;ai_context 是为本页补充的解释性注解,不是完整的九表生产演示。

可移植定义是起点。使用方仍需支持模型涉及的功能与表达式语言。

查看完整语义模型示例

把计算定义连接到业务概念。

核心语义模型描述数据集、字段、指标及数据关系。独立的 Ontology 规范描述业务概念、角色、关系和规则;映射文档将概念层连接到语义模型。

01

业务概念

Customer → places → Order

描述业务对象的含义和关系,超越物理表名。

02

Ontology 映射

概念与角色 ↔ 数据集与字段

把业务词汇连接到语义模型中的实际表示。

03

语义定义

orders.amount → revenue

明确源数据映射和计算表达式,供兼容的工具使用。

ai_context 中的说明和同义词有助于理解定义,但不能替代 Ontology 规范。具体使用方需要说明自己实现了哪些 Ontology 与映射功能。

阅读上游 Ontology 规范
互操作如何发生

一种共同格式,减少重复转换。

使用 Ossie 作为共同交换格式,减少为每一对工具单独维护转换逻辑的工作。受支持的转换器负责导入或导出源格式和目标格式能够表达的定义。

使用 Datus 工作台转换模型。

Datus 转换工作台包含以下示例路径。转换移动的是模型定义,不是底层数据;导入与导出能力分别维护。

例如:Cube YAML → Ossie → Snowflake Cortex Analyst 格式。本工作台中的 Snowflake Cortex Analyst 仅支持导出;dbt 导入不接受原始项目 YAML。请检查诊断,再在目标平台校验和测试;实际可用范围以工具的实时列表为准。

项目与社区

公开协作,共建开放规范。

  1. Open Semantic Interchange 发布

  2. 公开代码仓库开放

  3. Apache Ossie(孵化中)

项目于 2025 年以 Open Semantic Interchange 的名称发布,后更名为 Apache Ossie(孵化中)。目前仍处于 Apache 孵化阶段,规范持续演进。

项目公开开发与讨论决策。生态参与方包括 Snowflake、Salesforce、dbt Labs、Microsoft、Databricks、Datus 等,各实现的支持范围不同。任何人都可以讨论提案、报告问题或贡献代码与文档。

Datus 如何使用 Apache Ossie

从开放定义到 Agent 行动。

DOSI 将兼容的 Apache Ossie 定义编译为原生 SQL。在 Datus 中,这个运行时与 Datus Agent、Studio 共同工作:Agent 使用共享业务含义,团队构建、审核并检查工作背后的上下文。

已有知识

业务文档
SQL 与 ETL
数仓
Datus

Datus Studio

团队协作开展 Agent 驱动数据工程的工作区。

Datus Agent

支持数据工程与分析的完整数据 Agent。

本体与语义模型

DOSI Engine

将兼容的 Ossie 定义转为原生 SQL 执行。

Apache Ossie Spec

开放、中立的语义建模规范。

使用共享上下文

团队
AI Agent
应用与 BI

Apache Ossie(孵化中)是 Apache 软件基金会(ASF)旗下、由社区维护的项目,不属于 Datus。图中展示的是 Datus 对规范的使用关系:DOSI 执行兼容的定义。Datus 和 DOSI 独立于 ASF,并非 ASF 背书的产品。

Apache Ossie

开放规范描述语义模型与 Ontology;规范文件本身不执行查询。

DOSI

语义运行时校验兼容定义,将受支持的请求编译为原生 SQL,也可以独立使用。

Datus

Studio 提供团队工作空间;Datus Agent 开展数据工程与分析,建模是其工作流的一部分。

Ossie 定义元数据;MCP、API 和 CLI 接入能力由具体实现提供,不是模型文件自带的功能。共享上下文帮助分析建立依据,但不保证答案始终正确。

检查 DOSI 执行过程
用 DOSI 原生执行

规范定义业务,DOSI 提供执行。

DOSI 是 Datus 的语义执行运行时,也可独立使用。它读取兼容的 Ossie 定义,校验受支持的请求,并将其编译为配置数据源的原生 SQL。

01

读取模型

以数据集、指标表达式和已声明关系作为输入。

02

校验与规划

检查请求,规划受支持的连接与聚合,对不支持的情况明确报错。

03

生成原生 SQL

先检查 SQL,再选择是否通过已配置的数据源执行。

了解 Ossie 原生执行

观看 DOSI walkthrough,了解产品工作流程。

在 YouTube 观看
运行完整快速入门示例
选择起点

从已有工作中建立模型。

可以从日常数据工作中构建定义,也可以带入其他工具的兼容模型。团队始终参与审核。

01

从数据工作中构建

让 Datus Agent 辅助整理 SQL、支持的 BI 查询、文档与新需求,在团队工作流中审核定义。

了解建模工作流
兼容边界

定义开放,边界清楚。

使用相同格式,不意味着每个工具都支持所有功能,或对每种查询都采用相同行为。

规范与产品采用不同许可。

Apache Ossie 是在 Apache Software Foundation 中开发的开放规范。DOSI 采用 Elastic License 2.0;Datus Agent 以 Apache-2.0 开源。Datus 和 DOSI 是独立产品,不是 ASF 项目,也不表示通过 ASF 认证。

层次需要检查的内容
Apache Ossie 核心根据模型声明的规范版本,使用上游 Schema 校验文档。
DOSI 运行时阅读当前文档,确认表达式、查询行为、数据源适配器和执行条件。
Datus 扩展高级能力可能使用规范的扩展机制;其他工具未必解释这些扩展。
转换路径导入和导出是不同能力,需要检查字段、依赖、诊断和不支持的语义。
常见问题

采用 Apache Ossie 前的常见问题

Apache Ossie 文档本身能执行查询吗?

不能。Ossie 文档描述语义定义,本身不是查询运行时。兼容的引擎需要解释受支持的定义、校验请求、规划计算,再生成或执行查询。DOSI 为兼容模型和受支持的请求提供这条执行路径。

如何理解旧名称 Open Semantic Interchange?

Open Semantic Interchange 通常缩写为 OSI,是如今以 Apache Ossie(孵化中)开发的项目的原名。旧文章、路径和命令中可能仍保留 OSI。名称沿革不意味着所有历史模型结构都与当前规范兼容,仍需检查文档版本与当前校验器。

不使用完整 Datus 平台,也能采用 Apache Ossie 吗?

可以。规范保持厂商中立,独立于 Datus 开发。请根据定义和执行需求选择兼容使用方。DOSI 可通过受支持的接口独立于 Datus Studio 使用,编译兼容模型不要求采用完整工作空间。

复用转换后的模型之前需要验证什么?

检查源文件、模型版本、业务关系、表达式和转换诊断,再用目标运行时校验并测试预期查询。转换成功本身不意味着不同工具的默认筛选、时区处理、扩展支持和计算结果完全等价。

Datus 的生态收录是否代表 Apache 认证?

不代表。Apache Ossie 生态目录列出组织及其围绕规范的工作,其中 Datus 条目包含 DOSI、快速入门和 Datus Agent。收录不等于 ASF 对产品的认证或背书。Apache Ossie 是 Apache 孵化项目,Datus 与 DOSI 是独立产品。

Apache Ossie 的 YAML 文件是什么样的?

文件声明规范版本和模型名称,再描述数据集与字段,并按需包含关系、指标和上下文。YAML 与 JSON 均受支持。本页提供下载的示例使用 0.2.0.dev0 文档结构,并通过 DOSI 0.2.0 验证。旧示例可能采用不同的外层结构,复用前请检查版本并校验。

Apache Ossie 与 dbt Semantic Layer 有什么区别?

Apache Ossie 定义交换语义元数据的开放格式;dbt Semantic Layer 提供建模与指标查询系统。受支持的转换器可以在格式之间移动兼容定义,但仍需验证覆盖范围、表达式和执行行为。相关比较指南进一步解释两者分工。

AI Agent 如何使用 Apache Ossie 元数据?

Agent 可以检查已声明的字段、指标、关系、说明和 AI 上下文,再向兼容的使用方或运行时提交受支持的请求。DOSI 为兼容定义提供执行路径。文档本身不提供 Agent 协议,也不保证答案正确。

哪些公司支持 Apache Ossie?

官方生态目录列有 Datus、Databricks、dbt Labs、Microsoft、Salesforce 等参与方。被收录不意味着每家提供相同的集成能力。请查看具体实现的说明,分别核实导入、导出、原生读取和执行支持。

Ossie 的 hub-and-spoke 模式如何工作?

Ossie 作为中心的共同文档格式,转换器作为连接各厂商格式的分支,从而减少为每一对工具单独开发转换器的需要。这不要求集中式数据服务;转换后仍可能需要调整目标系统不支持的语义。

让开放定义进入工作

为团队与 Agent 提供可用的业务含义。

用 Datus 构建并审核上下文,或独立从 DOSI 快速入门开始。