Your first SOQL query

In chapter 1 you learned what SOQL is and where it fits in the Salesforce world. Now you'll write a query, run it against a real org, and read the results. By the end of this chapter you'll know the shape every SOQL statement follows, two free places to execute queries, and how to recognize the two error messages every beginner meets first.

The anatomy of a query

Every SOQL statement is built from the same small set of clauses, and they always appear in the same order:

SELECT field1, field2
FROM ObjectName
WHERE condition
ORDER BY field
LIMIT n

Only SELECT and FROM are required — everything else is optional, but when you do use the optional clauses they must come in that order. WHERE before ORDER BY, ORDER BY before LIMIT. Swap them and the query won't parse.

Keywords are case-insensitive — select, Select, and SELECT all work — but the universal convention is UPPERCASE keywords with field and object names in their natural casing. Every example in this tutorial follows that convention, and you should too: it makes the structure of a query visible at a glance.

Where to run it

You need a place to type a query and see results. The two most common are built into (or built for) every Salesforce org, and both are free.

Developer Console. Inside Salesforce, click the gear icon in the top-right corner and choose Developer Console. A new window opens. At the bottom of that window, click the Query Editor tab, type your query into the text area, and press Execute. Results appear in a grid directly above the editor.

Workbench. Workbench is a free web tool that talks to your org through the API. Log in with your Salesforce credentials, then open the queries menu and choose SOQL Query. You can pick an object and tick fields to have it scaffold a query for you, or just type into the query box and run it. Workbench is handy because it shows you exactly what the API returns — which matters in a moment when we look at record Ids.

Run your first query

Open either tool and run this:

SELECT Id, Name FROM Account LIMIT 10

You get a grid: one row per Account record, one column per field you selected — here just Id and Name. If your org has fewer than ten Accounts you'll see fewer rows; LIMIT 10 is a ceiling, not a target.

Look closely at the Id column. Every Salesforce record has a unique Id, and it comes in two lengths. The 15-character form is the original, and it's case-sensitive — two Ids differing only in letter case are different records. The 18-character form adds a three-character suffix that makes the Id safe to use in case-insensitive systems like spreadsheets. The API — and therefore SOQL — returns the 18-character form; you'll still meet the 15-character form in Salesforce Classic URLs, some reports, and older tools. Both refer to the same record, so don't panic if an Id you copied from somewhere else is three characters shorter than the one in your query results.

Add a filter

Ten arbitrary Accounts isn't very useful. The WHERE clause narrows the results to records matching a condition:

SELECT Id, Name
FROM Account
WHERE Industry = 'Technology'

Text values in SOQL always take single quotes — 'Technology', never double quotes. The comparison here is an exact match: only Accounts whose Industry field is exactly Technology come back. There's a whole family of operators beyond = — the WHERE clause operators guide covers them all, and chapter 4 of this tutorial works through filtering in depth.

Sort and limit

ORDER BY sorts the results by one or more fields, and LIMIT caps how many rows you get back. Together they answer "give me the first few, in this order":

SELECT Id, Name
FROM Account
ORDER BY Name
LIMIT 5

Sorting is ascending by default; add DESC after the field name to reverse it (ORDER BY Name DESC). Now put every clause from this chapter into one query, in the required order:

SELECT Id, Name, Industry
FROM Account
WHERE Industry = 'Technology'
ORDER BY Name
LIMIT 5

Read it aloud: select the Id, Name, and Industry fields, from Account, where the industry is Technology, sorted by name, at most five rows. That sentence structure — fields, object, filter, sort, cap — is the skeleton of nearly every query you'll ever write.

The first errors you'll meet

Two error messages account for most beginner frustration, and both have quick fixes.

"No such column." SOQL only knows fields by their API name, which is not always the label you see on the page layout. The field labeled "Account Name" is Name; a custom field labeled "Region" is probably Region__c — every custom field's API name ends in __c. If a query complains that a column doesn't exist, check the field's API name in Object Manager (or in Workbench's field picker) before assuming anything else is wrong.

"Unexpected token." This is the parser telling you the query stopped making sense partway through. The usual suspects: a missing closing quote on a string, a missing comma between field names in the SELECT list, or clauses out of order — LIMIT before ORDER BY, for instance. Read the query left to right and you'll almost always spot it. When you hit something stranger, the common SOQL errors chapter is a field guide to the full bestiary.

Up next: choosing your fields

You can now write and run a complete query. The next step is getting better at the SELECT list itself — which fields exist on an object, how to find their API names quickly, and why there's no SELECT * in SOQL. That's chapter 3: selecting fields.