SOQL and SOSL Queries

You can evaluate Salesforce Object Query Language (SOQL) or Salesforce Object Search Language (SOSL) statements on-the-fly in Apex by surrounding the statement in square brackets.

SOQL Statements

SOQL statements evaluate to a list of sObjects, a single sObject, or an Integer for count method queries.

For example, you could retrieve a list of accounts that are named Acme:

1List<Account> aa = [SELECT Id, Name FROM Account WHERE Name = 'Acme'];

From this list, you can access individual elements:

1if (!aa.isEmpty()) {
2   // Execute commands
3}

You can also create new objects from SOQL queries on existing ones. This example creates a new contact for the first account with the number of employees greater than 10.

1Contact c = new Contact(Account = [SELECT Name FROM Account 
2    WHERE NumberOfEmployees > 10 LIMIT 1]);
3c.FirstName = 'James';
4c.LastName = 'Yoyce';

The newly created object contains null values for its fields, which must be set.

The count method can be used to return the number of rows returned by a query. The following example returns the total number of contacts with the last name of Weissman:

1Integer i = [SELECT COUNT() FROM Contact WHERE LastName = 'Weissman'];

You can also operate on the results using standard arithmetic:

1Integer j = 5 * [SELECT COUNT() FROM Account];

SOQL limits apply when executing SOQL queries. See Execution Governors and Limits.

For a full description of SOQL query syntax, see the Salesforce SOQL and SOSL Reference Guide.

SOSL Statements

SOSL statements evaluate to a list of lists of sObjects, where each list contains the search results for a particular sObject type. The result lists are always returned in the same order as they were specified in the SOSL query. If a SOSL query doesn’t return any records for a specified sObject type, the search results include an empty list for that sObject.

For example, you can return a list of accounts, contacts, opportunities, and leads that begin with the phrase map:

1List<List<SObject>> searchList = [FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead];

The syntax of the FIND clause in Apex differs from the syntax of the FIND clause in SOAP API and REST API:

In Apex, the value of the FIND clause is demarcated with single quotes. For example:
1FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead
Note
In the API, the value of the FIND clause is demarcated with braces. For example:
1FIND {map*} IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead

Apex that is running in system mode ignores field-level security while scanning for a match using IN ALL FIELDS.

Note

From searchList, you can create arrays for each object returned:

1Account [] accounts = ((List<Account>)searchList[0]);
2Contact [] contacts = ((List<Contact>)searchList[1]);
3Opportunity [] opportunities = ((List<Opportunity>)searchList[2]);
4Lead [] leads = ((List<Lead>)searchList[3]);

SOSL limits apply when executing SOSL queries. See Execution Governors and Limits.

For a full description of SOSL query syntax, see the Salesforce SOQL and SOSL Reference Guide.

Apex Developer Guide

SOQL and SOSL Queries

SOQL Statements

SOSL Statements