You can use a list to store sObjects. Lists are useful when working with SOQL queries. SOQL queries return sObject data and this data can be stored in a list of sObjects. Also, you can use lists to perform bulk operations, such as inserting a list of sObjects with one call.
To declare a list of sObjects, use the List keyword followed by the sObject type within <> characters. For example:
// Create an empty list of Accounts List<Account> myList = new List<Account>();
You can assign a List variable directly to the results of a SOQL query. The SOQL query returns a new list populated with the records returned. Make sure the declared List variable contains the same sObject that is being queried. Or you can use the generic sObject data type.
This example shows how to declare and assign a list of accounts to the return value of a SOQL query. The query returns up to 1,000 returns account records containing the Id and Name fields.
// Create a list of account records from a SOQL query
List<Account> accts = [SELECT Id, Name FROM Account LIMIT 1000];
As with lists of primitive data types, you can access and set elements of sObject lists using the List methods provided by Apex. For example:
List<Account> myList = new List<Account>(); // Define a new list Account a = new Account(Name='Acme'); // Create the account first myList.add(a); // Add the account sObject Account a2 = myList.get(0); // Retrieve the element at index 0
// Define the list List<Account> acctList = new List<Account>(); // Create account sObjects Account a1 = new Acount(Name='Account1'); Account a2 = new Acount(Name='Account2'); // Add accounts to the list acctList.add(a1); acctList.add(a2); // Bulk insert the list insert acctList;
Apex automatically generates IDs for each object in a list of sObjects when the list is successfully inserted or upserted into the database with a data manipulation language (DML) statement. Consequently, a list of sObjects cannot be inserted or upserted if it contains the same sObject more than once, even if it has a null ID. This situation would imply that two IDs would need to be written to the same structure in memory, which is illegal.
For example, the insert statement in the following block of code generates a ListException because it tries to insert a list with two references to the same sObject (a):
try { // Create a list with two references to the same sObject element Account a = new Account(); List<Account> accs = new List<Account>{a, a}; // Attempt to insert it... insert accs; // Will not get here System.assert(false); } catch (ListException e) { // But will get here }
Alternatively, you can use the array notation (square brackets) to declare and reference lists of sObjects.
Account[] accts = new Account[1];
accts[0] = new Account(Name='Acme2');
These are some additional examples of using the array notation with sObject lists.
Example | Description |
---|---|
List<Account> accts = new Account[]{}; |
Defines an Account list with no elements. |
List<Account> accts = new Account[] {new Account(), null, new Account()}; |
Defines an Account list with memory allocated for three Accounts, including a new Account object in the first position, null in the second position, and another new Account object in the third position. |
List<Contact> contacts = new List<Contact>
(otherList); |
Defines the Contact list with a new list. |