soql-analyzer

You are analyzing SOQL queries for selectivity. A selective query uses an indexed field with a value that returns a small fraction of total rows; non-selective queries scan large tables and trigger query timeouts on LDV (Large Data Volume) objects. This skill flags candidate problems before they become production incidents.

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
APEX_SRC="$(sf_config_get '.paths.apexSource' "$ENV")"
ORG="$(sf_config_get '.platform.defaultTargetOrg' "$ENV")"
CACHE="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugin-data}/argo/org-cache/${ORG}.json"

Indexed Fields (Salesforce-managed by default)

These fields are always indexed unless the query disables the index:

• Id
• Foreign-key (lookup / master-detail) fields
• Name on most standard objects
• RecordTypeId
• OwnerId
• CreatedDate, LastModifiedDate, SystemModstamp
• External Id and Unique custom fields
• Custom fields explicitly indexed (custom indexes — visible only via the org cache, not source)

Non-indexed by default:

• Other custom fields (Status__c, Region__c, etc.)
• Description, Body, long text areas

Selectivity Rules

Input

$ARGUMENTS:

• (empty) — analyze all .cls and .trigger files
• <ClassName> — analyze a single class
• --ldv-threshold <rows> — flag any object with > N rows in the org cache as LDV (default 1000000)
• --target-org <alias> / --env <name> — for live cardinality / index lookup
• --ci / --format json|sarif / --out <path>

Steps

1. Walk the Apex source

For each file, find SOQL statements:

\[\s*SELECT\s+(.+?)\s+FROM\s+(\w+)(?:\s+(?:USING\s+SCOPE\s+\w+)?\s*WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?(?:\s+LIMIT\s+(\d+))?\s*\]

Multi-line / dynamic SOQL via Database.query: capture the string literal portion; if dynamic, flag for manual review.

2. Parse each WHERE clause

For each predicate:

• Identify the field
• Identify the operator
• Identify the right-hand value (literal, bind variable, dynamic)

3. Classify the query

For the FROM object:

• Look up in the org cache: actual indexed fields (custom-indexed flag), row count if available
• Map predicates against the indexed/non-indexed table above

Findings:

4. Output

Default Markdown:

# SOQL Analysis: <project.name>

Apex files scanned: 47 | Queries found: 124
LDV threshold: 1,000,000 rows
Org cache: <CLAUDE_PLUGIN_DATA>/.../DevVM.json (cachedAt: 2026-04-28T12:30:00Z)

## Findings

### Critical (3)
- `force-app/.../OrderReportController.cls:42` — `[SELECT ... FROM Order__c]` (no WHERE) — Order__c has 2.4M rows
- ...

### High (5)
- `force-app/.../SearchService.cls:18` — `[SELECT Id FROM Account WHERE Description LIKE '%...']` — leading wildcard, full scan
- `force-app/.../UnusedJob.cls:55` — `[SELECT ... FROM Lead]` (no LIMIT) on LDV
- ...

### Medium (8)
- `force-app/.../StatusBatch.cls:30` — `[SELECT ... FROM Order__c WHERE Status__c = :s]` — Status__c not indexed; consider custom index or external archive

### Notes (2)
- `force-app/.../DynamicReportController.cls:88` — Dynamic SOQL (Database.query) — manual review needed

CI mode: SARIF emit per finding.

5. Exit codes

• 0 — no error/warning findings
• 1 — any finding
• 2 — config error / no Apex source

Rules

• Heuristic, not perfect. Apex parsing without an AST is approximate. Mark dynamic SOQL as a note and let the human inspect
• Honor the org cache. If ${CACHE} lists a custom index on Status__c, don't flag WHERE Status__c = as non-selective. Run /argo:org-explore --refresh to update
• Don't flag tests. *<testSuffix>.cls is excluded by default
• Cross-link to fixes. Each finding's message should mention the appropriate fix: "add a custom index" / "filter by Id or lookup field" / "consider archiving" / "convert to a paginated report"

Consumers

• /argo:code-review consumes the JSON output and rolls up into the review report
• @architect and @data-architect reference the report when designing new query paths