agentscope-ai query-odps
MaxCompute 只读 SELECT 的域规则：怎么写对 SQL、怎么优化、怎么自检、怎么执行、失败如何回退。
禁止：直连 PyODPS；绕过标准执行通道自写 CSV。
规则索引
| 场景 | 读 |
|---|---|
| 写 SQL（方言） | references/dialect-rules.md |
| 分区 / MAX_PT | references/partition-semantics.md |
| SELECT 结构 | references/sql-correctness.md |
| 性能 / 扫描 | references/performance.md |
| 业务字面量 → 库内值 | references/value-discovery.md |
| 失败回退 | references/error-recovery.md |
核心原则
- 先取证 — 无元数据不臆测表名、列名、口径。
- 过滤值与 JOIN 键先定再写 SQL — 时间范围、分区边界、维度筛选、业务字面量对应的库内取值等 全部确认 后再生成 SQL；不得在 WHERE 里留臆测的枚举或占位过滤值。未映射的字面量确认参考
value-discovery.md。涉及 JOIN 时同理：写 ON 之前先对齐左右两边的连接键——列名是否同一实体、类型是否一致、格式是否同口径（如user_id是否都带前缀、ds是yyyyMMdd还是yyyy-MM-dd、STRING 是否需TRIM/CAST）；禁止在未核实键格式时直接拼 JOIN。 - 分步查询，勿一次开大 SQL — 执行结果会落入 ODPS 临时表（如
cm_tmp_*），应拆成可快速校验的小步：探针 / 单表过滤 / 中间结果落表 → 再基于临时表做下一步。禁止 一次性提交超大、多表深 JOIN、长窗口的「一步到位」SQL；一旦口径或 JOIN 键有误，会等非常久才失败，用户无法及时发现问题。 - 性能纪律 + 执行前自检 — 写 SQL 前 必须读
references/performance.md（分区必过滤、列裁剪、先聚合再 JOIN 等）；定稿后再对照performance.md、partition-semantics.md等 references 自检，明显违规 不得执行。ODPS 按扫描量计费，忽视此项会导致超时或严重资源浪费。 - 只走标准执行通道 — SELECT 仅经平台提供的执行通道提交；禁止 PyODPS 直连或自写 CSV。结果落盘路径由运行环境决定；
truncated须在回复中说明；禁止把超大结果全量贴进对话。