指标定义

指标定义是指已商定并写下计算方式的业务数字：Net Revenue、Headcount (FTE)、Units Shipped。它说明数字来自哪张表、如何汇总行、哪些行计入，以及可以按哪些列进行细分。

如果没有指标定义，向 AI 助手提问“上个季度 EMEA 的净收入是多少？”时，助手会自行决定使用哪张表、哪一列和哪些筛选器，两个人问同样的问题可能得到两个不同的数字。指标定义把这个决定权从助手手中拿走。项目架构师只需撰写一次定义，从保存的那一刻起，助手就完全按照所写的方式计算数字。

架构师：从定义指标开始。分析师：从询问指标开始。

指标定义是一份配方，而不是存储的结果。每次被询问时都会重新计算，并遵循提问者的行访问权限：只能看到 EMEA 的人得到的是 EMEA 的数字。两个人可能从同一个定义得到不同的合计，因为他们看到的行不同；计算方式是相同的。

定义包含的内容

部分	说明	示例
名称	人们对这个数字的称呼。最多 200 个字符。	Net Revenue
同义词	人们对它使用的其他说法，以便助手识别问题。最多 25 个。	revenue、sales
说明（API 中为 `memo`）	数字的含义及适用场景，供助手和人员参考。最多 1,000 个字符。	Revenue after returns and discounts. Use for all revenue questions.
源表	行的来源表。	`sales_fact`
联接	通过匹配列与源表联接的查找表。每张查找表的每个键只能有一行（例如每个区域代码一行），否则它匹配到的行会被重复计算。	`region_lookup`，将源表中的 `region_code` 与查找表中的 `code` 匹配
度量	如何汇总行：某一列的 `sum`、`count`、`count_distinct`、`min`、`max` 或 `avg`，或以第二列（`weight`）为权重的某一列的 `weighted_avg`：在两者都有值的行上，值乘以权重之和，再除以这些权重之和；若权重之和为零则为空。	`net_amount` 的 `sum`；以 `units` 为权重的 `unit_price` 的 `weighted_avg`
筛选器	哪些行始终计入。每个筛选器由一列、一个运算符（`eq`、`ne`、`in`、`not_in`、`lt`、`le`、`gt`、`ge`、`between`、`is_null`、`not_null`）及其值组成。	`status` `eq` Posted
细分列（API 中为 `grain`）	提问时可以用来分组和筛选的列。筛选器是固定的；细分列由提问者选择。	`region_lookup.region`、`product_line`、`fiscal_year`
方案（可选）	区分实际数据行和预算数据行的列，以及各自的值。指标取其实际数据行；预算数据行仅在进行差异比较时才会被读取。	`scenario`，实际为 Actual，预算为 Budget
维度（可选，API 中为 `dimensions`）	绑定到某个维度的细分列，这样问题中的词语会与该维度的成员和别名匹配，并转换为该列的值：请参阅询问指标。该维度必须存在于项目中。	`region_lookup.region` 绑定到 Region 维度
时间列（可选，API 中为 `time`）	一个日期列，或一个财年列加一个期间列，这样问题就可以询问某个财务期间，并随时间比较。	`fiscal_year` 和 `fiscal_period`

来自查找表的列写作 <table>.<column>；助手会替您写好这些内容。定义中的每张表和每一列都必须存在于项目中；若定义中指明了不存在的表或列，保存时会被拒绝。带有方案的指标不能按方案列筛选，也不能将其作为细分列提供：方案决定读取哪些行，因此类似 scenario eq Actual 的筛选器应放在方案中，而不是筛选器中。

指标还可以由其他指标构建，作为比率、和、差或倍数：请参阅由其他指标派生指标。

项目中的两个指标完全可以使用相同的名称或同义词，没有任何限制。请保持它们互不相同，否则助手只能猜测您指的是哪一个，或者向您询问。

谁可以做什么

项目架构师可以编写、编辑和停用定义。公开项目名义上会授予每个成员架构师角色，但这不算数：在公开项目中任何人都不能定义指标，因此请把指标放在拥有独立访问列表的项目中。
任何可以读取该项目的人可以查看和运行定义。
已锁定的项目会拒绝一切更改。 定义、编辑和停用都要等到项目解锁之后。

