| name | bi-semantic-layer-guide |
| description | 语义层工具使用规范。在发现语义层工具可用、需要查询指标定义/维度信息、验证业务口径、处理指标歧义时,必须优先调用此技能。无语义层工具时不调用。 |
bi-semantic-layer-guide
概述
语义层是统一管理业务语义元数据的服务,包括指标定义、维度定义、指标维度绑定和数据集映射。
可用工具
语义层暴露三类工具:
- 全局:
list_domains()
- 指标查询:
list_metrics(domain)、search_metrics(query, domain)、get_metric(name, domain)、get_north_star_metrics(domain)
- 维度查询:
list_dimensions(domain)、get_dimension(name, domain)、list_dimensions_of_metric(name, domain)、get_dimension_hierarchy(name, domain)、get_dimension_values(name, domain)
- 数据集查询:
list_datasets(domain)、get_dataset_columns(name, domain)、get_dataset(name, domain)
具体参数和返回格式参见工具自身描述。
查询策略
指标匹配
在语义层中查找指标,可选策略:
- 语义检索(
search_metrics),语义层会自动匹配同义词
- 查看具体业务域的北极星指标列表(
get_north_star_metrics),从中选择最相关的
- 若以上均未命中,列出该域全部指标(
list_metrics),逐一判断和分析条目的相关性。
指标属性确认
通过 get_metric 获取指标属性,重点属性:
- 是否是北极星指标(
is_north_star):用于角色分配
- 是否展示指标(
is_display):该指标是否应出现在展示面板中
- 是否展示分布(
is_display_distribution):展示指标时是否同时展示分布图
- 维度绑定(
dimensions):指标可拆解的维度列表,含 is_display_dimension、is_contribution_dimension 标记。
维度信息获取
通过 list_dimensions_of_metric 获取指标可拆解的维度列表(is_contribution_dimension=true 的维度才可用于贡献度拆解),通过 get_dimension_hierarchy 获取维度间的父子层级关系。
消歧规则
搜索指标时可能遇到歧义,按以下规则处理:
- 匹配到多个指标:优先选北极星指标(
is_north_star=true)。若仍有多个候选,结合指标类型和标签综合判断,必要时向用户确认。
- 精确名称 vs 同义词:若同时出现精确名称匹配和同义词匹配,精确名称优先。例如搜索"DAU",若同时命中指标名为"DAU"的指标和同义词含"DAU"的"访问用户数",取前者。
- 同名指标跨业务域:若同一指标名出现在多个业务域中,用当前分析任务的业务域限定范围。