DML Lib

Appearance

Record & Records ​

Build records dynamically — set field values and parent relationships with the fluent DML.Record and DML.Records builders.

Example

apex
Account account = new Account(Name = 'My Account');
Contact newContact = new Contact(LastName = 'Doe');

new DML()
    .toInsert(account)
    .toInsert(DML.Record(newContact)
        .with(Contact.Email, 'john@example.com')
        .withRelationship(Contact.AccountId, account)
    )
    .commitWork();

INFO

DML.Record and DML.Records are accepted by the toInsert, toUpdate, and toUpsert registration methods, as well as the insertImmediately, updateImmediately, and upsertImmediately overloads. See Insert, Update, and Upsert.

DML.Record ​

Wrap a single record in a fluent builder.

Signature

apex
static DML.Record Record(SObject record);
static DML.Record Record(Id recordId);

By Record ​

Use when you already have the SObject in memory and want to set fields or relationships fluently.

Signature

apex
static DML.Record Record(SObject record);

Standard DML

apex
Contact contact = new Contact(LastName = 'Doe');
contact.Email = 'john@example.com';
insert contact;

DML Lib

apex
Contact newContact = new Contact(LastName = 'Doe');

new DML()
    .toInsert(DML.Record(newContact).with(Contact.Email, 'john@example.com'))
    .commitWork();

By Record ID ​

Builds an in-memory SObject of the ID's type — update or upsert a record by its ID while setting fields, without querying it first.

Signature

apex
static DML.Record Record(Id recordId);

Standard DML

apex
Id accountId = '001xx000003DGbYAAW';

Account account = [SELECT Id FROM Account WHERE Id = :accountId];
account.Industry = 'IT';
update account;

DML Lib

apex
Id accountId = '001xx000003DGbYAAW';

new DML()
    .toUpdate(DML.Record(accountId).with(Account.Industry, 'IT'))
    .commitWork();

WARNING

The record ID cannot be null. Passing a null Id throws a DmlException: Invalid argument: recordId. Record ID cannot be null.

DML.Records ​

Wrap a collection of records in a fluent builder. Every builder call (with, withRelationship) applies to every record in the collection.

Signature

apex
static DML.Records Records(List<SObject> records);
static DML.Records Records(Iterable<Id> recordIds);

By Records ​

Use when you already have the records in memory and want to set the same fields or relationships on all of them.

Signature

apex
static DML.Records Records(List<SObject> records);

Standard DML

apex
List<Contact> contacts = new List<Contact>{
    new Contact(LastName = 'Doe'),
    new Contact(LastName = 'Smith')
};

for (Contact c : contacts) {
    c.LeadSource = 'Web';
}
insert contacts;

DML Lib

apex
List<Contact> contacts = new List<Contact>{
    new Contact(LastName = 'Doe'),
    new Contact(LastName = 'Smith')
};

new DML()
    .toInsert(DML.Records(contacts).with(Contact.LeadSource, 'Web'))
    .commitWork();

WARNING

All records must share a single SObjectType. Mixed types throw a DmlException: Mixed SObject types in a single List<SObject> operation are not supported.

By Record IDs ​

Accepts a Set<Id> or List<Id>. The SObject type is resolved from the first ID. Update fields on many records by their IDs — no SOQL query needed.

Signature

apex
static DML.Records Records(Iterable<Id> recordIds);

Standard DML

apex
Set<Id> accountIds = new Set<Id>{ '001xx000003DGbYAAW', '001xx000003DGbZAAW' };

List<Account> accounts = [SELECT Id FROM Account WHERE Id IN :accountIds];
for (Account account : accounts) {
    account.Industry = 'IT';
}
update accounts;

DML Lib

apex
Set<Id> accountIds = new Set<Id>{ '001xx000003DGbYAAW', '001xx000003DGbZAAW' };

new DML()
    .toUpdate(DML.Records(accountIds).with(Account.Industry, 'IT'))
    .commitWork();

with ​

Set a field value. On DML.Records the value is applied to every record in the collection.

Signature

apex
DML.Record with(SObjectField field, Object value);
DML.Records with(SObjectField field, Object value);

Standard DML

apex
Contact contact = new Contact(LastName = 'Doe');
contact.Email = 'john@example.com';
insert contact;

DML Lib

apex
Contact newContact = new Contact(LastName = 'Doe');

new DML()
    .toInsert(DML.Record(newContact).with(Contact.Email, 'john@example.com'))
    .commitWork();

WARNING

Pass a field value (e.g. an Id or String), never an SObject. To relate records to each other, use withRelationship.

Relate a record to a parent record that may not have an ID yet. The relationship creates a dependency between the records — the parent is inserted first, and the foreign key is filled automatically at commit time.

Signature

apex
DML.Record withRelationship(SObjectField relationshipField, SObject relatedRecord);
DML.Records withRelationship(SObjectField relationshipField, SObject relatedRecord);

Standard DML

apex
Account account = new Account(Name = 'Parent Account');
insert account;

Contact contact = new Contact(LastName = 'Doe', AccountId = account.Id);
insert contact;

DML Lib

apex
Account account = new Account(Name = 'Parent Account');
Contact newContact = new Contact(LastName = 'Doe');

new DML()
    .toInsert(account)
    .toInsert(DML.Record(newContact).withRelationship(Contact.AccountId, account))
    .commitWork();

INFO

The related record becomes part of the dependency graph, which determines the execution order of the DML operations. See Registration for details.

WARNING

The field passed as relationshipField must be a relationship field. Otherwise a DmlException is thrown at registration: Invalid argument: <FieldName>. Field supplied is not a relationship field.

withRelationship (External ID) ​

Relate a record to a parent by the parent's External ID field value instead of its Salesforce ID.

Signature

apex
DML.Record withRelationship(SObjectField relationshipField, SObjectField relatedObjectExternalIdField, Object relatedRecordExternalId);
DML.Records withRelationship(SObjectField relationshipField, SObjectField relatedObjectExternalIdField, Object relatedRecordExternalId);

Standard DML

apex
Contact contact = new Contact(LastName = 'Smith');
contact.Account = new Account(ExternalId__c = 'EXT-001');
insert contact;

DML Lib

apex
Contact newContact = new Contact(LastName = 'Smith');

new DML()
    .toInsert(DML.Record(newContact)
        .withRelationship(Contact.AccountId, Account.ExternalId__c, 'EXT-001')
    )
    .commitWork();

INFO

At commit time the library attaches a new in-memory parent SObject with only the External ID field populated, and the platform resolves the actual foreign key during the DML operation. Unlike the Related Record variant, the parent record is not part of the unit of work, and no execution-ordering dependency is created.

WARNING

The arguments are validated at registration. A DmlException is thrown when:

  • relationshipField is not a relationship field: Invalid argument: relationshipField. Field supplied is not a relationship field.
  • relatedObjectExternalIdField is not marked as an External ID: Invalid argument: externalIdField. Field supplied is not marked as an External Identifier.
  • relatedObjectExternalIdField does not exist on the related SObject: Invalid argument: externalIdField. Field supplied is not a known field on the target sObject.