Data Manipulation Language (DML) Database Methods

All database operations in Apex are transactional. For example, an implicit transaction is created when a trigger fires. If the code in a trigger completes without error, DML operations performed within it are automatically committed. If the trigger terminates prematurely with an uncaught exception, all DML operations are automatically rolled back. If multiple triggers fire for a single database operation, all trigger code succeeds or fails as a group.

In Chapter 4, you were exposed to DML statements. These statements accept a single record or batch of records. When operating on a batch, they succeed or fail on the entire group of records. For example, if 200 records are inserted and the last record fails with a validation error, none of the 200 records are inserted.

Apex offers a second way of making DML statements called DML database methods. DML database methods allow batch DML operations to fail on individual records without impacting the entire batch. To do this, they do not throw exceptions to indicate error. Instead they return an array of result objects, one per input record. These result objects contain a flag indicating success or failure, and error details in the event of failure.

A DML database method exists for each of the DML statements. Each method takes an optional Boolean parameter called opt_allOrNone to specify batch behavior. The default value is true, indicating that the behavior is “all or none.” This makes the method identical to a DML statement, with one failed record causing the failure of all records and a DmlException. But if the opt_allOrNone parameter is false, partial success is allowed.

Listing 5.18 inserts a batch of two Skill records using the insert database method. It passes false as an argument to allow partial success of the DML operation. The insert method returns an array of SaveResult objects. They correspond one-to-one with the array passed as an argument to the insert method. Each SaveResult object is examined to check for failure, and the results are displayed in the debug log.

Listing 5.18 DML Database Method Usage

Click here to view code image

Contact tim = [ SELECT Id
  FROM Contact
  WHERE Name = 'Tim Barr' LIMIT 1 ];
Skill__c skill1 = new Skill__c(Contact__c = tim.Id,
  Type__c = 'Java', Rating__c = '3 - Average'),
Skill__c skill2 = new Skill__c(Contact__c = tim.Id,
  Rating__c = '4 - Above Average'),
Skill__c[] skills = new  Skill__c[] { skill1, skill2 };
Database.SaveResult[] saveResults =
  Database.insert(skills, false);
for (Integer i=0; i<saveResults.size(); i++) {
  Database.SaveResult saveResult = saveResults[i];
  if (!saveResult.isSuccess()) {
    Database.Error err = saveResult.getErrors()[0];
    System.debug('Skill ' + i + ' insert failed: '
      + err.getMessage());
  } else {
    System.debug('Skill ' + i + ' insert succeeded: new Id = '
      + saveResult.getId());
  }
}

The result of executing this code is shown in Figure 5.6. The debug log indicates the first record is inserted, but the second failed because it doesn’t contain a value for the Type__c field. This is enforced by a validation rule created in Chapter 2. If you edit this code and remove the second argument to Database.insert, which enables partial success, the failure of the second record raises an exception and rolls back the successful insertion of the first record.

Figure 5.6 Results of insert DML database method