How to use the SOQL Formatter
- Paste a SOQL query into the input. Paste only the query, without the square brackets Apex puts around it.
- Choose how keywords and field lists should be laid out.
- Select Format query, or press Ctrl+Enter (⌘+Enter on a Mac).
- Copy the formatted query or download it. Use Minify to get it back on one line.
What a SOQL formatter does
SOQL from a debug log, a trace flag or a string in Apex is usually one long line. A formatter rewrites the same query across several lines with consistent indentation, so the fields, filters and ordering can be read at a glance. The query itself does not change: only spaces, line breaks and, if you choose, the letter case of keywords.
Example
Before:
select Id, Name, (select LastName from Contacts) from Account where Industry = 'Technology' and AnnualRevenue > 1000000 order by Name limit 20After:
SELECT
Id,
Name,
(
SELECT LastName
FROM Contacts
)
FROM Account
WHERE Industry = 'Technology'
AND AnnualRevenue > 1000000
ORDER BY Name
LIMIT 20How the layout is decided
- Up to three fields stay on the
SELECTline. More than three, or any subquery, puts one field per line. You can force either layout. - The first condition stays on the
WHEREline; each followingANDorORstarts an indented line. - A parenthesised group stays on one line when it is short, and is expanded when it is long or contains a subquery.
TYPEOFexpressions put eachWHENandELSEon its own line.
What the validation messages mean
The formatter reports problems it can see in the text itself: a missing FROM, a text value without a closing quote, parentheses that do not match, an extra comma in the field list, or clauses in an order Salesforce does not accept. These are structural checks. A query that formats cleanly can still fail in Salesforce if a field name is wrong, because only your org knows its schema.
Why meaning is preserved
The query is split into tokens: names, text values, numbers, operators and punctuation. Text inside quotes is treated as a single token and is never altered. After formatting, the output is split into tokens again and compared with the original list. Formatting is only accepted when the two lists match.
Features and limitations
What it does
- Each clause starts on its own line:
SELECT,FROM,WHERE,GROUP BY,HAVING,ORDER BY,LIMIT,OFFSET. - Child relationship subqueries and semi-joins are indented as queries of their own.
- Conditions break at
ANDandOR; long parenthesised groups are expanded. - Aggregate functions, date literals such as
LAST_N_DAYS:30,TYPEOFand bind variables such as:accountIdsare understood. - Object names that look like keywords, such as
Order,GroupandCase, are left alone. - A safety check compares the query before and after; if anything but spacing and keyword case changed, the result is not shown.
What it does not do
- It checks the shape of a query, not its meaning. It cannot know whether a field, object or relationship exists in your org.
- It does not run queries, estimate selectivity or check governor limits.
- SOSL (
FIND … RETURNING) is not supported. - Complex Apex expressions after a colon, such as
:map.get(key), may be rejected. Assign them to a variable first. - Comments are not part of SOQL and are reported as unexpected characters.