分析路径

分析路径是为经常分析的表起的一个易记名称，例如 *“运营结果”*或 “损益表”。注册一次之后，您（以及已连接的 AI 助手）就可以按这个名称提问，而无需每次都重复说明是哪个项目、哪张表。

将其中一个设为工作区的默认路径后，像 “上个季度为什么增长了？” 这样的普通问题也能直接得到解答，因为助手已经知道“这”指的是什么。

为什么使用分析路径

没有分析路径时，每个问题都必须写明数据所在的位置，即项目和表，这样既烦琐又容易出错。有了分析路径，您就可以用自己思考数据的方式来谈论数据：

按名称提问。 “汇总运营结果。” 而不是 “汇总项目 Enterprise Profitability 中的表 ops_summary_v3。”
设置默认值。 将最常用的表标记为默认，之后连名称都可以省略，“与上个月相比有什么变化？” 会自动定位到正确的数据。
保持团队一致。 当整个团队都说 “损益表” 时，大家访问的是同一张表，不会猜错，也不会用到过期的副本。

注册分析路径

如果您是工作区管理员，无需表单或设置屏幕，只要用自然语言请已连接的 AI 助手为您注册即可：

“注册一个名为运营结果的分析路径，指向 Enterprise Profitability 项目中的 ops_summary 表。”

助手会确认该路径，随后即可立即使用。您可以注册任意数量的路径，每张经常分析的表对应一个。

设置默认路径

管理员可以将某个路径标记为默认，这样没有指明表的问题会自动使用它：

“将运营结果设为默认分析路径。”

此后，“本季度变化最大的是什么？” 或 “总额为什么下降了？” 这类问题无需再指定其他内容，就会针对该表运行。整个工作区只有一个默认路径，因此所有人未指明目标的问题都会指向同一张表。设置新的默认路径只是转移这一身份，始终只有一个默认路径，助手也会告诉您当前是哪一个。

让路径对 AI 助手更有用

名称和表只能告诉助手数据在哪里，却无法告诉它数据是什么意思：哪些筛选器始终适用、财年如何划分、团队用语具体指什么。缺少这些信息，助手只能猜测，而自信的错误答案比缓慢的答案更糟。本节介绍存放这些知识的两个位置，以及两者为何都很重要。

在本指南中，AI 助手指通过 PlaidCloud MCP 连接的任何 LLM（Claude、Microsoft Copilot、ChatGPT 等），以及 PlaidCloud 内置的 AI。

添加提示指引

每个分析路径都有提示指引：由您撰写的自由文本，告诉助手如何使用该路径。每行写一条指令。

要添加提示指引，请打开工具菜单并选择分析路径，然后选择一个路径并选择编辑（或选择新建来创建）。提示指引字段位于表之后、设为工作区默认值之前。具有管理分析路径权限的已连接助手也可以设置它。MCP 和 API 调用方会将此字段视为 description，例如：“将运营结果路径的 description 设置为……”

助手以两种方式使用提示指引：

选择路径。 当问题没有指明路径时，助手会将问题与每个路径的名称和提示指引进行比较，选出最匹配的一个。
作为长期指导。 选定路径后，助手会在针对该路径的每次查询中应用提示指引：要包含的筛选器、需要转换的术语。对于通过 MCP 连接的助手，业务数字本身来自项目的指标定义，而不是来自提示指引。

提示指引与路径一起存储，工作区中所有能看到分析路径的人都可以查看。它会传递给通过 MCP 工作的助手和 PlaidCloud 内置的 AI，但不会传递给工作流 LLM 步骤中的 AI 辅助功能。

写什么

写下新分析师第一天使用这张表时需要被告知的内容。每条指令单独一行。

写这些	示例
该路径能回答哪些问题，不能回答哪些问题。	“按业务单元统计的月度运营结果。适用于收入、成本和 EBITDA 问题。不适用于人员编制或预测，请使用预测路径。”
某个业务用语对应哪个指标，适用于通过 MCP 连接的助手。	“‘收入’指净收入指标。`billed_amount` 是开票金额，不是收入。”
始终适用的筛选器。	“除非询问预算，否则始终排除 `scenario = 'Budget'`。集团内部行的 `entity_type = 'IC'`，请将其排除在总额之外。”
符号约定、日历和粒度。	“成本以负数存储。财年从 7 月开始，因此 FY26 为 2025 年 7 月至 2026 年 6 月。每个业务单元每月一行。”
映射到数据的业务术语。	“‘中西部’指 `region IN ('IL','IN','OH','MI')`。‘核心产品’指 `product_tier = 'A'`。”

保持简短而具体。每行一条指令胜过一大段文字，上限为 1,000 个字符。首尾空格会被去除。

不要写什么

助手本来就能看到的内容。 列类型、键和行数会随表一起返回。重复这些内容会白白占用 1,000 个字符。
某一列的含义。 请将其写入列备注，这样无论该表用在哪里，备注都会跟随该列。提示指引用于说明如何整体使用该路径。
任何机密信息。 提示指引在整个工作区可见，而不仅限于有权访问该表所在项目的人。请勿包含密码或密钥、个人数据，以及您不愿向每位工作区成员展示的数字和评论。

好的与欠佳的提示指引

以下两个示例针对同一个路径，并提出同一个问题：“去年中西部的 EBITDA 是多少？”

	欠佳的指引	好的指引
