调用 CDF Data Modeling API…

编写或审查调用 CDF Data Modeling（DMS）实例接口的代码时，用信号量限流、分页、分批和正确的 search/filter 选择来保证运行时可靠性。

适用场景

解决思路

1. 所有 CDF API 调用都用全局 cdfTaskRunner.schedule() 包裹，限制并发请求以避免 429 和死锁；若项目没有信号量工具，创建 src/shared/utils/semaphore.ts，实现 QueuedTaskRunner（默认 maxConcurrentTasks=15）并导出全局 cdfTaskRunner。
2. 用 key 选项做去重：schedule(fn, { key }) 时若已有同 key 的待执行任务，先以 AbortError 拒绝并移除旧任务，适用于用户快速切换过滤条件等场景。
3. instances.list 分页：循环调用并传入上一次返回的 cursor，累积 items，直到 nextCursor 为空；可在达到足够数据量时提前 break。
4. instances.query 分页：nextCursor 是 Record<string, string>（每个 table expression 一个游标），通过 cursors 参数传回上一页游标并递归/循环获取后续页，再合并结果。
5. 分页抓取也要用 cdfTaskRunner.schedule() 包裹，避免占满并发预算。
6. 写操作分批：instances.upsert 每次最多 1000 项，用 chunk 工具切分后通过 cdfTaskRunner.schedule() 并发提交（配合 Promise.all 是安全的）。
7. 删除操作使用单独且更严格的 QueuedTaskRunner（例如 new QueuedTaskRunner(2)），因为 delete 的并发限制更严；同样按 1000 项分批。
8. in 过滤表达式最多 1000 个值：超过时用 chunk 切成每批 1000，分别通过 cdfTaskRunner.schedule() 发起请求，再 flatMap 合并结果。
9. 文本模糊匹配用 instances.search：operator 为 AND（默认，所有词都需匹配，用于精确查找）或 OR（任一词匹配，用于探索/自动补全）；可同时传 filter 做精确约束。
10. 精确、确定性匹配（equals、range、in、hasData 等）用 instances.list / instances.query 的 filter，不做模糊匹配。
11. 避免嵌套信号量调用以防死锁：把 cdfTaskRunner.schedule() 放在最外层调用，或让内层函数各自持有自己的 schedule 调用，外层不再包裹。
12. 不要对原始 API 调用直接使用 Promise.all；必须让每个调用先经过 cdfTaskRunner.schedule() 再并发。
13. 注意 instances.query 中每个 table expression 有各自的 limit，单次可能超出时必须用 cursors 分页。
14. 对查询结果做 LLM 调用有硬性上限：不要对 instances.list/query/search 的每条结果映射 chat completions，优先用一次 Atlas/EOS 侧边栏交互；若必须逐条调用，每次用户操作最多 5 次、上限 50 次，按 space:externalId:lastUpdatedTime 缓存，且仅由用户触发。
15. 参考官方文档 https://docs.cognite.com/cdf/dm/dm_reference/dm_limits_and_restrictions 获取最新并发、资源和属性值限制；注意 apply/delete/query 各有独立并发限制，transformations 会占用大量并发预算。

适用边界 · 注意事项

• 不适用于非 CDF Data Modeling 的 API 调用场景。
• 若项目无法使用 Cognite 官方 SDK / cdfTaskRunner 或不允许引入信号量工具，则本经验的核心做法不适用。
• 遍历负载正确性和图特有的失败特征不属于本经验，应参考 dm-graph-traversal。