OSI 字段映射

OSI 字段映射：所有语义层，同一份规范

一份逐字段的对照参考：MetricFlow、Cube、LookML、AtScale、Snowflake Semantic Views、GoodData、Power BI 与 Databricks Metric Views 如何翻译到 Open Semantic Interchange schema——现代语义层的厂商中立传输格式。

OSI v0.2.0.dev0·8 款产品·Apache 2.0

第 1 层

1 · 数据集层（表与数据源）

各家产品如何命名支撑某个语义对象的物理表，以及 OSI 如何把这些名字统一到 dataset.name + dataset.source 之下。

osi-dataset-mapping.yamlyaml

OSI Field

dataset.name

MetricFlow

semantic_model.name

Cube

cubes[].name

AtScale (SML)

dimension / dataset file name

LookML

view: view_name

Snowflake Sem. View

TABLES (alias AS …)

GoodData

dataset.id

Power BI (TMDL)

table 'Name'

Databricks Metric View

CREATE METRIC VIEW name

OSI Field

dataset.source

MetricFlow

model's ref() or source YAML

Cube

cubes[].sql_table

AtScale (SML)

dataset.source

LookML

sql_table_name / derived_table

Snowflake Sem. View

TABLES (alias AS db.schema.table)

GoodData

connection + dataset mapping

Power BI (TMDL)

partition.source (M / SQL)

Databricks Metric View

source: catalog.schema.table

OSI Field

dataset.primary_key

MetricFlow

entities[] with type: primary

Cube

dimensions[] with primary_key: true

AtScale (SML)

level_attributes[].key_columns

LookML

dimension: + primary_key: yes

Snowflake Sem. View

PRIMARY KEY (col)

GoodData

implicit via attribute labels

Power BI (TMDL)

column.isKey: true

Databricks Metric View

declared on source table (not in metric view)

OSI Field

dataset.description

MetricFlow

semantic_model.description

Cube

in-code comment (no standard field)

AtScale (SML)

dataset description

LookML

view-level comment

Snowflake Sem. View

COMMENT = '…'

GoodData

dataset.description

Power BI (TMDL)

table.description

Databricks Metric View

COMMENT '…'

语义对象的叫法在各家工具里差别极大——cube、view、semantic_model，或者一个裸 SQL 别名——但最终每家都指向同一张物理表。 OSI 把它收敛成两个字段：dataset.name 是指标引用的逻辑标识，dataset.source 则是下游消费方真正打到的那张表。

第 2 层

2 · 维度层（字段与属性）

字段级元数据：名称、表达式、标签、描述，以及大多数产品缺失的两样东西——时间标记与 AI 上下文槽位。

osi-dimensions-mapping.yamlyaml

OSI Field

fields[].name

MetricFlow

dimensions[].name

Cube

dimensions[].name

AtScale (SML)

dimension.unique_name

LookML

dimension: field_name

Snowflake Sem. View

DIMENSIONS (table.dim AS …)

GoodData

attribute.id + label.id

Power BI (TMDL)

column.name

Databricks Metric View

dimensions[].name

OSI Field

fields[].expression.dialects[]

MetricFlow

dimensions[].expr (single dialect)

Cube

dimensions[].sql (single dialect)

AtScale (SML)

level_attribute.column

LookML

dimension: { sql: ${TABLE}.col }

Snowflake Sem. View

DIMENSIONS (… AS sql_expr)

GoodData

label.source_column

Power BI (TMDL)

column.sourceColumn or DAX calc column

Databricks Metric View

dimensions[].expr (SQL)

OSI Field

fields[].dimension.is_time

MetricFlow

type: time + time_granularity

Cube

type: time

AtScale (SML)

type: TIME

LookML

dimension_group + timeframes

Snowflake Sem. View

no flag — SQL expression only

GoodData

no flag — attribute only

Power BI (TMDL)

dataType: dateTime + mark-as-date-table

Databricks Metric View

