限制项 | 说明 |
创建权限 | 指标创建需要模型的 CreateMetric 或 Manage 权限;指标创建不需要底层表 Select 权限 |
编辑形态 | 指标与维度均通过 YAML 编辑器编辑 |
维度 ACL | 维度本期暂不支持精细化 ACL 权限,所有有「语义建模 → 维度管理」的 Read Write 或 Read Write & Delete 功能权限的用户均可编辑、删除 |
SUM(OrderAmount) 表示「交易总金额」。原子指标不涉及衍生逻辑。SUM(OrderAmount) 限定 渠道 = 线上。交易总金额 / 交易数量。下单量 / 注册量。SUM、COUNT、COUNT(DISTINCT)、MAX、MIN、AVG,以及自定义表达式。formula 字段引用的指标必须是同一模型下已发布或同 YAML 中同时定义的指标,否则发布时校验失败。SIMPLE / FILTER / DERIVED / RATIO / CUMULATIVE / CONVERSION)以及 3 类维度(TIME / CATEGORICAL / DICT)。可作为编写实际 YAML 时的参考模板。# ============================================================# WeData 语义模型 YAML 配置完整示例# 版本:1.0# 说明:通过此 YAML 可一次性创建语义模型、指标、维度# ============================================================# 【必填】配置文件版本号,固定为 1.0version: 1.0# ============================================================# 语义模型定义(可选)# type: DEF - 新建模型(需提供完整定义)# REF - 引用已有模型(只需 name + type)# ============================================================model:# 【必填】模型英文名,1-50字符,支持字母、数字、下划线、括号name: ecommerce_order_model# 【可选】模型别名列表,支持多个,不允许含逗号# 为空时默认使用 name;存入数据库时以逗号分隔存储label:- 电商订单模型- order_model_alias# 【可选】模型描述description: "电商业务订单主模型,关联用户表和商品表"# 【必填】模型类型:DEF(定义新模型) | REF(引用已有模型)type: DEF# 【DEF必填】主表数据源路径,格式:catalogName.databaseName.tableNamesource: default_catalog.ecommerce_db.orders# 【可选】关联表配置,支持嵌套 JOINjoins:- name: user_table # 关联表别名(必填)source: default_catalog.ecommerce_db.users # 关联表路径(必填)on: # 关联条件(必填,至少一个)- source.user_id = user_table.id# 嵌套关联(可选)joins:- name: user_addresssource: default_catalog.ecommerce_db.addresseson:- user_table.id = user_address.user_id- name: product_tablesource: default_catalog.ecommerce_db.productson:- source.product_id = product_table.id# ============================================================# 指标定义列表(可选)# 支持类型:SIMPLE | FILTER | DERIVED | RATIO | CUMULATIVE | CONVERSION# ============================================================metrics:# ----------------------------------------------------------# 1. 原子指标(SIMPLE)- 基础聚合指标# ----------------------------------------------------------- name: total_order_amount# 【可选】指标别名列表,支持中英文、数字、下划线、括号,不允许含逗号label:- 订单总金额- GMVdescription: "统计所有有效订单的总金额"# 【必填】指标类型type: SIMPLE# 【必填】类型参数type_params:# 【可选】关联模型引用,填写 model 的 name# 不填时默认使用当前 YAML 中定义的 modelmodel_ref: ecommerce_order_model# 【必填】源表路径,格式:catalogName.databaseName.tableNamesource_table: default_catalog.ecommerce_db.orders# 【必填】聚合表达式expr: "SUM(order_amount)"# 【必填】时间维度名称(需在 dimensions 中定义对应的 TIME 类型维度)time_dimension: order_date# 【可选】非可加维度配置(用于半累加指标,如库存快照)# non_additive_dimension:# dimension: snapshot_date # 维度名称(必填)# window_choice: MAX # 窗口取值:MIN | MAX(必填)# window_groupings: # 窗口分组(可选)# - warehouse_id# ----------------------------------------------------------# 2. 筛选型指标(FILTER)- 在原子指标基础上加过滤条件# ----------------------------------------------------------- name: paid_order_amountlabel:- 已支付订单金额description: "仅统计已支付状态的订单总金额"type: FILTERtype_params:# 【必填】筛选条件表达式filter: "status = 'PAID'"# 【必填】依赖的基础指标列表(至少一个)metrics:- name: total_order_amount# ----------------------------------------------------------# 3. 混合计算型指标(DERIVED)- 多指标表达式运算# ----------------------------------------------------------- name: avg_order_amountlabel:- 平均客单价description: "订单总金额 / 订单总数"type: DERIVEDtype_params:# 【必填】计算表达式,使用指标名称作为变量expr: "total_order_amount / order_count"# 【必填】参与计算的基础指标列表(至少一个)metrics:- name: total_order_amount- name: order_count# ----------------------------------------------------------# 4. 同环比指标(RATIO)- 时间周期对比# ----------------------------------------------------------- name: order_amount_yoylabel:- 订单金额同比description: "订单总金额的同比增长率"type: RATIOtype_params:# 【必填】计算类型:YEAR_ON_YEAR(同比) | RELATIVE_RATIO(环比)derived_type: YEAR_ON_YEAR# 【必填】基础指标列表(至少一个)metrics:- name: total_order_amount# ----------------------------------------------------------# 5. 累积计算型指标(CUMULATIVE)- 时间窗口累积# ----------------------------------------------------------- name: weekly_order_amountlabel:- 近7日订单金额description: "最近7天的订单金额累积值"type: CUMULATIVEtype_params:# 【必填】时间窗口,可选值:# MINUTE_5 | MINUTE_30 | HOUR_1 | DAY_1 | DAY_7 | DAY_30 | DAY_90 | DAY_180# WTD(本周至今) | MTD(本月至今) | QTD(本季度至今) | YTD(本年至今) | HTD(历史至今)window: DAY_7# 【可选】额外筛选条件filter: "status IN ('PAID', 'SHIPPED')"# 【必填】基础指标列表(至少一个)metrics:- name: total_order_amount# ----------------------------------------------------------# 6. 转化类指标(CONVERSION)- 漏斗转化分析# ----------------------------------------------------------- name: view_to_purchase_ratelabel:- 浏览到购买转化率description: "用户从浏览商品到下单购买的转化率"type: CONVERSIONtype_params:# 【必填】基准指标(漏斗起点)base_metric:name: page_view_count# 【必填】转化指标(漏斗终点)conversion_metric:name: purchase_count# 【必填】转化实体类型:FROM_ENTITY | FROM_DIMENSIONconversion_entity_type: FROM_DIMENSION# 【可选】转化维度(conversion_entity_type 为 FROM_DIMENSION 时使用)conversion_dimension: user_id# 【必填】计算方式:CONVERSIONS(转化值) | CONVERSIONRATE(转化率)calculation: CONVERSIONRATE# 【可选】窗口类型:WINDOW(N时间内转化) | OFFSET(第N时间转化)window_type: WINDOW# 【可选】时间窗口,格式:{数字} {hour|day|week|month}window: "7 day"# ----------------------------------------------------------# 7. 转化类指标(CONVERSION)- FROM_ENTITY 示例# 通过实体(主键/关联键)关联基准指标和转化指标# ----------------------------------------------------------- name: register_to_order_conversionslabel:- 注册到下单转化数description: "用户从注册到首次下单的转化数量,通过用户实体关联"type: CONVERSIONtype_params:# 【必填】基准指标(漏斗起点)base_metric:name: user_register_count# 【必填】转化指标(漏斗终点)conversion_metric:name: total_order_amount# 【必填】转化实体类型:FROM_ENTITY 表示通过实体(主键)关联两个指标# FROM_ENTITY: 两个指标通过同一实体(如用户ID)自动关联,无需指定 conversion_dimension# FROM_DIMENSION: 需要手动指定 conversion_dimension 字段来关联conversion_entity_type: FROM_ENTITY# 【必填】计算方式:CONVERSIONS(转化数) | CONVERSIONRATE(转化率)calculation: CONVERSIONS# 【可选】窗口类型:WINDOW(N时间内转化) | OFFSET(第N时间转化)window_type: OFFSET# 【可选】时间窗口,格式:{数字} {hour|day|week|month}window: "30 day"# ============================================================# 维度定义列表(可选)# 支持类型:TIME | CATEGORICAL | DICT# ============================================================dimensions:# ----------------------------------------------------------# 1. 时间维度(TIME)- 必须指定时间精度# ----------------------------------------------------------- name: order_date# 【可选】维度别名列表,支持多个,不允许含逗号label:- 下单日期- 订单时间description: "订单创建时间,精确到天"# 【必填】数据源路径,格式:catalogName.databaseName.tableNamesource: default_catalog.ecommerce_db.orders# 【必填】对应的数据库列名col_name: created_time# 【必填】维度类型type: TIME# 【TIME类型必填】类型参数type_param:# 时间精度,可选值:YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECONDtime_precision: DAY# ----------------------------------------------------------# 2. 普通维度(CATEGORICAL)# ----------------------------------------------------------- name: order_channellabel:- 订单渠道description: "订单来源渠道:APP/PC/H5"source: default_catalog.ecommerce_db.orderscol_name: channeltype: CATEGORICAL# CATEGORICAL 类型不需要 type_param,不填# ----------------------------------------------------------# 3. 字典维度(DICT)- 关联字典表# ----------------------------------------------------------- name: order_statuslabel:- 订单状态description: "订单状态码,关联字典表"source: default_catalog.ecommerce_db.orderscol_name: status_codetype: DICT# 【DICT类型必填】类型参数type_param:dict_items:- key: Shippedvalue: 已发货- key: Completedvalue: 已完成- key: Canceledvalue: 已取消
version: 1.0 是配置文件版本号,固定为 1.0。model.type = DEF 时需要提供完整模型定义(source + joins);改为 REF 时仅需 name + type,表示引用已有模型。type_params 形态各不相同:SIMPLE 通过 expr(聚合表达式)+ time_dimension 定义;FILTER 在 metrics 引用的原子指标上叠加 filter 条件;DERIVED 用 expr 引用其他指标名称做四则运算;RATIO 用 derived_type(YEAR_ON_YEAR / RELATIVE_RATIO)声明同环比;CUMULATIVE 用 window(如 DAY_7 / MTD)声明时间窗口累积;CONVERSION 通过 base_metric / conversion_metric / conversion_entity_type / calculation / window 声明漏斗转化。type_param 形态:TIME 必填 time_precision(如 DAY / HOUR / MONTH);CATEGORICAL 无 type_param;DICT 通过 dict_items 声明 key-value 映射。name 引用全局维度,避免重复声明。order_date(订单创建日期)、pay_time(支付完成时间),常按天、周、月切片。category_name(商品类目)、brand(品牌)、gender(性别)。user_name(用户名)、age(年龄)、user_id(用户 ID)。A / B)或文字描述,每种指标类型会根据其类型展示不同的计算逻辑信息。select * from query(metric=[avg_session_behavior_count], limit=30)
上游:表和视图(2) 语义模型(1) 上游:指标(2) 当前指标┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐│ 订单事实表 │─>│ Customer … │─>│ metric.会话数 │─>│ avg_se… ││ ODS 数据表 │ │ Behavior … │ │ metric.行为数 │ │ count │└──────────────┘ └──────────────┘ └──────────────┘ └──────────┘
字段 | 是否必填 | 说明 |
授权主体 | 是 | 可选择用户、用户组、标签 |
授权对象 | 是 | 如果授权主体选用户:此处展示选用户面板,支持搜索用户;至少添加 1 个 如果授权主体选用户组:此处展示选用户组面板,支持搜索用户组;至少添加 1 个 如果授权主体选标签:无需选择授权对象,仅需选下面的授权点即可 |
授权点 | 是 | 至少勾选 1 项;未勾选时提交按钮置灰并提示「请选择权限点」。可支持设置授权对象可查询的指标行列权限。 |
授权原因 | 否 | 多行文本,用于审计与业务背景说明 |
用户输入 |
「在我的 olist_sales_model 语义模型下,新增一个 gmv 指标。统计逻辑是对 dlc.default_catalog.olist.orders 表中的 pay_amount 字段求和,用以对所有订单的支付金额求和(总交易额),注意统计时,剔除掉内部客户(客户类型为“internal”)下单的数据」 |
用户输入 |
创建「支付时间」维度,表名 dlc.default_catalog.olist.orders,字段名 pay_time,最小时间粒度按日 DAY,表示订单实际支付完成的时间点," |
catalog.database.table,例如 dlc.default_catalog.olist.orders。CreateMetric 权限;无权限会拒绝创建。formula 中能引用其他模型的指标吗?
不能。派生指标只能引用同一模型下的指标。COUNT(DISTINCT) 被某些引擎不直接支持,需确认平台支持的去重写法;③ 自定义 SQL 中的函数名不被引擎识别。建议先用底层表在 SQL 编辑器中验证表达式可执行后再发布。文档反馈