# 数据分析
> 本场景所有 recipe 均为 full。
| Recipe | 行动指南（固定路线） |
|--------|-------------------|
| read-aitable | 1. `aitable base search --query "<表格名>"` → 取 `baseId`/`tableId`
2. `aitable field get --base-id --table-id ` → 取 `fieldId`
3. **取记录（按场景分流）**：
• 数据统计/分析/全量汇总 → `aitable record query --base-id --table-id --all`（自动翻页，**禁止凭单页数据做统计**）
• 大表保险 → 加 `--page-limit 100`（默认 50 页/5000 条，0 = 无限制）
• 单纯预览前几条 → `aitable record query --base-id --table-id --limit 30`（不加 --all）
• 筛选时 `--filters` 格式见 [aitable-filter-sort.md](../products/aitable/aitable-filter-sort.md)
4. **检查输出契约**：`hasMore=true` 时数据被截断，必须用 `--cursor ` 续拉；`partial=true` 时表示中途某页失败（保留已拉数据，可重试）
5. 总结数据 |
| generate-data-report | 1. 同 read-aitable 步骤 1-3（**必须用 --all 防漏数据**）
2. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行 → 补充背景
3. `doc create --name "<报告名>" --content "<分析报告>"` |
| create-aitable-record | **写入路径分流**（关键决策）：
• **追加到已有表**（场景：把这批数据加到「成员表」）→ `python scripts/import_records.py data.csv\|data.json [batch_size]`（走 `record create`，需要列名匹配字段名）
• **新建表**（场景：把这个 Excel 变成多维表）→ `python scripts/aitable_import_via_task.py `（脚本内置 prepare→OSS PUT→import data 全流程和正确的头处理，**禁止自己写 PUT**）。注意 `aitable import upload` 没有 `--file` flag、也不代做 PUT，只准备导入；能一站式完成的是上面的脚本
• **单条/少量手动**：1. `aitable base search` → `baseId`/`tableId`；2. `aitable field get` → `fieldId` 与类型；3. `aitable record create --records '[{"cells":{"":"值"}}]'` |
| update-aitable-record | 1. `aitable base search --query "<表格名>"` → 取 `baseId`/`tableId`
2. **取目标 record**：
• 已知少量 recordId → `aitable record query --record-ids `
• 按条件批量改 → `aitable record query --base-id --table-id --filters '' --all`（**用 --all 防止漏改**）
3. **先展示让用户确认要改的 record 列表**
4. `aitable record update --base-id --table-id --records '[{"recordId":"","cells":{...}}]'`（单次 ≤30 条） |
| search-aitable-template | 1. `aitable template search --query "<关键词>"` → 取 `templateId`
2. 用户选定
3. `aitable base create --name "<表格名>" --template-id ` → 取 `baseId` |
| export-aitable-to-xlsx | 1. `aitable base search --query "<表格名>"` → 取 `baseId`
2. **按场景选 scope**：
• 全表+附件 → `aitable export data --base-id --scope all --export-format excel_and_attachment --output ./.xlsx`
• 单表（仅 xlsx）→ `--scope table --table-id --export-format excel`
• 单视图 → `--scope view --table-id --view-id `
3. CLI 内置渐进式退避轮询 + 自动落盘，**不要自己写 GET downloadUrl**
4. 大表超时（默认 5 分钟）：加 `--timeout-sec 900` 或拿到 `taskId` 后 `aitable export data --task-id --output ./.xlsx` 续等
5. 与悟空脚本路径并存：复杂场景（多 base 批量 / 按视图组合）请用 `python scripts/aitable_export_via_task.py --scope all\|table\|view` |
| primary-doc-from-record | 当 AI 表格用文档作主键字段时，从 record 跳到其主文档：
1. `aitable record query` 取 `recordId`
2. `aitable base get-primary-doc-id --base-id --table-id --record-id ` → 取主键文档 `dentryUuid`
3. 凭 `dentryUuid` 调 `doc read --node ` 拿文档内容 |