Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Using Apex Variables in SOQL and SOSL Queries

SOQL and SOSL statements in Apex can reference Apex code variables and expressions if they’re preceded by a colon (:). This use of a local code variable within a SOQL or SOSL statement is called a bind. The Apex parser first evaluates the local variable in code context before executing the SOQL or SOSL statement. Bind expressions can be used as:

The search string in FIND clauses.
The filter literals in WHERE clauses.
The value of the IN or NOT IN operator in WHERE clauses, allowing filtering on a dynamic set of values. Note that this is of particular use with a list of IDs or Strings, though it works with lists of any type.
The division names in WITH DIVISION clauses.
The numeric value in LIMIT clauses.
The numeric value in OFFSET clauses.

For example:

1Account A = new Account(Name='xxx');
2insert A;
3Account B;
4
5// A simple bind
6B = [SELECT Id FROM Account WHERE Id = :A.Id];
7
8// A bind with arithmetic
9B = [SELECT Id FROM Account 
10     WHERE Name = :('x' + 'xx')];
11
12String s = 'XXX';
13
14// A bind with expressions
15B = [SELECT Id FROM Account 
16     WHERE Name = :'XXXX'.substring(0,3)];
17
18// A bind with INCLUDES clause
19B = [SELECT Id FROM Account WHERE :A.TYPE INCLUDES (‘Customer – Direct; Customer – Channel’)];
20
21// A bind with an expression that is itself a query result
22B = [SELECT Id FROM Account
23     WHERE Name = :[SELECT Name FROM Account
24                    WHERE Id = :A.Id].Name];
25
26Contact C = new Contact(LastName='xxx', AccountId=A.Id);
27insert new Contact[]{C, new Contact(LastName='yyy', 
28                                    accountId=A.id)};
29
30// Binds in both the parent and aggregate queries
31B = [SELECT Id, (SELECT Id FROM Contacts
32                 WHERE Id = :C.Id)
33     FROM Account
34     WHERE Id = :A.Id];
35
36// One contact returned
37Contact D = B.Contacts;
38
39// A limit bind
40Integer i = 1;
41B = [SELECT Id FROM Account LIMIT :i];
42
43// An OFFSET bind
44Integer offsetVal = 10;
45List<Account> offsetList = [SELECT Id FROM Account OFFSET :offsetVal];
46
47// An IN-bind with an Id list. Note that a list of sObjects
48// can also be used--the Ids of the objects are used for 
49// the bind
50Contact[] cc = [SELECT Id FROM Contact LIMIT 2];
51Task[] tt = [SELECT Id FROM Task WHERE WhoId IN :cc];
52
53// An IN-bind with a String list
54String[] ss = new String[]{'a', 'b'};
55Account[] aa = [SELECT Id FROM Account 
56                WHERE AccountNumber IN :ss];
57
58// A SOSL query with binds in all possible clauses
59
60String myString1 = 'aaa';
61String myString2 = 'bbb';
62Integer myInt3 = 11;
63String myString4 = 'ccc';
64Integer myInt5 = 22;
65
66List<List<SObject>> searchList = [FIND :myString1 IN ALL FIELDS 
67                                  RETURNING 
68                                     Account (Id, Name WHERE Name LIKE :myString2
69                                              LIMIT :myInt3), 
70                                     Contact, 
71                                     Opportunity, 
72                                     Lead 
73                                  WITH DIVISION =:myString4 
74                                  LIMIT :myInt5];

Apex bind variables aren’t supported for the units parameter in the DISTANCE function. This query doesn’t work.

1String units = 'mi';
2List<Account> accountList = 
3    [SELECT ID, Name, BillingLatitude, BillingLongitude 
4     FROM Account 
5     WHERE DISTANCE(My_Location_Field__c, GEOLOCATION(10,10), :units) < 10];

Note

Apex Developer Guide

Using Apex Variables in SOQL and SOSL Queries