AI 表格数据分析 SOP

当用户诉求涉及查询、筛选、排序、统计、Top/Bottom N、分组聚合、判断全局结论时，必须先读本文档再执行。

1. 查询决策树

用户要做什么？
│
├─ 查看/导出原始记录明细
│   → record query [--filters] [--sort] [--field-ids] [--limit]
│
├─ 按条件筛选记录（如"状态=进行中的记录"）
│   → record query --filters '{"operator":"and","operands":[...]}'
│
├─ 取 Top N / Bottom N（如"销售额最高的5条"）
│   → record query --sort '[{"fieldId":"xxx","direction":"desc"}]' --limit 5
│
├─ 全量统计（如"一共多少条"、"所有记录的总销售额"）
│   → record stats --stats '[{"fieldId":"...","statsType":"COUNT|SUM|AVG|..."}]'
│
├─ 分组统计（如"每个状态各有多少条"）
│   → record group-stats --group '[...]' --stats '[{"fieldId":"...","statsType":"count"}]'
│
├─ 条件唯一实体数（如"有索赔单的门店共有多少家"）
│   → record group-stats --filters '{...}' --stats '[{"fieldId":"<实体字段>","statsType":"distinct"}]'
│
└─ 判断全局结论（如"是否所有记录都满足条件"）
    → record stats 对反向过滤结果 COUNT；只有需要行级证据时再 record query

2. 核心规则

2.1 禁止基于默认分页下全局结论

record query 默认返回 100 条。如果返回 JSON 中 data.nextCursor 非空，表示还有后续数据，当前结果不是全量。

{"data": {"nextCursor": "3hf5MtLbLZ", "records": [...]}}

❌ 错误：只查了默认 100 条就说"共 100 条记录"
✅ 正确：使用 --all 自动翻页拿全量，再统计

2.2 能在服务端过滤的，不要拉到本地再过滤

需求	正确做法	错误做法
筛选"状态=已完成"	`--filters '{"operator":"and","operands":[{"operator":"eq","operands":["fldXXX","已完成"]}]}'`	`--all` 拉全量再本地 filter
按日期降序取最新5条	`--sort '[...]' --limit 5`	`--all` 拉全量再本地 sort + slice
模糊搜索标题含"Q1"	`--filters` 用 `contain` 操作符	全量拉取再本地 grep

2.3 聚合必须优先在服务端完成

以下场景均有服务端聚合入口，不得先用 record query --all 下载全表计算：

record stats：不分组的 COUNT / SUM / AVG / MAX / MIN / MEDIAN / DISTINCT / 完整率等
record group-stats：分组统计，以及不带 group 的条件 DISTINCT 唯一计数
任意条件比率：分别聚合分子与分母，再对齐范围和 dataVersion 计算

只有用户要求记录明细、少量样本校验、精确分位数输入，或聚合接口明确返回不支持/错误时，才允许使用 record query。需要先逐行运算再聚合的指标（例如两个日期相减）必须使用表内已有且可聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能下载全表本地二次计算。

2.4 --all 使用注意

dws aitable record query \
  --base-id <baseId> \
  --table-id <tableId> \
  --all \
  --field-ids <只取需要的字段> \
  --format json

必须配合 --field-ids 限制返回字段，减少数据量
对于大表（>1000条），先告知用户可能耗时
--all 会自动处理分页，无需手动翻页

3. filters 快速参考

详细语法见 aitable-filter-sort.md。

常用操作符速查

操作符	适用类型	含义	示例 operands
`eq`	通用	等于	`["fldXXX", "值"]`
`ne`	通用	不等于	`["fldXXX", "值"]`
`gt` / `lt`	数值/日期	大于/小于	`["fldXXX", "25"]`
`gte` / `lte`	数值/日期	大于等于/小于等于	`["fldXXX", "100"]`
`contain`	文本	包含	`["fldXXX", "关键词"]`
`exist` / `un_exist`	通用	有值/为空	`["fldXXX"]`（无第二参数）
`any_of`	多选	包含任一	`["fldXXX", "选项A"]`

filters 结构模板

{
  "operator": "and",
  "operands": [
    {"operator": "eq", "operands": ["<fieldId>", "<值>"]},
    {"operator": "gt", "operands": ["<fieldId>", "<数值>"]}
  ]
}

4. 分析结果呈现规范

4.1 必须包含的信息

数据范围：基于哪个表、哪些筛选条件、查询了多少条记录
计算方法：用了什么聚合方式（sum/count/avg 等）
结果值：精确到合理小数位

4.2 示例

基于「销售数据」表，筛选条件：日期 ≥ 2026-01-01，共查询到 342 条记录。

总销售额：¥1,234,567.89（SUM）

平均单价：¥3,610.46（AVG）

最大单笔：¥89,000.00（MAX）

5. 任务选路心智模型

用户诉求	优先方案	不要误走
一次性标量统计	`record stats`	不要 `record query --all` 后本地聚合
分组/去重统计	`record group-stats`	不要下载全表 groupby / 去重
长期展示派生指标	创建 formula 字段（见 formula-guide）	不要每次手算再手动写入
按条件筛选记录	`record query --filters`	不要 `--all` 拉全量再本地 filter
取最新/最大/前N	`--sort + --limit`	不要 `--all` 再本地排序取前N
关键词检索	`record query --filters` 用 `contain`	不要把表格当搜索引擎全文检索
验证"是否全部满足"	反向 filters（筛不满足的），看是否有结果	不要 `--all` 逐条遍历

5.5 KiB Raw Blame History Unescape Escape