SOQL — 18 Operations for AI Agents
SOQL queries run the Salesforce data layer — objects, relationships, the lookups behind every workflow. act101 reads query structure natively, so agents reason about relationship traversals instead of pattern-matching strings.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze SOQL code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
Worked SOQL examples
act101 reads a SOQL query's FROM clause as its declarations: the object named directly after FROM, and the object named in each parenthesized relationship subquery, both surface as a declaration named for the Salesforce object or relationship. The skeleton's subquery rule overlaps its top-level rule rather than replacing it, so every relationship subquery — (SELECT ... FROM Encounters__r) — is reported twice, once at the range of the subquery and once at the range of its inner query body. symbols avoids that duplication, reporting one entry per FROM object, but reports every entry's kind as unknown rather than naming the object a Salesforce sObject, since neither rule states a kind for its bare @definition capture. The unit of structure in this grammar is the query body: act101 does not read the selected fields, aliases, or WHERE-clause conditions in either query. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read a bed query's relationship subqueries as a skeleton
occupied-beds.soql selects from Bed__c and pulls two relationship subqueries — Encounters__r for admission history and CareTeamMembers__r for the assigned care team.
$ act query skeleton occupied-beds.soqlBefore
SELECT Id, BedNumber__c, Ward__c, Status__c,
(SELECT Id, AdmissionDateTime__c, DischargeDateTime__c FROM Encounters__r),
(SELECT Id, MemberName__c FROM CareTeamMembers__r)
FROM Bed__c
WHERE Status__c = 'Occupied'Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "function",
"name": "Encounters__r",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 2,
"column": 8,
"byte_offset": 52
},
"end": {
"file": "occupied-beds.soql",
"line": 2,
"column": 82,
"byte_offset": 126
}
},
"name_range": {
"start": {
"file": "occupied-beds.soql",
"line": 2,
"column": 68,
"byte_offset": 112
},
"end": {
"file": "occupied-beds.soql",
"line": 2,
"column": 81,
"byte_offset": 125
}
}
},
{
"kind": "function",
"name": "Encounters__r",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 2,
"column": 9,
"byte_offset": 53
},
"end": {
"file": "occupied-beds.soql",
"line": 2,
"column": 81,
"byte_offset": 125
}
},
"name_range": {
"start": {
"file": "occupied-beds.soql",
"line": 2,
"column": 68,
"byte_offset": 112
},
"end": {
"file": "occupied-beds.soql",
"line": 2,
"column": 81,
"byte_offset": 125
}
}
},
{
"kind": "function",
"name": "CareTeamMembers__r",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 3,
"column": 8,
"byte_offset": 135
},
"end": {
"file": "occupied-beds.soql",
"line": 3,
"column": 58,
"byte_offset": 185
}
},
"name_range": {
"start": {
"file": "occupied-beds.soql",
"line": 3,
"column": 39,
"byte_offset": 166
},
"end": {
"file": "occupied-beds.soql",
"line": 3,
"column": 57,
"byte_offset": 184
}
}
},
{
"kind": "function",
"name": "CareTeamMembers__r",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 3,
"column": 9,
"byte_offset": 136
},
"end": {
"file": "occupied-beds.soql",
"line": 3,
"column": 57,
"byte_offset": 184
}
},
"name_range": {
"start": {
"file": "occupied-beds.soql",
"line": 3,
"column": 39,
"byte_offset": 166
},
"end": {
"file": "occupied-beds.soql",
"line": 3,
"column": 57,
"byte_offset": 184
}
}
},
{
"kind": "function",
"name": "Bed__c",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "occupied-beds.soql",
"line": 5,
"column": 29,
"byte_offset": 226
}
},
"name_range": {
"start": {
"file": "occupied-beds.soql",
"line": 4,
"column": 6,
"byte_offset": 191
},
"end": {
"file": "occupied-beds.soql",
"line": 4,
"column": 12,
"byte_offset": 197
}
}
}
]
}The skeleton reports five declarations for three FROM objects: Bed__c once, but Encounters__r and CareTeamMembers__r each twice, at two overlapping ranges, because the subquery-specific rule matches the same query body the general rule already matched.
List the same three query objects as symbols
The file has exactly three FROM objects and no others: the main query and its two subqueries.
$ act query symbols occupied-beds.soqlBefore
SELECT Id, BedNumber__c, Ward__c, Status__c,
(SELECT Id, AdmissionDateTime__c, DischargeDateTime__c FROM Encounters__r),
(SELECT Id, MemberName__c FROM CareTeamMembers__r)
FROM Bed__c
WHERE Status__c = 'Occupied'Output
{
"type": "Symbols",
"symbols": [
{
"name": "Encounters__r",
"kind": "unknown",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 2,
"column": 68,
"byte_offset": 112
},
"end": {
"file": "occupied-beds.soql",
"line": 2,
"column": 81,
"byte_offset": 125
}
},
"visibility": "unknown"
},
{
"name": "CareTeamMembers__r",
"kind": "unknown",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 3,
"column": 39,
"byte_offset": 166
},
"end": {
"file": "occupied-beds.soql",
"line": 3,
"column": 57,
"byte_offset": 184
}
},
"visibility": "unknown"
},
{
"name": "Bed__c",
"kind": "unknown",
"range": {
"start": {
"file": "occupied-beds.soql",
"line": 4,
"column": 6,
"byte_offset": 191
},
"end": {
"file": "occupied-beds.soql",
"line": 4,
"column": 12,
"byte_offset": 197
}
},
"visibility": "unknown"
}
]
}symbols reports exactly Encounters__r, CareTeamMembers__r, and Bed__c once each, with no duplication — but all three come back kind: unknown, since the query's bare @definition capture carries no stated kind.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch