Persisting Database Records
Changes to database records in Force.com are saved using Data Manipulation Language (DML) operations. DML operations allow you to modify records one at a time, or more efficiently in batches of multiple records. The five major DML operation types are listed next. Each is discussed in more detail later in this subsection.
Insert—Creates new records.
Update—Updates the values in existing records, identified by Force.com unique identifier (Id) field or a custom field designated as an external identifier.
Upsert—If records with the same unique identifier or external identifier exist, this updates their values. Otherwise, it inserts them.
Delete—Moves records into the Recycle Bin.
Undelete—Restores records from the Recycle Bin.
DML operations can be included in Apex code in one of two ways: DML statements and database methods. Beyond the syntax, they differ in how errors are handled. If any one record in a DML statement fails, all records fail and are rolled back. Database methods allow for partial success. This chapter uses DML statements exclusively. Chapter 5 provides information on database methods.
Usage of DML in Apex is subject to governor limits. For example, you are limited to a total of 150 DML operations. The cumulative maximum number of records modified by all DML operations is 10,000.
Insert
The Insert statement adds up to 200 records of a single object type to the database. When all records succeed, they contain their new unique identifiers. If any record fails, a DmlException is raised and the database is returned to its state prior to the Insert statement. For example, the code in Listing 4.34 inserts a Contact record and uses it as the parent of a new Resource record.
Listing 4.34 Inserting a Record
try {
Contact c = new Contact(FirstName = 'Justin', LastName = 'Case',
Hourly_Cost_Rate__c = 75, Region__c = 'West'),
insert c;
} catch (DmlException e) {
System.debug(LoggingLevel.ERROR, e.getMessage());
}
Update
Update saves up to 200 existing records of a single object type. Existing records are identified by unique identifier (Id). Listing 4.35 illustrates the usage of the Update statement by creating a Resource record for Doug and updating it. Refresh the Resources tab in the native user interface to see the new record.
Contact doug = new Contact(FirstName = 'Doug', LastName = 'Hole'),
insert doug;
doug.Hourly_Cost_Rate__c = 100;
doug.Home_Office__c = 'London';
update doug;
Upsert
Upsert combines the behavior of the Insert and Update operations on up to 200 records of the same object type. First, it attempts to locate a matching record using its unique identifier or external identifier. If one is found, the statement acts as an Update. If not, it behaves as an Insert.
The syntax of the Upsert statement is identical to Update and Insert, but adds a second, optional argument for specifying an external identifier. If an external identifier is not provided, the record’s unique identifier is used. The code in Listing 4.36 upserts a record in the Contact object using the field Resource_ID__c (created in Chapter 11, “Advanced Integration”) as an external identifier. If a Contact record with a Resource_ID__c value of 1001 exists, it is updated. If not, it is created.
Listing 4.36 Upserting a Record
Contact c = new Contact(Resource_ID__c = 1001,
FirstName = 'Terry', LastName = 'Bull'),
upsert c Resource_ID__c;
Delete and Undelete
Delete and Undelete statements move up to 200 records of the same object type to and from the Recycle Bin, respectively. Listing 4.37 shows an example of the Delete statement. A new Resource record named Terry is added and then deleted.
Contact terry = new Contact(FirstName = 'Terry', LastName = 'Bull'),
insert terry;
delete terry;
Listing 4.38 builds on Listing 4.37 to undelete the Terry record. Concatenate the listings in the Execute Anonymous view to test. The database is queried to prove the existence of the undeleted record. Try running the code a second time with the undelete statement commented out to see that it is working as intended.
Listing 4.38 Undeleting Records
undelete terry;
Contact terry2 = [ SELECT Id, Name
FROM Contact WHERE Name LIKE 'Terry%' LIMIT 1 ];
System.debug(terry2.Name + ' exists'),
delete terry;