metrics

指标

指标是语义模型中完全限定的度量： crm_deals.amount。应用的 指标页面会列出从数据源构建的立方体中的所有度量；指标自己的页面则可以按范围（一个分段或若干条件）统计该指标，并按某个维度拆分——这与仪表板卡片保存的三个设置相同。此技能仅用于读取；不会在此写入任何内容。

对于与单个指标无关的临时分析问题——例如同时查询多个度量、自定义分组或跨立方体执行 Top-N 分析——语义模型技能更合适。用户以命名指标的方式思考，或想知道卡片显示的数值时，使用此技能。

指标目录

api_read { "resource": "cubes", "method": "meta", "params": { "fields": "name,title,description,type", "pageSize": 100 } }
api_read { "resource": "cubes", "method": "meta", "params": { "filter": "name == \"crm_deals\"" } }

应用仅列出源立方体中的度量。以下内容不纳入：

• type: "view" — 表的视图（model_…）会以新名称重新导出度量；每个此类度量的 aliasMember 都指向原始度量；
• 生成的立方体，标记为 meta.abConnectionId: "revos" — 分段快照（segment_…）和表自身的列（model_stream_…）。 meta 不能通过 fields 投影；不过读取候选立方体时，本来就会读取完整记录。

目录中每个度量显示的内容：

列	来自 meta
指标	title（description 作为其工具提示），name 作为引用
立方体	立方体的 title
聚合	aggType：count、countDistinct、sum、avg、min、max、number 等
格式	format 为 currency / percent，否则按类型显示：Number、Text、Boolean、Date

只有 type: "number" 的度量才能在卡片上统计；如果用户选择了文本、布尔值或时间类型的度量，请告知这一点。

用户按含义（“胜率”“ARR”）查找指标时，请搜索标题和描述。如果没有匹配项，请如实说明并提供最接近的选项，或建议使用立方体技能添加指标——切勿悄悄用其他度量代替。

指标的使用位置

• 表：视图 model_<table id, '-' → '_'> 会重新导出该度量（aliasMember == "<measure>"）。使用 api_read { "resource": "tables", "params": { "fields": "id,name" } } 将 ID 映射回表。
• 分段：该度量（或其视图别名）是分段 filter 中的 member。
• 仪表板：api_read { "resource": "dashboard-cards", "params": { "filter": "measure == \"<measure>\"" } }。

指标的值

api_read { "resource": "cubes", "method": "query", "body": { "query": … } }， 必须严格按应用构建查询的方式构建——否则结果数值会与用户屏幕上的不同：

{
  "measures": ["<measure>"],
  "filters": [ <the scope's conditions, as Cube filters> ],
  "joinHints": [ <each join path, split on "."> ]
}

filters / joinHints 为空时省略。

范围

• 所有行——不加筛选条件。
• 条件——使用分段筛选语法编写（参见分段技能的 references/filter-syntax.md），并根据其对照表转换： EQUAL → equals，EMPTY → notSet，CHECKED → equals "true" 等。 顶层的 AND 项分别作为独立的 filters 条目；OR 转换为 { "or": [ … ] }， AND 组转换为 { "and": [ … ] }。跳过没有 member 的条件，或在运算符需要 value 时缺少 value 的条件——应用也会这样处理。对字符串执行 EQUAL 前， 请先通过立方体查询检查已存储的值。
• 动态分段——读取该分段；以相同方式转换它的 filter，并先将 cubes[1..].joinPath 放入 joinHints。
• 静态分段——用一个筛选条件代替其各项条件： { "member": "segment_<segment id, '-' → '_'>.id", "operator": "set" }。 这需要 meta 中包含相应的 segment_… 立方体。

只有当分段的根立方体与指标所属立方体相同 （segment.cubes[0].joinPath）时，才能将其用于该指标。公司分段不能限定交易指标——请说明这一点，并提供改用公司字段设置条件的方案。

关联到其他立方体

在其他立方体上的条件或拆分，会沿着从指标所属立方体出发的关联路径读取数据：crm_deals.crm_companies。检查 meta 中声明的 joins，核对路径上的每一跳（任一侧声明均可）。如果存在两条路径，选择不同，结果也会不同——询问用户想用哪条路径。将每条路径作为关联提示传入，例如 ["crm_deals", "crm_companies"]；指标所属立方体本身无需提示。

应用会拒绝以下两种条件，你也应如此：

• 对度量的条件（crm_deals.count > 3）。对于汇总值，这不是逐行条件；它不属于筛选范围。
• 对指标行对应多个记录的立方体设置条件（路径上存在 hasMany / one_to_many）：每行都会针对每条关联记录检查一次。

拆分

在相同查询中添加维度：

• 非时间维度："dimensions": ["<dim>"]， "order": { "<measure>": "desc", "<dim>": "asc" }——按组从大到小排列。
• 时间维度："timeDimensions": [{ "dimension": "<dim>", "granularity": "month" }]， "order": { "<dim>": "desc" }——按月份从最新到最早排列。

只有当度量为 count 或 sum，且拆分路径不经过指标行对应多个记录的关联时，各组之和才会等于总数。否则，不要展示占比或“其他”类别；如果拆分路径会造成行数扩增，请说明关联到多个组的记录会在每个组中重复计数。卡片展示排名前 5 的组和“其他”；指标页面展示 50 组。

解读结果

• 没有行：count、count distinct 或 sum 的结果为 0；平均值或其他度量则没有值——应说“没有值”，而不是 0。
• 按度量的 format 格式化（货币、百分比）。
• 始终说明这个数字的统计对象：“€1.2M 的未结商机管道金额，统计对象为 EMEA 细分市场中的商机”。
• 结果中的 metadata.lastRefreshTime 表示数据的新鲜程度；如果数据较旧或设置了 slowQuery，请提及。

单个值显示为一行，拆分结果显示为简洁表格；必要时也可以使用图表。