no flag — inferred from column type

OSI Field

fields[].label

MetricFlow

dimensions[].label

Cube

dimensions[].title

AtScale (SML)

level_attribute.label

LookML

dimension.label

Snowflake Sem. View

no dedicated field (use COMMENT)

GoodData

label.title

Power BI (TMDL)

column name doubles as label

Databricks Metric View

dimensions[].label

OSI Field

fields[].description

MetricFlow

dimensions[].description

Cube

dimensions[].description

AtScale (SML)

level_attribute.description

LookML

dimension.description

Snowflake Sem. View

COMMENT = '…'

GoodData

attribute.description

Power BI (TMDL)

column.description

Databricks Metric View

dimensions[].comment

OSI Field

fields[].ai_context

MetricFlow

—

Cube

—

AtScale (SML)

—

LookML

—

Snowflake Sem. View

WITH SYNONYMS = ('…')

GoodData

—

Power BI (TMDL)

column.synonyms (Q&A)

Databricks Metric View

Genie-space instructions (external)

OSI Field

fields[].custom_extensions

MetricFlow

dimensions[].type_params

Cube

dimensions[].meta

AtScale (SML)

dimension.type / format

LookML

tags / group_label

Snowflake Sem. View

WITH TAG (…)

GoodData

label.value_type

Power BI (TMDL)

annotations[]

Databricks Metric View

column tags on source table

OSI 的 fields[].expression.dialects[] 是唯一能原生容纳多方言 SQL 的地方—— MetricFlow、Cube 和 LookML 都默认只有一种方言。而fields[].dimension.is_time 是消费方唯一能依赖的跨产品时间维度标记：不必再分别去嗅 LookML 的 dimension_group、MetricFlow 的 type: time 和 Snowflake 的裸 SQL，用三种方式去猜同一件事。

第 3 层

3 · 指标层（度量与聚合）

各家产品如何描述聚合、过滤条件与派生指标——以及 OSI 如何把聚合从 SQL 字符串里拎出来，变成一等字段。

osi-metrics-mapping.yamlyaml

OSI Field

metrics[].name

MetricFlow

measures[].name

Cube

measures[].name

AtScale (SML)

metric.unique_name

LookML

measure: field_name

Snowflake Sem. View

METRICS (table.metric AS …)

GoodData

metric.id

Power BI (TMDL)

measure.name

Databricks Metric View

measures[].name

OSI Field

metrics[].aggregation

MetricFlow

measures[].agg (sum, count_distinct…)

Cube

measures[].type (sum, avg…)

AtScale (SML)

metric.aggregation_type

LookML

measure: { type: sum }

Snowflake Sem. View

inline in SQL (SUM(...))

GoodData

inline in MAQL

Power BI (TMDL)

inline in DAX (SUM(...))

Databricks Metric View

inline in SQL (SUM(...))

OSI Field

metrics[].expression

MetricFlow

measures[].expr

Cube

measures[].sql

AtScale (SML)

metric.expression

LookML

measure: { sql: ${TABLE}.col }

Snowflake Sem. View

METRICS (… AS sql_expr)

GoodData

metric.maql

Power BI (TMDL)

measure.expression (DAX)

Databricks Metric View

measures[].expr (SQL)

OSI Field

metrics[].description

MetricFlow

measures[].description

Cube

measures[].description

AtScale (SML)

metric.description

LookML

measure.description

Snowflake Sem. View

COMMENT = '…'

GoodData

metric.description

Power BI (TMDL)

measure.description

Databricks Metric View

measures[].comment

OSI Field

metrics[].filter

MetricFlow

measures[].filter

Cube

measures[].filters[]

AtScale (SML)

metric.filter

LookML

measure: { filters: [...] }

Snowflake Sem. View

inline in SQL WHERE

GoodData

MAQL WHERE clause

Power BI (TMDL)

DAX CALCULATE(..., filter)

Databricks Metric View

