SOQL SELECT Syntax

SOQL query syntax consists of a required SELECT statement followed by one or more optional clauses such as TYPEOF, WHERE, WITH, GROUP BY,ORDER BY.

The SOQL SELECT statement uses the following syntax:

1SELECT fieldList [subquery][...]
2[TYPEOF typeOfField whenExpression[...] elseExpression END][...]
3FROM objectType[,...] 
4    [USING SCOPE filterScope]
5[WHERE conditionExpression]
6[WITH [DATA CATEGORY] filteringExpression]
7[GROUP BY {fieldGroupByList|ROLLUP (fieldSubtotalGroupByList)|CUBE (fieldSubtotalGroupByList)} 
8    [HAVING havingConditionExpression] ] 
9[ORDER BY fieldOrderByList {ASC|DESC} [NULLS {FIRST|LAST}] ]
10[LIMIT numberOfRowsToReturn]
11[OFFSET numberOfRowsToSkip]
12[FOR {VIEW  | REFERENCE}[,...] ]
13[ UPDATE {TRACKING|VIEWSTAT}[,...] ]

TYPEOF is currently available as a Developer Preview as part of the SOQL Polymorphism feature. For more information on enabling TYPEOF for your organization, contact Salesforce.

Note

Syntax	Description
`fieldList subquery`	Specifies a list of one or more fields, separated by commas, that you want to retrieve from the specified `object`. The bold elements in the following examples are `fieldlist`s: `SELECT Id, Name, BillingCity FROM Account` `SELECT count() FROM Contact` `SELECT Contact.Firstname, Contact.Account.Name FROM Contact` You must specify valid field names and must have read-level permissions to each specified field. The `fieldList` defines the ordering of fields in the query results. `fieldList` can include a subquery if the query traverses a relationship. For example: `1SELECT Account.Name, (SELECT Contact.LastName FROM Account.Contacts) 2FROM Account` The `fieldlist` can also be an aggregate function, such as `COUNT()` and `COUNT(fieldName)`, or be wrapped in `toLabel()`.
`typeOfField`	A polymorphic relationship field in `objectType` or a polymorphic field in a parent of `objectType` that can reference multiple object types. For example, the What relationship field of an Event could be an Account, a Campaign, or an Opportunity. `typeOfField` cannot reference a relationship field that is also referenced in `fieldList`. See `TYPEOF` for more information.
`whenExpression`	A clause of the form `WHEN whenObjectType THEN whenFieldList`. You can have one or more `whenExpression` clauses inside a `TYPEOF` expression. See `TYPEOF` for more information.
`elseExpression`	A clause of the form `ELSE elseFieldList`. This clause is optional inside a `TYPEOF` expression. See `TYPEOF` for more information.
`objectType`	Specifies the type of object that you want to `query()`. You must specify a valid object, such as Account, and must have read-level permissions to that object.
`filterScope`	Available in API version 32.0 and later. Specifies the filterScope for limiting the results of the query.
`conditionExpression`	If `WHERE` is specified, determines which rows and values in the specified object (`objectType`) to filter against. If unspecified, the `query()` retrieves all the rows in the object that are visible to the user.
`filteringExpression`	If `WITH DATA CATEGORY` is specified, the `query()` only returns matching records that are associated with the specified data categories and are visible to the user. If unspecified, the `query()` returns the matching records that are visible to the user. The `WITH DATA CATEGORY` clause only filters objects of type: `Question`—to query questions. `KnowledgeArticleVersion`—to query articles. For more information about the `WITH DATA CATEGORY` clause, see `WITH DATA CATEGORY` `filteringExpression`.
`fieldGroupByList`	Available in API version 18.0 and later. Specifies a list of one or more fields, separated by commas, that are used to group the query results. A `GROUP BY` clause is used with aggregate functions to summarize the data and enable you to roll up query results rather than having to process the individual records in your code. See `GROUP BY`.
`fieldSubtotalGroupByList`	Available in API version 18.0 and later. Specifies a list of up to three fields, separated by commas, that are used to group the query results. The results include extra subtotal rows for the grouped data. See `GROUP BY ROLLUP` and `GROUP BY CUBE`.
`havingConditionExpression`	Available in API version 18.0 and later. If the query includes a `GROUP BY` clause, this conditional expression filters the records that the GROUP BY returns. See `HAVING`.
`fieldOrderByList`	Specifies a list of one or more fields, separated by commas, that are used to order the query results. For example, you can query for contacts and order the results by last name, and then by first name: `1SELECT Id, LastName, FirstName 2FROM Contact 3ORDER BY LastName, FirstName`

Note the following implementation tips:

Statement Character Limit—By default, SOQL statements cannot exceed 20,000 characters in length. For SOQL statements that exceed this maximum length, the API returns a MALFORMED_QUERY exception code; no result rows are returned.
Long, complex SOQL statements, such as statements that contain a large number of formula fields, can sometimes result in a QUERY_TOO_COMPLICATED error. This occurs because the statement is expanded internally when processed by Salesforce, even though the original SOQL statement is under the 20,000 character limit. To avoid this, reduce the complexity of your SOQL statement.
Note
Localized Results—SELECT statements can include the toLabel() and convertCurrency() functions in support of localized fields.
Dynamic SOQL in Apex—Apex requires that you surround SOQL and SOSL statements with square brackets in order to use them on the fly. Additionally, Apex script variables and expressions can be used if preceded by a colon (:).
Ordered Results—There is no guarantee of the order of results unless you use an ORDER BY clause in a query.

Force.com SOQL and SOSL Reference

No Results

SOQL SELECT Syntax