Apex Developer Guide

Apex Developer Guide
Getting Started with Apex
Writing Apex
Data Types and Variables
Control Flow Statements
Classes, Objects, and Interfaces
Working with Data in Apex
Working with sObjects
Data Manipulation Language
SOQL and SOSL Queries
SOQL For Loops
sObject Collections
Lists of sObjects
Sorting Lists of sObjects
Expanding sObject and List Expressions
Sets of Objects
Maps of sObjects
Dynamic Apex
Apex Security and Sharing
Custom Settings
Running Apex
Debugging, Testing, and Deploying Apex
Apex Reference
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Lists of sObjects

Lists can contain sObjects among other types of elements. Lists of sObjects can be used for bulk processing of data.

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:

Auto-populating a List from a SOQL Query

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 that 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.

Adding and Retrieving List Elements

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:

Bulk Processing

You can bulk-process a list of sObjects by passing a list to the DML operation. This example shows how you can insert a list of accounts.

If you perform a bulk insert of Knowledge article versions, make the ownerId of all records the same.

Note

Record ID Generation

Apex automatically generates IDs for each object in an sObject list that was inserted or upserted using DML. Therefore, a list that contains more than one instance of an sObject cannot be inserted or upserted 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):

Using Array Notation for One-Dimensional Lists of sObjects

Alternatively, you can use the array notation (square brackets) to declare and reference lists of sObjects.

This example declares a list of accounts using the array notation.
This example adds an element to the list using square brackets.

These examples also use the array notation with sObject lists.

Example Description
Defines an Account list with no elements.
Defines an Account list with memory allocated for three Accounts: a new Account object in the first position, null in the second, and another new Account object in the third.
Defines the Contact list with a new list.