定义指标

如果您是项目架构师，请用自然语言请您连接的 AI 助手：

“在 Sales 项目中，定义一个名为 Net Revenue 的指标，同义词为 revenue 和 sales：sales_fact 中 net_amount 的总和，通过 region_code 联接到 region_lookup，可按查找表的 region、product_line 和 fiscal_year 细分；其实际数据行的 scenario 为 Actual，预算数据行的 scenario 为 Budget。”

助手会保存它，并在其所指的表或列不存在时告知您。指标一经保存即刻生效。每次编辑都会生成定义的一个新版本，由编辑者署名，读者会立即获得新版本。未做任何更改的保存会被拒绝。最近一次保存的版本就是该指标的当前版本。

对于开发人员，通过 REST API 提交的同一定义如下：

POST /rest/v1/analyze/metric/definition
{
  "project_id": "<project>",
  "name": "Net Revenue",
  "synonyms": ["revenue", "sales"],
  "memo": "Revenue after returns and discounts. Use for all revenue questions.",
  "definition": {
    "source": "sales_fact",
    "joins": [{"table_id": "region_lookup", "on": [["region_code", "code"]]}],
    "measure": {"agg": "sum", "column": "net_amount"},
    "filters": [],
    "grain": ["region_lookup.region", "product_line", "fiscal_year"],
    "scenario": {"column": "scenario", "actual": "Actual", "budget": "Budget"},
    "time": {"year_column": "fiscal_year", "period_column": "fiscal_period"}
  }
}

on 中的每一对是 [source column, lookup column]。time 可以是 {"year_column", "period_column"}（可带可选的 periods_per_year），也可以是用于日期列的 {"column"}（可带可选的 fiscal_year_start 和 fiscal_year_label）；请参阅随时间比较。

保存时会检查什么

每次保存都会运行这些检查，未通过任何一项的定义都会被拒绝，并给出指明问题的消息：

每张表和每一列都存在于项目中。
每张查找表的每个键只有一行，以保存当时的数据为准。如果查找表中同一个键有两行，就会使其匹配的源表行翻倍，因此保存会被拒绝并指明该表。没有键值的查找行会被此检查忽略，因为它永远不会匹配任何源表行。
派生指标的输入存在，并且既未被停用，本身也不是派生指标。

每个版本都会记录保存者和保存时间。编辑指标会保存一个新版本，读者会立即获得该版本。

由其他指标派生指标

派生指标是对已有指标进行的算术运算：Net Revenue per FTE 就是 Net Revenue 除以 Headcount (FTE)。它的定义、被询问和停用方式与其他指标相同。不同之处在于它的定义，定义中指明的是其所基于的指标，而不是一张表。

运算	计算内容	输入
`ratio`	第一个输入除以第二个输入	两个指标
`add`	第一个输入加上第二个输入	两个指标
`subtract`	第一个输入减去第二个输入	两个指标
`scale`	输入乘以固定的 `factor`	一个指标和一个数字

输入是同一项目的基础指标，即上文所述由表定义的那类指标。派生指标不能由另一个派生指标构建，也不能两次使用同一个输入。

请告诉助手：

“在 Sales 项目中，定义一个名为 Net Revenue per FTE 的指标，为 Net Revenue 与 Headcount (FTE) 之比。”

通过 REST API 时，definition 按 id 指定输入，id 可从 metric_find 或定义列表获得。顺序很重要：第一个 id 是 ratio 的分子，也是 subtract 中被减数的指标。

{
  "kind": "derived",
  "op": "ratio",
  "inputs": ["<Net Revenue metric_id>", "<Headcount (FTE) metric_id>"]
}

scale 接受一个输入和一个 factor：{"kind": "derived", "op": "scale", "inputs": ["<Monthly Run Rate metric_id>"], "factor": 12} 可将月度数字年化。

计算方式。 每个输入都会按您要求的细分方式、在您的行访问权限下单独计算，然后针对每个细分值合并结果。先分别汇总每个输入再合并，才能确保两张表的比率可信：如果先联接行，每一行会按它在另一侧遇到的行数被重复计算。如果某个输入在某个细分值下没有行，该细分值的派生值为空；分母为零的比率同样为空；两者都不会被报告为零。

