简介
本技能是自定义 SQL 的生成与执行入口，用于补足标准分析模型难以覆盖的复杂取数需求，如多表关联、跨库查询、明细提取等。
支持两种进入方式：用户已提供 SQL 时，直接进入只读校验与执行流程，不强制要求业务元数据确认；用户用自然语言描述取数需求时，须先确认所涉事件名、字段名、表名及枚举值的精确元数据，元数据不足则回退至 sensors-metadata，不允许猜测映射。
安全约束方面，仅允许查询语句（SELECT 或 WITH ... SELECT），禁止任何建表、改表、增删改等写操作。执行前须先在服务端预演校验，通过后方可正式执行。自动生成的 SQL 须采用"库名.表名"全限定格式，库名通过元数据命令运行时查得而非硬编码；用户自带的 SQL 可原样执行，不因缺库名限定而拦截。SQL 中包含 $ 事件名或属性名时，CLI 层会做转义处理。
使用场景
本技能适用于以下任务：
- 用户已提供 SQL，需要校验是否为只读并执行返回结果；
- 标准分析模型无法覆盖的复杂联表查询、跨库取数；
- 单用户行为明细的时间线提取；
- 跨项目数据对比或合并查询。
执行流程遵循以下路径：首先判断输入是用户自带 SQL 还是自然语言生成。用户自带 SQL 时，直接进行只读校验并执行；自然语言生成时，逐一核对元数据完整性——只要有一项无法精确映射即判定为元数据不足，停止后续步骤并回退至 sensors-metadata。元数据充足时生成 SQL，经服务端预演校验通过后正式执行。
使用案例
| 用户输入 | 系统执行 |
|---|---|
| "帮我查最近 7 天每个渠道的订单量和金额" | 先确认事件名、字段名、枚举值 → 生成全限定表名的只读 SQL → 预演校验 → 执行 → 返回结果；元数据不足时回退至 sensors-metadata 并说明原因。 |
| "帮我执行select * from xxx" | 直接做只读校验 → 预演校验 → 原样执行 → 返回结果；不强制补全库名限定。 |
| "对比正式项目和测试项目的活跃用户数" | 分别解析两个项目的默认库名 → 生成跨库联表形式的单条 SQL → 预演校验 → 执行。 |
| "查某个用户的所有行为明细" | 确认事件表与字段 → 生成按用户 ID 过滤的明细查询 → 执行返回时间线。 |
常见问题
Q：能执行写操作吗（建表、改数据等）？
不能。仅允许查询语句，禁止任何建表、改表、增删改操作。
Q：自然语言生成 SQL 时元数据不完整怎么办？
立即停止，回退至 sensors-metadata 补充元数据。不允许在元数据不足时猜测字段映射，也不允许先执行再补充。
Q：用户自带的 SQL 缺少库名限定会被拒绝吗？
不会。用户自带的 SQL 原样执行，不因缺少"库名.表名"格式而拦截。自动生成的 SQL 则必须写全限定表名。
Q：跨项目查询怎么处理？
跨项目与跨库是同一机制。分别解析各项目的默认库名后，在单条 SQL 内以"库名.表名"形式联表查询即可。仅当引擎明确报库不存在或权限隔离时，才回退为逐库查询后合并。
Q：执行前必须先预演校验吗？
是的。所有 SQL 经预演校验通过后方可正式执行，预演用于确认字段、表名、过滤条件等是否符合预期。
Q：$ 符号在 SQL 中怎么处理？
SQL 中包含 $ 事件名或属性名时，CLI 命令层会自动做转义处理，调用方无需额外操作。