inline SQL WHERE in measure expr

OSI Field

metrics[].label

MetricFlow

measures[].label

Cube

measures[].title

AtScale (SML)

metric.label

LookML

measure.label

Snowflake Sem. View

—

GoodData

metric.title

Power BI (TMDL)

measure name doubles as label

Databricks Metric View

measures[].label

OSI Field

composite / derived

MetricFlow

metrics: block (ratio, derived)

Cube

measures[].sql referencing other measures

AtScale (SML)

metric referencing metric

LookML

type: number, sql: ${m1}/${m2}

Snowflake Sem. View

nested SQL only

GoodData

metric.maql referencing other metrics

Power BI (TMDL)

DAX measure referencing other measures

Databricks Metric View

MEASURE(name) reference in metric view

OSI Field

metrics[].ai_context

MetricFlow

—

Cube

—

AtScale (SML)

—

LookML

—

Snowflake Sem. View

WITH SYNONYMS = ('…')

GoodData

—

Power BI (TMDL)

measure.synonyms (Q&A)

Databricks Metric View

Genie certified instructions (external)

Snowflake Semantic Views 和 GoodData 把聚合埋在表达式字符串里（AS SUM(...)、SELECT SUM({fact})）。OSI 把它提到 metrics[].aggregation，这样 Agent 和 BI 工具不解析 SQL 也能理解这个运算。引用其他指标的派生指标，则通过 metrics[].expression 原样保留。

第 4 层

4 · 关系层（Join）

Join 在哪里声明、在哪里只能靠推断。OSI 把它们提升成一等的 relationships[] 块。

osi-relationships-mapping.yamlyaml

OSI Field

relationships[].name

MetricFlow

derived from entity.name

Cube

joins[].name

AtScale (SML)

dimension-to-fact binding (implicit)

LookML

join's view name

Snowflake Sem. View

RELATIONSHIPS (name AS …)

GoodData

dataset reference declaration

Power BI (TMDL)

relationship.name

Databricks Metric View

joins[].name

OSI Field

from_dataset / to_dataset

MetricFlow

model + entity.type: foreign

Cube

cube + joins[].name

AtScale (SML)

fact → dimension binding

LookML

current view + joined view

Snowflake Sem. View

table_a (col) REFERENCES table_b

GoodData

current + referenced dataset

Power BI (TMDL)

fromTable / toTable

Databricks Metric View

metric view + joins[].source

OSI Field

relationships[].foreign_key

MetricFlow

entities[].expr

Cube

joins[].sql

AtScale (SML)

FK column on fact dataset

LookML

join: { sql_on: ${a}.fk = ${b}.pk }

Snowflake Sem. View

FK column in REFERENCES

GoodData

reference key in dataset fields

Power BI (TMDL)

fromColumn / toColumn

Databricks Metric View

joins[].on (SQL predicate)

OSI Field

relationships[].cardinality

MetricFlow

inferred from entity type

Cube

joins[].relationship

AtScale (SML)

not declared

LookML

relationship: many_to_one

Snowflake Sem. View

not declared

GoodData

not declared

Power BI (TMDL)

cardinality: manyToOne

Databricks Metric View

not declared

这是六款产品里最不一致的一层。MetricFlow 和 AtScale 从 entities /level bindings 推导 join；Cube 和 LookML 直接内联声明；Snowflake 和 GoodData 介于两者之间。 OSI 的 relationships[] 块给所有消费方同样的四个字段——name、from_dataset、 to_dataset、foreign_key——外加显式的 cardinality，目前只有 Cube 和 LookML 会声明它。

第 5 层

5 · 时间语义层（粒度）

各家产品如何标记时间维度、如何表达粒度。OSI 的 is_time + granularity 是最小公约数。

osi-time-mapping.yamlyaml

OSI Field

fields[].dimension.is_time

MetricFlow

type: time

Cube

type: time

AtScale (SML)

type: TIME

LookML

dimension_group: { type: time }

