Back to Details

querying-soql

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

querying-soql: Salesforce SOQL Query Expert

querying-soql: Salesforce SOQL 查询专家

Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance/safety improvements for Salesforce queries.
当用户需要SOQL/SOSL编写或优化时使用此技能：包括自然语言转查询生成、关联查询、聚合查询、查询计划分析，以及Salesforce查询的性能/安全性提升。

When This Skill Owns the Task

此技能负责的任务场景

Use 
querying-soql
when the work involves:
  • .soql
    files
  • query generation from natural language
  • relationship queries and aggregate queries
  • query optimization and selectivity analysis
  • SOQL/SOSL syntax and governor-aware design
Delegate elsewhere when the user is:
  • performing bulk data operations → handling-sf-data
  • embedding query logic inside broader Apex implementation → generating-apex
  • debugging via logs rather than query shape → debugging-apex-logs
当工作涉及以下内容时，使用
querying-soql
：
  • .soql
    文件
  • 从自然语言生成查询
  • 关联查询和聚合查询
  • 查询优化和选择性分析
  • SOQL/SOSL语法和考虑governor限制的设计
当用户进行以下操作时，请转交至其他技能：
  • 执行批量数据操作 → handling-sf-data
  • 将查询逻辑嵌入更广泛的Apex实现中 → generating-apex
  • 通过日志而非查询结构进行调试 → debugging-apex-logs

Required Context to Gather First

首先需要收集的必要信息

Ask for or infer:
  • target object(s)
  • fields needed
  • filter criteria
  • sort / limit requirements
  • whether the query is for display, automation, reporting-like analysis, or Apex usage
  • whether performance / selectivity is already a concern
询问或推断：
  • 目标对象
  • 需要的字段
  • 过滤条件
  • 排序/限制要求
  • 该查询用于展示、自动化、类报表分析还是Apex调用
  • 是否已经存在性能/选择性方面的问题

Recommended Workflow

推荐工作流程

1. Generate the simplest correct query

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

Prefer:
  • only needed fields
  • clear WHERE criteria
  • reasonable LIMIT when appropriate
  • relationship depth only as deep as necessary
优先选择：
  • 仅查询所需字段
  • 清晰的WHERE条件
  • 必要时设置合理的LIMIT
  • 关联深度仅满足需求即可

2. Choose the right query shape

2. 选择合适的查询结构

NeedDefault pattern
parent data from childchild-to-parent traversal
child rows from parentsubquery
counts / rollupsaggregate query
records with / without related rowssemi-join / anti-join
text search across objectsSOSL
需求默认模式
从子对象获取父对象数据子对象到父对象遍历
从父对象获取子对象行数据子查询
计数/汇总聚合查询
存在/不存在关联行的记录半连接/反连接
跨对象文本搜索SOSL

3. Optimize for selectivity and safety

3. 针对选择性和安全性进行优化

Check:
  • indexed / selective filters
  • no unnecessary fields
  • no avoidable wildcard or scan-heavy patterns
  • security enforcement expectations
检查：
  • 索引化/选择性过滤条件
  • 无不必要的字段
  • 无可避免的通配符或扫描密集型模式
  • 安全执行预期

4. Validate execution path if needed

4. 必要时验证执行路径

If the user wants runtime verification, hand off execution to:
  • handling-sf-data
如果用户需要运行时验证，请将执行任务转交至：
  • handling-sf-data

High-Signal Rules

高优先级规则

  • never use 
    SELECT *
    style thinking; query only required fields
  • do not query inside loops in Apex contexts
  • prefer filtering in SOQL rather than post-filtering in Apex
  • use aggregates for counts and grouped summaries instead of loading unnecessary records
  • evaluate wildcard usage carefully; leading wildcards often defeat indexes
  • account for security mode / field access requirements when queries move into Apex
  • 绝对不要使用
    SELECT *
    的思路；仅查询所需字段
  • 在Apex上下文的循环内不要执行查询
  • 优先在SOQL中进行过滤，而非在Apex中进行事后过滤
  • 使用聚合查询进行计数和分组汇总，而非加载不必要的记录
  • 谨慎评估通配符的使用；前导通配符通常会失效索引
  • 当查询用于Apex时，需考虑安全模式/字段访问要求

Output Format

输出格式

When finishing, report in this order:
  1. Query purpose
  2. Final SOQL/SOSL
  3. Why this shape was chosen
  4. Optimization or security notes
  5. Execution suggestion if needed
Suggested shape — use 
references/soql-syntax-reference.md
for exact syntax:
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>
完成任务后，按以下顺序输出：
  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>

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
run the query against an orghandling-sf-dataexecution and export
embed the query in services/selectorsgenerating-apeximplementation context
analyze slow-query symptoms from logsdebugging-apex-logsruntime evidence
wire query-backed UIgenerating-lwc-componentsfrontend integration
需求转交至原因
在组织中运行查询handling-sf-data执行与导出
将查询嵌入服务/选择器中generating-apex实现上下文
从日志分析慢查询症状debugging-apex-logs运行时证据
连接查询驱动的UIgenerating-lwc-components前端集成

Score Guide

评分指南

ScoreMeaning
90+production-optimized query
80–89good query with minor improvements possible
70–79functional but performance concerns remain
< 70needs revision before production use
分数含义
90+生产级优化查询
80–89良好查询，可进行小幅改进
70–79功能可用，但仍存在性能问题
< 70投入生产前需要修改

Reference File Index

参考文件索引

FileWhen to read
references/soql-syntax-reference.md
Syntax, operators, date literals, relationship query patterns
references/query-optimization.md
Selectivity rules, indexing strategy, governor limits, security patterns
references/soql-reference.md
Quick reference — operators, date functions, aggregate functions, WITH clauses
references/anti-patterns.md
Common SOQL mistakes and their fixes — read before finalizing any query
references/selector-patterns.md
Apex selector layer patterns — read when embedding queries in Apex classes
references/field-coverage-rules.md
Field coverage validation — read when generating SOQL used inside Apex code
references/cli-commands.md
sf CLI query execution, bulk export, query plan commands
assets/basic-queries.soql
Starter query examples for common objects
assets/relationship-queries.soql
Parent-to-child and child-to-parent relationship query patterns
assets/aggregate-queries.soql
COUNT, SUM, GROUP BY, ROLLUP query patterns
assets/optimization-patterns.soql
Selective filter and index-aware query patterns
assets/bulkified-query-pattern.cls
Apex Map-based bulk query pattern for trigger contexts
assets/selector-class.cls
Full selector class implementation template
scripts/post-tool-validate.py
Post-write hook — runs static SOQL validation and live query plan analysis after 
.soql
file edits
文件阅读场景
references/soql-syntax-reference.md
语法、运算符、日期字面量、关联查询模式
references/query-optimization.md
选择性规则、索引策略、governor限制、安全模式
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验证和实时查询计划分析