querying-soql

querying-soql：Salesforce SOQL 查询专家

当用户需要编写或优化 SOQL/SOSL时，使用此技能：将自然语言转换为查询、编写关系查询、聚合查询、分析查询计划，以及改进 Salesforce 查询的性能和安全性。

此技能负责的任务

遇到以下工作时，使用 querying-soql：

• .soql 文件
• 根据自然语言生成查询
• 关系查询和聚合查询
• 查询优化和选择性分析
• SOQL/SOSL 语法和考虑治理限制的设计

以下情况应转交给其他技能：

• 执行批量数据操作 → handling-sf-data
• 在更广泛的 Apex 实现中嵌入查询逻辑 → generating-apex
• 通过日志而非查询结构进行调试 → debugging-apex-logs

---

首先收集必要的上下文

询问或推断：

• 目标对象
• 所需字段
• 筛选条件
• 排序 / 限制要求
• 查询用于显示、自动化、类似报表的分析，还是 Apex
• 是否已存在性能 / 选择性方面的顾虑

---

推荐工作流

1. 生成最简单且正确的查询

优先考虑：

• 只查询所需字段
• 使用清晰的 WHERE 条件
• 适当时设置合理的 LIMIT
• 关系查询深度仅达到必要程度

2. 选择合适的查询结构

需求	默认模式
从子对象获取父对象数据	子对象到父对象的关系遍历
从父对象获取子记录	子查询
计数 / 汇总	聚合查询
查询存在 / 不存在关联记录的记录	半连接 / 反连接
跨对象文本搜索	SOSL

3. 优化选择性和安全性

检查：

• 筛选条件是否已建立索引 / 具有选择性
• 是否包含不必要的字段
• 是否存在可避免的通配符或大量扫描的模式
• 是否符合安全性执行要求

4. 必要时验证执行路径

如果用户需要运行时验证，请将执行工作转交给：

• handling-sf-data

---

高优先级规则

• 切勿采用 SELECT * 的思路；只查询所需字段
• 在 Apex 上下文中，切勿在循环内执行查询
• 优先在 SOQL 中筛选，而不是在 Apex 中进行后续筛选
• 对计数和分组汇总使用聚合查询，避免加载不必要的记录
• 谨慎评估通配符的使用；前置通配符通常会导致索引失效
• 查询移入 Apex 后，应考虑安全模式 / 字段访问要求

---

输出格式

完成时，按以下顺序报告：

1. 查询目的
2. 最终 SOQL/SOSL
3. 选择此查询结构的原因
4. 优化或安全性说明
5. 必要时提供执行建议

建议的结构——使用 references/soql-syntax-reference.md 查阅准确语法：

Query goal: <summary>
Query: <soql or sosl>
Design: <relationship / aggregate / filter choices>
Notes: <selectivity, limits, security, governor awareness>
Next step: <run in handling-sf-data or embed in Apex>

---

跨技能协作

需求	转交给	原因
针对某个组织运行查询	handling-sf-data	执行和导出
在服务 / 选择器中嵌入查询	generating-apex	实现上下文
根据日志分析慢查询症状	debugging-apex-logs	运行时证据
接入由查询提供数据的 UI	generating-lwc-components	前端集成

---

评分指南

分数	含义
90+	针对生产环境优化的查询
80–89	查询良好，仍有少量改进空间
70–79	功能正常，但仍存在性能方面的顾虑
< 70	投入生产使用前需要修改

---

参考文件索引

文件	何时阅读
references/soql-syntax-reference.md	语法、运算符、日期字面量、关系查询模式
references/query-optimization.md	选择性规则、索引策略、治理限制、安全模式
references/soql-reference.md	快速参考——运算符、日期函数、聚合函数、WITH 子句
references/anti-patterns.md	常见 SOQL 错误及其修正方法——定稿任何查询前请阅读
references/selector-patterns.md	Apex 选择器层模式——在 Apex 类中嵌入查询时请阅读
references/field-coverage-rules.md	字段覆盖率验证——生成 Apex 代码中使用的 SOQL 时请阅读
references/cli-commands.md	sf CLI 查询执行、批量导出、查询计划命令
assets/basic-queries.soql	常见对象的入门查询示例
assets/relationship-queries.soql	父到子和子到父关系查询模式
assets/aggregate-queries.soql	COUNT、SUM、GROUP BY、ROLLUP 查询模式
assets/optimization-patterns.soql	选择性筛选和索引感知查询模式
assets/bulkified-query-pattern.cls	适用于触发器上下文的基于 Apex Map 的批量查询模式
assets/selector-class.cls	完整的选择器类实现模板
scripts/post-tool-validate.py	写入后钩子——在编辑 .soql 文件后运行静态 SOQL 验证和实时查询计划分析