Snowflake Sem. View

no flag

GoodData

no flag

Power BI (TMDL)

dataType: dateTime + date table

Databricks Metric View

no flag (TIMESTAMP column type)

OSI Field

fields[].dimension.granularity

MetricFlow

time_granularity: day

Cube

dimensions[].granularity

AtScale (SML)

hierarchy levels[]

LookML

timeframes: [date, week, month]

Snowflake Sem. View

SQL only (DATE_TRUNC(...))

GoodData

MAQL date semantics only

Power BI (TMDL)

date-table hierarchy (Year / Qtr / Month / Day)

Databricks Metric View

SQL only (DATE_TRUNC(...))

LookML 带 timeframes 的 dimension_group 最完整；Snowflake 则把时间完全丢给 SQL。 OSI 把这一层收敛成单个时间字段，带 is_time: true 和一个granularity 值——下游若需要日 / 周 / 月 / 季 / 年，可以基于基础字段加粒度元数据自行生成，信息不丢，而每个消费方只需判断一个标记。

第 6 层

6 · AI 上下文层（OSI 的差异点）

OSI 在整个生态里领先的一层。目前只有 Snowflake Semantic Views 有原生对应能力。

osi-ai-context-mapping.yamlyaml

OSI Field

fields[].ai_context

MetricFlow

—

Cube

—

AtScale (SML)

—

LookML

—

Snowflake Sem. View

WITH SYNONYMS = ('…')

GoodData

—

Power BI (TMDL)

column.synonyms (Q&A)

Databricks Metric View

—

OSI Field

metrics[].ai_context

MetricFlow

—

Cube

—

AtScale (SML)

—

LookML

—

Snowflake Sem. View

WITH SYNONYMS = ('…')

GoodData

—

Power BI (TMDL)

measure.synonyms (Q&A)

Databricks Metric View

—

OSI Field

AI instruction block

MetricFlow

—

Cube

external Cube AI API

AtScale (SML)

—

LookML

—

Snowflake Sem. View

AI_SQL_GENERATION '<instr>'

GoodData

—

Power BI (TMDL)

linguistic schema (.lsdl)

Databricks Metric View

Genie-space instructions

OSI Field

verified sample block

MetricFlow

—

Cube

—

AtScale (SML)

—

LookML

—

Snowflake Sem. View

AI_VERIFIED_QUERIES (…)

GoodData

—

Power BI (TMDL)

Q&A featured questions

Databricks Metric View

Genie certified example queries

这正是 OSI 被造出来要解决的一层。Snowflake 在 2026 年发布了 WITH SYNONYMS、AI_SQL_GENERATION 与 AI_VERIFIED_QUERIES——至今还没有第二家主流语义层有对应能力。 OSI 把这些提示标准化到每个字段和指标的 ai_context 里，于是读取 OSI 的 Agent 无论源头是 Snowflake、Cube 还是自研 YAML 存储，都能用同一种方式找到同义词、自然语言名称和已验证的示例查询。当下游工具采纳 OSI 后，这些 AI grounding 元数据会跟着指标一起走——而不是被锁死在某一家厂商的 SQL 方言里。

使用场景

OSI 为数据团队带来了什么

语义层一旦讲同一种厂商中立的格式，团队就能解锁四类模式——从终端一路到对话界面。

一份指标定义，通吃所有 BI 工具

OSI 把 metrics[].aggregation、fields[] 和 relationships[] 变成厂商中立的契约。同一份营收或留存定义可以同时下发到 Cube、Looker、Metabase 和 Python Notebook，不会悄悄跑偏。转换结果可以在OSI Playground 里校验。

把 AI Agent 锚定在业务语义上

同义词、自然语言标签和已验证的示例查询，都存放在每个字段与指标的 ai_context 里。Datus-Chat 和模型层读的是同一份 grounding，所以「ARR」会被解析成年度经常性收入，而不是某个机场代码。