细分列是计算得出的，而非声明的。 派生指标只能按所有输入都允许的列进行细分，该列表会显示在其定义旁边。如果您想按区域询问派生指标，请为每个输入都提供 region_lookup.region 作为细分列，且拼写相同。如果输入之间没有共同的细分列，派生指标就只能回答单一总计。与其他指标一样，按其他任何内容分组或筛选的问题都会被拒绝。派生指标旁边的列表为空，表示它的某个输入已不可用：已停用或已缺失。

保存时会检查输入。 只有当每个输入都存在、未被停用且本身不是派生指标时，才能保存派生指标。读者和架构师始终获得每个输入以及派生指标的当前版本。输入不会固定在某个版本：当保存了输入的后续版本时，派生指标的数字也会随之变化。

只要有派生指标在使用，输入就保持在用状态。 它不能被停用，也不能被改为派生指标；拒绝消息会指明使用它的指标。要停用某个输入，请先停用派生指标，或保存一个不再使用该输入的版本。

询问指标

任何可以读取项目的人都可以向 PlaidCloud 内置的 AI 助手或通过 MCP 连接的助手提问：

“FY26 各区域的净收入是多少？”

助手会通过名称或其某个同义词识别指标（查找时忽略大小写并匹配名称的一部分，因此 revenue 能找到 Net Revenue），从您的问题中获取细分方式和筛选器，然后运行该定义。问题只能按指标的细分列分组或筛选；询问其他任何内容的问题都会被拒绝，而不是靠猜测来回答。如果某个指标的表在保存后丢失了某一列，同样会被拒绝：拒绝消息会指明该指标及其版本，需要由架构师修复定义。

您的措辞会通过维度转换为该列的值。 当架构师将某个细分列绑定到维度后，助手会将您问题中的词语与该维度的成员名称和别名进行比对，忽略大小写。只命中一个成员的词语会变成该成员的值：叶子成员就是它自己的值，而像 EMEA 这样的父成员会展开为其下的每一个叶子成员，因此“EMEA 的净收入”会按 EMEA 的所有区域筛选。没有命中任何成员、或命中多个成员的词语（Seaboard 可能是两个成员上的别名，且都不与您使用的拼写完全一致），会作为候选列表返回，由助手向您确认；它绝不会替您选择其中一个。在维度中查找词语需要读取维度的权限，这与 PlaidCloud 中其他任何地方读取维度的要求相同。

助手所依据的结果会指明指标及其版本，并说明是否应用了行访问权限。如果答案没有说明使用了哪个指标，请询问。在 PlaidCloud 内置的 AI 助手中，数字会显示在带有 ✓ 的独立卡片中；请参阅来自指标的数字。关于 PlaidCloud 如何为 AI 答案评级并附上注意事项的更多信息，请参阅值得信赖的答案。

行访问权限会应用于指标读取的每张表，源表和每张查找表都一样。如果某个查找行对您隐藏，但它所标注的源表行并未隐藏，该源表行仍然计入。比如您看不到区域 APAC 的查找行，但能看到其销售额：这些销售额会计入您的总计，在按区域细分时出现在空白区域下，而如果您按区域筛选，或指标本身按某个查找列筛选，它们通常会被排除。

行访问权限也会影响查找：当细分列受到管控时，只会向您提供您的访问权限允许的值。其下没有任何您可见内容的成员绝不会被提供，无论作为值还是候选项；父成员也只会展开为您可见的叶子成员。读取所有行的架构师可以看到每个成员。

架构师可以读取每一行，这与他们在项目中的其他任何地方一样。

比较、排名和占比

关于指标的问题还可以要求一项比较、一项排名以及占总计的份额。每一项都是基于该指标自身数字的固定计算，并遵循提问者的行访问权限；没有一项是由助手自行算出的。

要求	返回内容	在 API 中
与预算的差异	对每个细分值：实际数字、预算数字、差值（`value`），以及差值占预算大小的百分比（`pct`），当预算为负时保留差值的符号。	`compare: "variance"`
占总计的份额	每行的数字除以细分的所有行的总计（`share`），或除以共享您所指定 `within` 列的行的总计。	`share: {"within": ["region"]}`；`{}` 表示总计
前 N 或后 N	最高的 N 个数字，或使用 `order: "asc"` 时最低的 N 个，并带有其 `rank`；指定 `within` 列时按组计算。并列的行共享同一名次且全部保留，因此返回的行数可能多于 N。对于成本指标，超出预算最多的是差异的前 N；对于收入指标，则是后 N。	`top: {"n": 10, "within": [], "order": "desc"}`

