OraAI代理资源指南

文档获取方式

AI代理可通过以下方式获取OraAI文档：

• 完整参考：https://docs.oraai.chat

语义层核心组件

1. 模型定义

name: orders
description: "电商平台订单交易记录"
dimensions:   # 分析维度
  - name: order_date
    type: date
measures:     # 可聚合指标
  - name: revenue
    type: decimal
metrics:      # 业务指标
  - name: aov
    expr: "sum(revenue)/count(distinct order_id)"

最佳实践：

• 使用snake_case命名规范
• 按业务领域组织模型文件
• 至少包含dimensions/measures/metrics中的一种

2. 维度(非数值属性)

dimensions:
  - name: customer_level
    description: "会员等级（普通/VIP/黑金）"
    type: string
    searchable: true

类型体系：

• 时间类：timestamp/date
• 文本类：string
• 状态类：boolean

3. 指标(数值度量)

measures:
  - name: payment_amount
    description: "实际支付金额(人民币元)"
    type: decimal

注意：type字段表示原始数据类型，非聚合方式

4. 业务指标

metrics:
  - name: retention_rate
    description: "次日留存率"
    expr: "count(distinct case when...)/count(distinct...)"

AI代理开发准则

配置规范

1. 结构组织：
   • 优先定义必填字段(name/description)
   • 保持命名一致性(snake_case)
   • 按业务域划分模型文件
2. 关系处理：
   • 明确指定source_col和ref_col
   • 合理定义cardinality
   • 避免未经验证的关联假设
3. 描述规范：
   • 维度/指标：说明含义、计算逻辑、分析用途
   • 业务指标：解释计算方法和业务意义
   • 关联关系：阐明业务联系和分析价值

数据验证原则

• 禁止假设字段具体取值
• 必须验证模型间引用有效性
• 关系定义需基于实际证据：
  • 匹配的列名模式
  • 数据库外键约束
  • 明确的文档说明

dbt集成指南

元数据命令

# 安全命令(不影响生产数据)
dbt ls          # 列出所有模型
dbt docs generate  # 生成元数据
dbt describe    # 显示依赖关系

工作流整合

1. 使用orai-cli generate从dbt生成语义模型
2. 通过orai-cli parse验证模型
3. 用orai-cli deploy部署语义层

建模最佳实践

• 字段命名：
  • 包含单位说明(如amount_usd)
  • 避免通用名称(如value)
• 文档规范：
  • 说明计算逻辑和数据质量注意事项
  • 标注衍生字段的特殊处理方式
• 关系设计：
  • 保持键名模式一致性
  • 通过dbt测试验证完整性
  • 考虑双向关系文档

通过遵循这些规范，AI代理可以构建出高质量的语义层配置，为自然语言查询提供可靠的数据基础。

---