Apache Ossie字段规范详解：多方言表达式与时间维度标记

Apache Ossie字段规范详解多方言表达式与时间维度标记【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossieApache Ossie 是一个行业级的开源语义元数据规范旨在标准化分析、AI 与 BI 平台之间的语义数据交换为语义层提供厂商中立的唯一事实来源。其中字段Field定义是最核心的构建单元它决定了指标、过滤和分组如何在 Snowflake、BigQuery、Databricks 等平台上被一致地执行。本文将带你快速掌握两大关键机制——多方言表达式dialects与时间维度标记is_time。上图展示了 Ossie 的三层架构逻辑层Logical Layer正是字段与指标表达式发挥作用的层级使用可移植的 Ossie SQL 表达式语言与底层各数据库的原生 SQL 解耦参见 core-spec/expression_language.md。一、字段对象结构一览在 core-spec/spec.md 中字段定义在数据集dataset内部是行级属性可用于分组、过滤和指标表达式。核心属性如下属性类型必填说明namestring✅字段在数据集内的唯一名称expressionobject✅带方言支持的表达式定义dimensionobject❌维度元数据如is_time时间角色标记datatypestring (enum)❌逻辑数据类型Date、Integer、String等 10 种description/ai_contextstring❌描述与 AI 同义词上下文 注意区分两个独立属性datatype回答值是什么类型dimension.is_time回答它扮演时间维度角色吗——这正是下面要展开的重点。二、多方言表达式一份字段定义多平台运行expression 对象结构字段的expression是一个对象通过dialects数组声明一份字段在多种 SQL 方言下的写法spec.md 表达式对象expression: dialects: - dialect: ANSI_SQL # 必须取自 dialects 枚举缺省即默认方言 expression: customer_id # 标量 SQL 表达式不允许聚合规范内置了 7 种标准方言spec.yaml#L32-L39ANSI_SQL标准 SQL默认SNOWFLAKE、DATABRICKS、BIGQUERYMDX、TABLEAU、MAQLGoodData 查询语言何时需要多份方言版本当同一逻辑计算在不同引擎上语法或语义不一致时可为同一字段提供多个方言版本。官方示例是一个归一化邮箱字段spec.md 多方言字段示例- name: email_normalized expression: dialects: - dialect: ANSI_SQL expression: LOWER(email) - dialect: SNOWFLAKE expression: LOWER(email)::VARCHAR - dialect: BIGQUERY expression: SAFE_CAST(LOWER(email) AS STRING)执行端会根据目标平台选择对应版本未选中的方言可被安全忽略。常见方言差异速查规范专门整理了一张各引擎函数差异表expression_language.md 方言变体写表达式前值得先扫一眼场景ANSI_SQL / SnowflakeBigQueryPostgreSQL截断到月DATE_TRUNC(month, d)DATE_TRUNC(d, MONTH)DATE_TRUNC(month, d)加 7 天DATEADD(day, 7, d)DATE_ADD(d, INTERVAL 7 DAY)d INTERVAL 7 days字符串拼接CONCAT(a, b)CONCAT(a, b)a \|\| b✅最佳实践优先使用核心可移植函数如COALESCE、SUM、CASE WHEN只有当核心函数无法表达时才声明方言版本方言扩展的完整规则见 Dialect Extensions 章节。三、is_time 时间维度标记类型与角色分离为什么需要 is_time日期列不一定是时间维度比如审计用的created_at反过来整数年份、字符串季度名也可以是时间维度。Ossie 因此把数据类型datatype与时间角色dimension.is_time解耦官方称之为type vs. rolespec.md 详细说明datatype字段持有何种类型的值如Date、DateTimeTz、Integerdimension.is_time消费者BI 工具、AI 查询生成是否应把它当作时间轴处理is_time 默认规则速查未显式设置时is_time按数据类型自动推断spec.yaml 字段定义组合示例datatypeis_time实际角色原因d_date日历日期Date省略⏰ 时间维度时间类型默认truecreated_at审计时间戳DateTimefalse普通维度显式退出时间默认d_year整数年份Integertrue⏰ 时间维度非时间类型显式声明角色d_quarter_name如 Q1Stringtrue⏰ 时间维度字符串型时间粒度customer_idInteger省略普通维度非时间类型默认false真实示例TPC-DS 日期维表仓库自带的 TPC-DS 示例语义模型examples/tpcds_semantic_model.yaml展示了三种典型写法- name: d_year # 整数年份 → 显式 is_time: true datatype: Integer dimension: is_time: true - name: d_quarter_name # 字符串季度名 → 仅用 is_time 声明时间角色 dimension: is_time: true而同表的代理键d_date_skInteger 类型则被显式标记为is_time: false避免被误当作时间轴——这正是显式声明优先于默认值的体现。给消费端的两条建议类型问题类型转换、序列化优先看datatype不要从is_time: true反推具体标量类型角色问题时间轴 UI、时序聚合只要is_time解析为true无论显式还是默认就按时间维度处理四、上手检查清单先写 ANSI_SQL它是默认方言保证模型在任何实现上可读spec.md 完整示例差异函数再补方言对照方言差异表为 BigQuery/Snowflake 等补充dialects版本给每个字段问一句它是时间轴吗是则确保is_time为true显式或依赖时间类型默认不是则对时间类型列显式写is_time: false补上 ai_context 同义词帮助 AI 工具识别字段业务含义相关资源核心规范文档core-spec/spec.md机器可读 YAML 模式core-spec/spec.yamlJSON Schema 校验core-spec/osi-schema.json表达式语言规范core-spec/expression_language.md示例语义模型examples/tpcds_semantic_model.yaml、examples/flights.yaml项目入口文档docs/index.md 规范当前为 0.2.0.dev 草案版本schema 在正式发版前可能调整生产环境接入前请留意版本变更。【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考