文本	“运营数据。”	“按业务单元统计的月度运营结果。 EBITDA = `ebitda_adj`；忽略 `ebitda`。排除 `scenario = 'Budget'` 和集团内部行（`entity_type = 'IC'`）。财年从 7 月开始。中西部 = IL、IN、OH、MI。”
助手的做法	选用普通的 `ebitda` 列，包含预算行和集团内部行，并将“去年”理解为日历年。	使用 `ebitda_adj`，排除预算行和集团内部行，使用上一个完整财年，并筛选出中西部的四个州。
答案	一个看似合理、实际错误、且与财务团队不一致的数字。	财务团队所报告的数字。

欠佳的指引并没有错，只是把每一个决定都留给了助手去猜。

添加列备注

提示指引针对整个路径，而列备注解释单独一列，助手正是通过它了解一列实际存放的内容。当一列的用途无法从名称看出时，备注就是选对列与选中一个看似合理的错误列之间的区别。

路径所用表上的备注会随列清单一起返回给 AI 助手，即在 table_describe 配合 include=['columns'] 时，每个带备注的列都会有 memo。没有备注的列与之前一样返回。对于工作流 LLM 步骤所用的表，同样的备注也会传递给其中的 AI 辅助功能。

何时需要备注

需要添加备注的情形	备注示例
代码和缩写	`seg_cd`：“客户细分代码：E = 企业，M = 中型市场，S = 小型企业。”
相似的度量	`ebitda_adj`：“剔除一次性项目后的 EBITDA。报告时请使用此列；`ebitda` 为未调整值。”
标志	`is_ic`：“如果该行为集团内部交易，则为 1。在合并总额中排除。”
单位或货币	`amt_local`：“以实体本地货币计的金额，单位为千。”
派生或分摊的值	`alloc_cost`：“按人员编制分摊到此单元的共享成本。并非直接发生。”

名称本身已经说明一切的列，例如 invoice_date 或 customer_name，可以跳过。只是重复名称的备注没有任何价值。

如何添加备注

在表资源管理器中打开该路径所用的表。
在工具栏上，打开列属性。
在列清单中选择该列。
在备注中输入文本。

在表上设置的备注适用于该表被使用的任何地方，包括所有指向它的分析路径。

提示指引还是备注

每条信息只放在一个位置。

	提示指引	列备注
涵盖范围	如何整体使用该路径	某一列的含义
典型内容	能回答的问题、长期筛选器、财年日历、业务术语	代码、单位、标志、应使用哪个相似列
示例	“在总额中排除集团内部行。”	`is_ic`：“如果该行为集团内部交易，则为 1。”

在这里，备注说明 is_ic 的含义，提示指引则说明该如何处理它。

使用分析路径

注册好路径之后，直接提问即可：

按名称 — “显示运营结果的前几行。”
按默认路径 — “与上个季度相比有什么变化？”（未指明表，因此使用工作区默认路径）。
自由切换 — “现在对预测做同样的操作。” 助手会在各路径之间跟随切换。

这与分摊类问题天然契合，请参阅追溯分摊，这样您就可以从 “运营结果为什么发生变动？” 直接深入其背后的科目和动因。

通过 MCP 使用

当通过 MCP 连接的助手将分析路径传递给工具时，可以使用路径的名称（不区分大小写）或其 id。使用不存在的 id 更新路径会被拒绝；要创建新路径，请省略 id。

query_data_read 在 table、json_paths、dimension_value、column_values 和 aggregate 中接受 analysis_path，以取代项目和表。

仅预览部分列。 向 query_data_read(action='table') 传入 columns=[...]，即可只返回您指定的列。行访问规则仍然完全适用。不能与 version_id 同时使用。

一次调用获得筛选后的总计。 对度量请求 column_values，并按您关心的列进行筛选：

query_data_read(
  action='column_values',
  project_id=<project>,
  table_id=<table>,
  dimension_column_name=<filter column>,
  value_column_name=<measure>,
  filters={<filter column>: <value>}
)

它会返回该值对应的一行。如果列名拼写错误，错误信息会列出最多五个相近的匹配项，以便助手更正后重试。

一次调用完成汇总或分解。 使用 action='aggregate' 按一列或多列分组，并在服务器上对度量求和、求平均值或计数，而无需读取各行：

query_data_read(
  action='aggregate',
  project_id=<project>,
  table_id=<table>,
  group_by=['Product'],
  measures=[{'column': 'Revenue', 'agg': 'sum'}, {'column': 'Volume'}],
  filters={'Fiscal Year': 2027},
  order_by='Revenue',
  limit=10
)

measures 的 agg 可取 sum（默认）、avg、min、max 或 count；count 还接受 '*'。filters 的值可以是列表，用于匹配多个值中的任意一个。limit 默认为 50，最大为 500。order_by 指定一个度量或一个分组列；度量按从高到低排序。响应包含 rows、total_groups 和 truncated，当存在的分组多于 limit 所返回的数量时，该值为 true。行访问规则会在计算总计之前应用。

谁可以设置

设置分析路径（注册路径和选择默认路径）是管理员的操作，这样共享名称才能保持整洁并值得所有人信赖。路径创建后，工作区的每位成员都可以在提问时使用，且每个人仍然只能看到自己权限范围内的数据。