What is SOQL? Salesforce's query language, explained

Every report, dashboard, integration, and export that pulls data out of Salesforce is, somewhere underneath, running a SOQL query. Learn SOQL and you stop waiting on admins and analysts — you ask the database directly. This first chapter explains what SOQL is, how Salesforce organizes the data you'll query, and where you can run your first query in the next chapter.

SOQL in one paragraph

SOQL — the Salesforce Object Query Language — is the language for reading data out of Salesforce. It is read-only: a SOQL query can never create, change, or delete a record, which makes it safe to experiment with. Each query starts from one object (Salesforce's word for a table) and can reach into that object's related records, but it always has a single home base. And it is everywhere: the report builder, list views, the APIs, Apex code, and every third-party tool that pulls Salesforce data ultimately speak SOQL. Whatever interface sits on top, this is the language underneath.

Objects, fields, and records

If you've used a spreadsheet or a database, the mapping is straightforward: an object is roughly a table, a field is a column, and a record is a row. The caveat in "roughly" is that objects carry more than tables do — validation rules, security, automation, and built-in relationships to other objects — but for writing queries, table/column/row is the right mental model.

Salesforce ships with standard objects that cover common sales and service data: Account (companies), Contact (people), Opportunity (deals), Case (support tickets), and Lead (prospects not yet qualified). Your org almost certainly also has custom objects, created by an admin for data specific to your business. You can spot them instantly: their API names end in __c, as do custom fields on any object.

A standard object with standard fields:

SELECT Name, Industry FROM Account

And a custom object with a custom field — note the __c suffixes:

SELECT Id, Name, Status__c FROM Invoice__c

One field deserves a special mention now: every record on every object has an Id — a unique identifier Salesforce assigns automatically. You will select it constantly.

SOQL vs SQL, in 30 seconds

If you know SQL, SOQL will look familiar and then surprise you. The four differences that matter most:

• No SELECT *. You name every field you want back, explicitly. (The closest thing, the FIELDS() shortcut, is a limited exploration tool — chapter 3 covers it.)
• No JOIN keyword. Related data is reached through relationship paths like Account.Name and nested subqueries instead — we cover these in the relationships chapter.
• Read-only. There is no INSERT, UPDATE, or DELETE in SOQL. Writes happen through other mechanisms.
• Governed limits. Salesforce is a shared platform, so queries run under enforced limits on rows returned and resources consumed. You'll feel these mostly in code, not in ad-hoc queries.

If you're coming from a SQL background, the full comparison in SOQL vs SQL is worth ten minutes; if SOQL is your first query language, you're arguably lucky — nothing to unlearn.

SOQL vs SOSL

Salesforce has a second query language you'll bump into: SOSL, the Salesforce Object Search Language. The two answer different questions. SOQL is a structured query: you know which object holds the data and which fields you want, and you filter on field values. SOSL is a full-text search: you have a piece of text and want to find it anywhere, across multiple objects at once. SOSL uses FIND instead of SELECT:

FIND {acme} IN ALL FIELDS
RETURNING Account(Id, Name), Contact(Id, LastName)

That searches every searchable field for "acme" and returns matching Accounts and Contacts in one shot — something SOQL cannot do, because a SOQL query has exactly one base object. The rule of thumb: reach for SOSL when you'd reach for a search box ("find anything mentioning acme"), and SOQL for everything else ("accounts in the Technology industry created this year"). This tutorial is about SOQL, which is what you'll use the overwhelming majority of the time.

Where you can run SOQL

SOQL is a language, not a tool — you need somewhere to type it. All of these run the same queries against the same data:

For this tutorial you only need the first one: the Developer Console is built into most Salesforce editions — including the free Developer Edition orgs anyone can sign up for — with nothing to install.

A first taste

Here is a complete, real SOQL query:

SELECT Id, Name FROM Account LIMIT 5

Read it left to right: give me the Id and Name fields, from the Account object, and stop after five records. Run it and you get back a small result table — five rows, two columns — listing the first five accounts Salesforce finds. No filter, no sorting, just raw records. Every query you will ever write is an elaboration of this shape: more fields, a WHERE clause to filter, an ORDER BY to sort, relationships to traverse.

And here is a glimpse of where we're headed:

SELECT Id, Name, Amount
FROM Opportunity
WHERE Amount > 50000 AND IsClosed = false
ORDER BY Amount DESC
LIMIT 10

Don't worry about parsing that second one yet — by the middle of this tutorial it will read like a plain sentence. In chapter 2 you'll open the Developer Console, run your first query against a live org, and see real results come back.