“在 Finance 项目中，哪五个成本中心超出预算最多？”

“每个区域占总支出的份额是多少，哪个区域最大？”

差异比较需要带有方案的指标；没有方案的指标或派生指标会拒绝它。两侧先各自汇总再进行比较：某个细分值如果没有预算行或没有实际行，其差值显示为空而不是零（例外是作为单一总计询问的 count 指标，其中没有行的一侧计为零），预算为零时的百分比也是如此。

排名和占比基于指标的数字；当要求差异或随时间比较时，则基于差值，因此“哪些成本中心占超支的大部分”就是带有占比和排名的差异比较。pct 是百分比，所以 12 表示 12%，而 share 是小数。占比是在前 N 保留部分行之前，基于细分的所有行计算的，因此您得到的各行占比之和不一定等于一。无论您要求哪种顺序，空数字都排在最后，并且占比为空；基于零总计的占比也一样。

占比是针对您能看到的内容。行访问权限仅限于 EMEA 的人，得到的是 EMEA 各成本中心占 EMEA 总计的占比，结果会说明已应用行访问权限。占比或排名的 within 列必须属于您所要求的细分列；并且，按与结果自身某一列同名的列分组的问题（value，以及在要求产生它们的运算符时的 actual、budget、current、prior、pct、share、rank、year、period 或 cumulative）会被拒绝。包含两项比较或两项排名的问题会被拒绝。

随时间比较

定义中带有时间列（API 中为 time）的指标，可以被询问某一个财务期间，并与前一个期间比较，以及逐期累计。时间列通过以下两种方式之一说明每行在财年日历中的位置：

日期列，配合 fiscal_year_start，即财年开始的日历月份（1 表示一月，为默认值）。其期间是财年的各个月份，从起始月份开始编号：如果财年从十月开始，则第 1 期是十月，第 7 期是四月。一个季度是其中三期。默认情况下，不从一月开始的财年以其结束的日历年命名（fiscal_year_label 为 ending）；将 fiscal_year_label 设置为 starting，则以其开始的年份命名。以十月为起点时，从 2025 年 10 月到 2026 年 9 月的月份默认属于 FY2026，使用 starting 则属于 FY2025。行按日期范围读取，这使得大表上的问题保持快速。
财年列加期间列，两者都是整数，分别保存财年（2026，而不是 26）和其中的期间（从 1 开始编号），并配合 periods_per_year：默认为 12，13 期日历为 13，按周为 52，按季度为 4。只有当期间能被四整除时才存在季度。含 53 周年份的日历可以设置 53，代价是失去季度。如果任一列的值不是整数，例如 2024-01 或 FY26，保存会被拒绝，拒绝消息会指明该列和该值。以文本存储的数字（如 07）会被接受，超出年度范围的期间也会被接受，例如账簿的第 0 期或第 13 期：关于某个期间的问题会排除这些行。

然后，问题会指明它所涉及的期间：一个财年，或其中的某个季度或某个期间。截至当期会把范围向前延伸到年初，因此“截至四月的年初至今”就是该年的前几个月，直到并包括四月。

“FY2026 第一季度按区域的销售额是多少，与前一个季度相比如何？”

“截至四月的年初至今销售额，与去年同期相比。”

“按月显示 FY2026 的销售额，并显示累计值。”

