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:

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

From this list, you can access individual elements:

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

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.

Contact c = new Contact(Account = [SELECT Name FROM Account 
    WHERE NumberOfEmployees > 10 WITH USER_MODE LIMIT 1]);
c.FirstName = 'James';
c.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:

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

You can also operate on the results using standard arithmetic:

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

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:

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

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:
```
FIND '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.
In the API, the value of the FIND clause is demarcated with braces. For example:
```
FIND {map*} IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead
```

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

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

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

Note

The 4,000 characters limit for WHERE clause strings doesn’t apply to SOQL queries in Apex if the WHERE clause includes the IN operator.

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