OraAI语义模型规范指南

模型对象结构

1. 根模型配置(Model Object)

name: fct_order_main                  # 必填 - 数据集名称，必须与数据库中表名称一致。
label: 订单主表                        # 可选 - 数据集助记名。
data_source_name: ec_demo           # 可选 - 数据源名称，默认继承ora.yml。
description: >                        # 必填 - 数据集描述，定义数据集使用场景
  此表记录电商业务中订单的主要信息。包含订单基本信息、买家信息、支付信息以及订单状态等。
  可用于分析订单整体情况、销售业绩、客户购买行为等，辅助电商企业进行运营决策和客户关系管理等。       

dimensions:                           # 必填 - 维度列表。用于分组的字段，通常为字符、时间类型。
  - name: order_date
    type: date
measures:                             # 必填 - 度量列表。用于聚合计算的字段，通常为数字类型。
  - name: amount
    type: double

关键字段说明：

• 必填字段：name, description
• 可继承字段：data_source_name, database, schema
• 组件类型：dimensions/measures/metrics/filters

核心组件规范

2. 维度(Dimension)

dimensions:
  - name: payment_method  # 必填
    description: "支付方式(微信/支付宝/银行卡)"  # 必填
    type: string         # 必填
    searchable: true     # 可选，默认false
    options:             # 枚举值示例
      - "微信支付"
      - "支付宝"
      - "银联"

数据类型支持：

• 基础类型：string, int, decimal
• 时间类型：date, timestamp
• 布尔类型：boolean

3. 度量(Measure)

measures:
  - name: total_amount  # 必填
    description: "订单总金额(含税)"  # 必填
    type: decimal      # 原始字段类型

注意：type表示底层数据类型，非聚合方式

4. 业务指标(Metric)

metrics:
  - name: conversion_rate  # 必填
    expr: "count(order_id)/count(distinct session_id)"  # 计算表达式
    description: "访客转化率"  # 必填
    args:  # 动态参数
      - name: date_range
        type: string
        description: "统计周期"

5. 过滤器(Filter)

filters:
  - name: high_value_orders  # 必填
    expr: "amount > {{min_amount}}"  # 条件表达式
    description: "高价值订单筛选"  # 必填
    args:
      - name: min_amount
        type: decimal
        default: 1000

完整示例

电商模型示例

name: orders
description: "电商订单核心事实表"
dimensions:
  - name: order_id
    type: string
    description: "订单唯一标识"
    
  - name: order_date
    type: date
    description: "订单创建日期"

measures:
  - name: amount
    type: decimal
    description: "订单金额(元)"

metrics:
  - name: avg_order_value
    expr: "sum(amount)/count(distinct order_id)"
    description: "客单价"

最佳实践

1. 命名规范

• 使用snake_case命名法
• 保持字段名与数据库一致

2. 文档质量

• 描述需包含业务含义和计算逻辑
• 枚举值需明确业务选项

3. 关系设计

• 确保source_col/ref_col类型匹配
• 多对多关系需通过中间表实现

4. 版本控制

• 模型文件按业务域拆分
• 重大变更需保留版本历史

该规范为构建可解释、可维护的语义层提供了标准化框架，建议结合具体业务需求进行定制化扩展。

---