要求	返回内容	在 API 中
单个期间	仅该期间内的指标，包含常用的细分、占比和排名；与预算的差异比较会读取该期间内的两个方案。	`period: {"year": 2026}`；`{"year": 2026, "quarter": 1}`；`{"year": 2026, "period": 7}`
同比	对每个细分值：该期间的数字（`current`）、一年前的同一期间（`prior`）、差值（`value`）和 `pct`。答案会指明上一期间。	带有 `period` 的 `compare: "yoy"`
季度环比	同上，与前一个季度比较。第一季度与上一年的第四季度比较。	`compare: "qoq"`；`period` 必须指明 `quarter`
期间环比	同上，与前一个期间比较。第一期与上一年的最后一期比较。在 12 期日历上，这就是月环比，名称由此而来。	`compare: "mom"`；`period` 必须指明 `period`
年初至今	从年初到所指明季度或期间末的这一段，单独呈现，或与 `yoy` 一起与上一年的相同月份比较。与 `qoq` 或 `mom` 一起使用会被拒绝。	`period` 中的 `"to_date": true`
累计	对所要求期间内的每个财年和期间各返回一行，包含该期间自身的数字（`value`）和迄今为止的累计（`cumulative`）。如果没有期间，则跨年份从第一行运行到最后一行。它不接受比较、占比或排名。	`cumulative: true`

pct 是差值占上一数字大小的百分比，当上一数字为负时保留差值的符号，与差异比较相同。两个期间各自单独汇总，然后按细分值匹配两个总计；不会从相邻行读取任何内容。因此，去年没有行的月份会比较为空，而不是比较为最近一个有行的月份；仅在两个期间之一有行的细分值，其另一侧、差值和 pct 显示为空而不是零。

累计适用于 sum 和 count 指标。平均值、去重计数、最小值或最大值无法随时间累加，会被拒绝。没有行的期间在累计中没有对应的行，累计总数会继续越过它向后延伸。

在指明期间、随时间比较或要求累计的问题中，不能按时间列筛选或分组：它们决定读取哪些行以及如何放置这些行。不做这些事的问题仍然可以像按任何细分列一样按它们筛选和分组。同样会被拒绝的还有：超出年末的期间（12 期日历上的第 13 期）、没有季度的日历上的季度、派生指标上的时间比较或累计，以及没有指明其比较所需期间类型的问题。当派生指标的每个输入在同一财年日历上都有时间列时，可以询问该派生指标的某一个期间，这时同样不能按这些列筛选或分组。随时间比较是问题的唯一一项比较，因此不能与对预算的差异比较组合，不过占比和排名仍然适用于差值。

停用指标

停用指标会使其永久停止使用：读取项目的人不再能看到它，架构师会看到它被标记为已停用并保留其历史，并且它不能再被编辑或运行。架构师通过请助手或使用 POST /rest/v1/analyze/metric/retire 来停用指标。被派生指标所基于的指标，在该派生指标被停用之前，或保存了不再使用此输入的版本之前，不能被停用。要替换已停用的指标，请定义一个新指标。

通过 MCP 和 REST API

操作	MCP 工具	REST
列出项目的指标及其完整定义；`q` 仅保留名称或某个同义词包含它的指标	`metric_find`	`GET /rest/v1/analyze/metric/definitions?project_id=&q=`
将问题中的词语解析为细分列的值	带有 `column` 和 `words` 的 `metric_values`	`GET /rest/v1/analyze/metric/values?project_id=&metric_id=&column=&words=`
读取一个指标		`GET /rest/v1/analyze/metric/definition?project_id=&metric_id=`
定义或编辑	`metric_upsert`	`POST` / `PUT /rest/v1/analyze/metric/definition`
停用	带有 `action: retire` 的 `metric_review`	`POST /rest/v1/analyze/metric/retire`
运行	带有 `group_by`、`filters` 以及可选的 `period`、`compare`、`share`、`top` 和 `cumulative` 的 `metric_run`	使用相同字段的 `POST /rest/v1/analyze/metric/run`
早期版本（仅限架构师）		`GET /rest/v1/analyze/metric/flashback-versions`

metric_upsert 接受 {name, memo, synonyms, definition} 形式的 spec，并接受 dry_run 以便在不保存的情况下检查定义。基础指标的 definition 是 {source, joins, measure, filters, grain, dimensions, scenario, time}，其中 dimensions 为 {<breakdown column>: <dimension id>}，measure 为 {agg, column} 或 {agg: "weighted_avg", column, weight}，scenario 为 {column, actual, budget}，time 为 {column, fiscal_year_start, fiscal_year_label} 或 {year_column, period_column, periods_per_year}。派生指标的 definition 是 {kind, op, inputs, factor}；其计算得出的细分列会作为 grain 与定义一起返回。