---
id: gh-platform-soql-query
name: "platform-soql-query"
url: https://skills.yangsir.net/skill/gh-platform-soql-query
author: forcedotcom
domain: data-analysis
tags: ["salesforce", "soql", "query-optimization", "database"]
install_count: 4500
rating: 4.40 (120 reviews)
github: https://github.com/forcedotcom/sf-skills/tree/main/skills/platform-soql-query
---

# platform-soql-query

> 此技能专门用于生成、优化和分析 Salesforce SOQL/SOSL 查询。它支持自然语言转查询、关系查询、聚合查询、查询计划分析以及性能优化，帮助开发者快速编写高效且安全的查询。

**Stats**: 4,500 installs · 4.4/5 (120 reviews)

## Before / After 对比

### SOQL 查询编写时间

**Before**:

在没有此技能之前，开发者需要手动编写 SOQL 查询，反复查阅语法文档并调整筛选条件，平均耗时 60 分钟。

**After**:

使用此技能后，开发者只需用自然语言描述需求，即可自动生成优化后的查询，平均耗时降至 10 分钟。

| Metric | Before | After | Change |
|---|---|---|---|
| 查询编写时间 | 60分钟 | 10分钟 | -83% |

## Readme

# platform-soql-query: Salesforce SOQL Query Expert

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.

## 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](../platform-data-manage/SKILL.md)
- embedding query logic inside broader Apex implementation → [platform-apex-generate](../platform-apex-generate/SKILL.md)
- debugging via logs rather than query shape → [platform-apex-logs-debug](../platform-apex-logs-debug/SKILL.md)

---

## 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

---

## Recommended Workflow

### 1. Generate the simplest correct query
Prefer:
- only needed fields
- clear WHERE criteria
- reasonable LIMIT when appropriate
- relationship depth only as deep as necessary

### 2. Choose the right query shape
| Need | Default pattern |
|---|---|
| parent data from child | child-to-parent traversal |
| child rows from parent | subquery |
| counts / rollups | aggregate query |
| records with / without related rows | semi-join / anti-join |
| text search across objects | SOSL |

### 3. Optimize for selectivity and safety
Check:
- indexed / selective filters
- no unnecessary fields
- no avoidable wildcard or scan-heavy patterns
- security enforcement expectations

### 4. Validate execution path if needed
If the user wants runtime verification, hand off execution to:
- [platform-data-manage](../platform-data-manage/SKILL.md)

---

## 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

---

## 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:

```text
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>
```

---

## Cross-Skill Integration

| Need | Delegate to | Reason |
|---|---|---|
| run the query against an org | [platform-data-manage](../platform-data-manage/SKILL.md) | execution and export |
| embed the query in services/selectors | [platform-apex-generate](../platform-apex-generate/SKILL.md) | implementation context |
| analyze slow-query symptoms from logs | [platform-apex-logs-debug](../platform-apex-logs-debug/SKILL.md) | runtime evidence |
| wire query-backed UI | [experience-lwc-generate](../experience-lwc-generate/SKILL.md) | frontend integration |

---

## Score Guide

| Score | Meaning |
|---|---|
| 90+ | production-optimized query |
| 80–89 | good query with minor improvements possible |
| 70–79 | functional but performance concerns remain |
| < 70 | needs revision before production use |

---

## Reference File Index

| File | When 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 |


---

# platform-soql-query

Salesforce SOQL query generation, optimization, and analysis skill with 100-point scoring. Convert natural language into performant SOQL and validate queries for security, selectivity, and governor-limit awareness.

## Features

- **Natural Language to SOQL**: Convert requests into executable queries
- **Query Optimization**: Improve selectivity, LIMIT usage, and field selection
- **Relationship Queries**: Parent-child, child-parent, and polymorphic patterns
- **Security Guidance**: `WITH USER_MODE`, `WITH SECURITY_ENFORCED`, and Apex-safe usage
- **100-Point Scoring**: Performance, correctness, security, and readability checks

## Quick Start

### 1. Invoke the skill

```yaml
Skill: platform-soql-query
Request: "Find Accounts with open Opportunities created this quarter"
```

### 2. Typical use cases

- Generate SOQL from plain-English requirements
- Optimize slow or non-selective queries
- Build aggregates and relationship queries
- Validate queries before using them in Apex or CLI workflows

## Documentation

- [SKILL.md](SKILL.md) - Core workflow and optimization guidance
- [references/query-optimization.md](references/query-optimization.md) - Selectivity and performance tuning
- [references/soql-syntax-reference.md](references/soql-syntax-reference.md) - Syntax, relationships, and aggregates
- [references/selector-patterns.md](references/selector-patterns.md) - Reusable Apex selector patterns
- [references/cli-commands.md](references/cli-commands.md) - sf CLI query execution examples

## Related Skills

- `platform-data-manage` - For data creation/import/export workflows
- `platform-apex-generate` - For inline SOQL inside Apex code
- `platform-apex-test-run` - For validating query behavior in tests


---
*Source: https://skills.yangsir.net/skill/gh-platform-soql-query*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-platform-soql-query/markdown*