在语义层之间迁移，不用重写

在 MetricFlow、Cube 或 LookML 里编写，再导出成 OSI 作为共享交换格式。数据工程师继续用自己的源头工具，而下游消费方读到的是一份一致的 schema—— 生成与评审都可以从 CLI 完成。

在看板坏掉之前发现 Schema 漂移

对比两份 OSI 文件，就能精确看到哪些 dataset.source、relationships[] 或 metrics[].filter 变了。治理检查是从 CLI 针对这份规范跑的，而不是针对某家厂商的 YAML。它在整体中的位置见 Datus 功能介绍。

常见问题

LookML、Snowflake AI 上下文、Cube 的 join、dimension_group timeframes、双向转换与 MAQL——OSI 各是怎么处理的。

LookML 的指标能用 OSI 表达吗？

可以。每个 LookML measure 都能翻译成一个 OSI metric：type 对应 aggregation，sql 对应 expression，filters 对应 filter。LookML 的派生 measure（type: number 且引用其他字段）映射为 OSI 的派生指标，引用同一文件中其他指标的名称。

OSI 支持 Snowflake Semantic Views 的 WITH SYNONYMS 和 AI_SQL_GENERATION 吗？

支持——而且这正是 OSI 标准化力度最大的一层。维度或指标上的 WITH SYNONYMS 直接映射到 OSI 的 ai_context.synonyms；AI_SQL_GENERATION 与 AI_VERIFIED_QUERIES 都有一等公民的位置，任何厂商的 Agent 都能读到同一份 grounding 提示。

OSI 怎么表示 Cube 的 joins[] 块？

Cube 的 joins[] 条目对应 OSI 的 relationships[] 条目：joins[].sql 对应 foreign_key，joins[].relationship（many_to_one / one_to_many）对应 cardinality，目标 cube 对应 to_dataset。不需要推断，是 1:1 映射。

MetricFlow 里有哪些东西是 OSI 目前表达不了的？

OSI v0.2 覆盖了 MetricFlow 的全部核心结构——semantic_models、measures、dimensions、entities 以及顶层 metrics——但少数高级能力（saved queries、带 grain-to-date 的累计指标、部分转化指标选项）仍在演进中。Datus Playground 会把所有被丢弃的字段显式列出来，不会悄悄丢失。

OSI 有对应 LookML dimension_group timeframes 的东西吗？

OSI 把 LookML 的 dimension_group 收敛成单个时间字段，用 is_time: true 加上一个 granularity 值来表达。下游工具如果需要全部时间粒度（date、week、month、quarter、year），可以基于这个基础字段和粒度元数据自行生成——既保持了 OSI 的厂商中立，也没有丢信息。

能做双向转换吗：MetricFlow → OSI → LookML？

OSI 目前主要是交换与消费格式。从 MetricFlow 或 Cube 正向转成 OSI 支持得很好（见 Datus Playground）；反向转回 LookML 或 MetricFlow 原生 YAML 还在社区路线图上。实际做法是：大多数团队把 OSI 当作共享的读取层，编写仍留在各自的源头工具里。

OSI 会支持 GoodData 的 MAQL 表达式吗？

MAQL 通过 metrics[].expression.dialects[] 得以保留：原始 MAQL 字符串存放在自己的方言下，认得 GoodData 的消费方仍可执行它，不认得的消费方则回退到 SQL 方言。OSI 处理任何厂商专有表达式语言用的都是这套机制。

Datus Playground 什么时候支持 MetricFlow 之外的转换？

先做 MetricFlow → OSI，是因为 dbt 语义层 YAML 是最常见的起点。Cube 和 LookML 转换器是路线图上的下一步；也欢迎贡献——Playground 是 Apache 2.0 的，每个转换器都是纯浏览器端的函数。

去试试 OSI Playground。

贴进你的 MetricFlow YAML，拿回 OSI——校验、转换与 diff 全部在浏览器里完成。

打开 OSI Playground