dingtalk-workspace-cli/skills/multi/dingtalk-aitable/references/06-data-analytics.md

数据分析

本场景所有 recipe 均为 full。

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