Back to Details

platform-soql-query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

platform-soql-query: Salesforce SOQL Query Expert

platform-soql-query: 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 
platform-soql-query
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 → platform-data-manage
  • embedding query logic inside broader Apex implementation → platform-apex-generate
  • debugging via logs rather than query shape → platform-apex-logs-debug
使用
platform-soql-query
当工作涉及以下内容时：
  • .soql
    文件
  • 从自然语言生成查询
  • 关联查询与聚合查询
  • 查询优化与选择性分析
  • SOQL/SOSL语法及符合Governor限制的设计
当用户进行以下操作时，请转交至其他技能：
  • 执行批量数据操作 → platform-data-manage
  • 在更广泛的Apex实现中嵌入查询逻辑 → platform-apex-generate
  • 通过日志而非查询结构进行调试 → platform-apex-logs-debug

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:
  • platform-data-manage
如果用户需要运行时验证，将执行任务转交至：
  • platform-data-manage

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 platform-data-manage or embed in Apex>
完成任务后，按以下顺序输出：
  1. 查询用途
  2. 最终SOQL/SOSL
  3. 选择该结构的原因
  4. 优化或安全说明
  5. 必要时的执行建议
建议格式——如需精确语法，请参考
references/soql-syntax-reference.md
：
Query goal: <摘要>
Query: <soql或sosl>
Design: <关联/聚合/筛选选择说明>
Notes: <选择性、限制、安全、Governor限制相关说明>
Next step: <在platform-data-manage中运行或嵌入到Apex>

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
run the query against an orgplatform-data-manageexecution and export
embed the query in services/selectorsplatform-apex-generateimplementation context
analyze slow-query symptoms from logsplatform-apex-logs-debugruntime evidence
wire query-backed UIexperience-lwc-generatefrontend integration
需求转交至原因
在组织中运行查询platform-data-manage执行与导出
在服务/选择器中嵌入查询platform-apex-generate实现上下文
从日志分析慢查询症状platform-apex-logs-debug运行时证据
构建基于查询的UIexperience-lwc-generate前端集成

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验证和实时查询计划分析