agentleFS
omoji-personalomoji-personal/torque/.agents/skills/salesforce-soql-review/SKILL.md

salesforce-soql-review

Skill0 starsChanged 3 days agoMITView on GitHub

Draft, run, explain, optimize or review Salesforce SOQL and the sf data query commands that carry it. Use it before the first query on an object or setup entity you have not described in this session, when a query fails with an unknown field, an unsupported object or a restriction message, when deciding between the standard and the Tooling API, and when a result will be quoted to a client. Covers describe before you query, never guessing a name twice, entities that refuse OR, grouping, counting or filtering, reading the whole error, selectivity on large objects, and query and command-line traps with a check each.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Confirm the object exists: before you name it from memory: sf sobject list --target-org ALIAS.

    line 25
  2. Distinctive:

    When a query fails with "sObject type X is not supported", try the other API once and note which one answered.

    line 49
  3. Distinctive:

    Read the full message with its row, column and caret line.

    line 71
  4. Very specific:

    Write --json results to a file and read the file.

    line 74
  5. Distinctive:

    If you wrap queries in a redacting layer, keep the error code, the row and column and the schema part of the message (object, field, …

    line 77
  6. Distinctive:

    Keep record values out of notes and shared documents.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Salesforce SOQL review

Describe before you query, and look a name up instead of guessing it twice. State described: Winter '27 (API 68.0), checked 2026-11-14.

Marks: verify = not confirmed in a fetched primary source: verify in the org or the current documentation. field-reported = from real client work: a classification of 273 failed Salesforce CLI calls, 150 of them queries (one consultant, mostly sandboxes). [ADV] = Torque advisory catalogue, with its own confidence label per entry.

Before the first query on an object

  1. Name the org: --target-org ALIAS on every command. Do not switch to another org because it is already signed in.
  2. Look the names up. sf sobject describe --sobject Object__c --target-org ALIAS --json gives each field's name, type, filterable, groupable, nillable, and the relationshipName of lookups and child relationships. A relationship name is not the lookup's label. Do this for setup and metadata entities too: their fields are not the ones a custom object would have.
  3. Confirm the object exists before you name it from memory: sf sobject list --target-org ALIAS. An object from another product generation is absent (Nonprofit Cloud objects in an NPSP org, and the reverse); a managed field's prefix is not always its object's.
  4. Choose the API per query, not per session (table below).
  5. Ask for the least that answers the question: the fields you need, a count or a GROUP BY where a number is the answer, a LIMIT where rows are.

field-reported: 52 queries failed on an unknown field or relationship name; after such a failure the agent guessed again 37 times out of 51 and looked the name up 8 times. Only 2 of 314 first queries on setup entities were preceded by a check. After "No such column" or "Didn't understand relationship", describe. Do not guess again.

Standard API or Tooling API

EntityAPIEvidence
FlowDefinitionView, SetupAuditTrail, FieldPermissions, ObjectPermissions, PermissionSet, PermissionSetAssignmentStandard: the Tooling flag fails[ADV flowdefinitionview-is-standard-api, tooling-api-refuses-permission-objects]; field-reported
PermissionSetGroup, PermissionSetGroupComponent, CronTrigger, AsyncApexJob, DuplicateRuleStandard (verify in the Object Reference)The skills' own checks query them this way
ApexCodeCoverageAggregateTooling (verify)
FlowDefinition, ValidationRule and WorkflowRule metadata, ApexTrigger, CustomField, layouts, installed package versionsTooling: add --use-tooling-api[ADV]; field-reported
FieldDefinition, EntityDefinitionAnswered on both in the field record (the catalogue says Tooling only): try the standard API firstfield-reported, 48 queries
Any custom objectStandard. Never the Tooling flagfield-reported, 8 failures

When a query fails with "sObject type X is not supported", try the other API once and note which one answered.

Restrictions that look like syntax errors

You are about toIt fails withDo insteadEvidence
Put OR in a WHERE on FieldDefinition, FlowDefinitionView or a custom metadata type"Disjunctions not supported"IN on one field, one query per branch, or filter the rows yourselffield-reported, 13
GROUP BY a formula, percent, label or raw date and time field"field X can not be grouped"Check groupable in describe; group by a date function, or count the rows yourselffield-reported, 13
COUNT(Id) with GROUP BY on some setup and custom metadata entities"does not support aggregate operator COUNT"COUNT() without grouping, or count client-sidefield-reported, 6
Filter on a long text area or some setup fields"field X can not be filtered"Check filterable; filter on another field, then in codefield-reported, 7; [ADV history-fields-unfilterable]
Filter permission rows with LIKE on Field"invalid operator on id field"= or IN with the full Object.Field, plus SobjectTypefield-reported, 4
Write a semi-join or anti-join (WHERE Field IN (SELECT ...)) on the outer query's own object, or with a left side that is not an Id or reference fieldMALFORMED_QUERYFetch the Ids first and bind them, or walk level by level. A parent-to-child relationship sub-query (SELECT Id, (SELECT Id FROM Contacts) FROM Account) is a different thing[ADV self-join-forbidden]; field-reported, 3
Query some setup entities without their key filter"Implementation restriction"Add the Id = '...' or key filter the message asks forfield-reported, 3
Alias an aggregate first or last, or use a string function in SELECTMALFORMED_QUERYAnother alias; SOQL has no string functionsfield-reported, 3
Put ALL ROWS in the text of sf data query"unexpected token: 'ALL'"Drop it and pass --all-rows[ADV all-rows-is-a-cli-flag]
Query a change event or platform event"does not support query"There are no rows: not applicable, not unknown[ADV event-channels-do-not-support-query]

An error means the query did not run. Never read it as "no rows".

Read the whole error

  • Read the full message with its row, column and caret line. Do not pipe a query through a filter or send its errors to nowhere: 14 failures in the field record cost a second run because the message was hidden or cut.
  • Write --json results to a file and read the file. With --output-file, also pass --result-format.
  • --result-format csv printed blanks for aliased aggregates (field-reported): use JSON.
  • If you wrap queries in a redacting layer, keep the error code, the row and column and the schema part of the message (object, field, operator), and redact the literals in the echoed query line: a filter value can be private. Keep the raw response in private evidence when the task needs it.

Before a result goes anywhere

  • Say which you have: a drafted query, a schema check, or an executed query with its org, date and row count.
  • Zero rows needs a second look: = on text ignores case, a checkbox needs = true, a lowercased 18-character Id matches nothing (field-reported), and a permission set held through a group has no assignment row of its own [ADV psg-assignment-names-the-group].
  • A query straight after a save does not show asynchronous effects [ADV post-commit-work-is-invisible-to-the-caller].
  • Keep record values out of notes and shared documents. For a study of production data, count and group; put raw rows only in the private workspace, and only when the task needs them.
  • Record-count commands are approximate. Use SELECT COUNT() for a number you will quote.

On large objects

A filter helps only if it is selective and on an indexed field. Details, thresholds and how to read a query plan: references/query-and-cli-traps.md.

References

  • references/query-and-cli-traps.md: every trap with its check, selectivity, counting hierarchies, handing names to sub-agents.

Sources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.