Upsert

Insert new records or update existing ones based on record ID.

Example

Account existingAccount = [SELECT Id, Name FROM Account LIMIT 1];
existingAccount.Name = 'Updated Name';

Account newAccount = new Account(Name = 'New Account');

new DML()
    .toUpsert(existingAccount)
    .toUpsert(newAccount)
    .systemMode()
    .withoutSharing()
    .commitWork();

toUpsert

Register records for upsert. The actual DML is executed when commitWork() is called.

Signature

Commitable toUpsert(SObject record);
Commitable toUpsert(DML.Record record);
Commitable toUpsert(Iterable<SObject> records);
Commitable toUpsert(DML.Records records);

Single Record

Signature

Commitable toUpsert(SObject record);

Standard DML

Account account = new Account(Name = 'My Account');
upsert account;

DML Lib

Account account = new Account(Name = 'My Account');

new DML()
    .toUpsert(account)
    .commitWork();

Parent Relationship

Handle parent-child relationships automatically.

Signature

Commitable toUpsert(DML.Record record);

Standard DML

Account account = new Account(Name = 'Parent Account');
upsert account;

Contact contact = new Contact(
    FirstName = 'John', 
    LastName = 'Doe', 
    AccountId = account.Id
);
upsert contact;

DML Lib

Account account = new Account(Name = 'Parent Account');
Contact contact = new Contact(FirstName = 'John', LastName = 'Doe');

new DML()
    .toUpsert(account)
    .toUpsert(DML.Record(contact).withRelationship(Contact.AccountId, account))
    .commitWork();

With Field

Set field values dynamically using DML.Record.

Signature

Commitable toUpsert(DML.Record record);

Standard DML

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

DML Lib

Contact contact = new Contact(LastName = 'Doe');

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

Multiple Records

Signature

Commitable toUpsert(Iterable<SObject> records);
Commitable toUpsert(DML.Records records);

Standard DML

List<Account> accounts = new List<Account>{
    new Account(Name = 'New Account'),
    new Account(Id = existingId, Name = 'Updated Account')
};
upsert accounts;

DML Lib

List<Account> accounts = new List<Account>{
    new Account(Name = 'New Account'),
    new Account(Id = existingId, Name = 'Updated Account')
};

new DML()
    .toUpsert(accounts)
    .commitWork();

Parent Relationship

Signature

Commitable toUpsert(DML.Records records);

Standard DML

Account account = new Account(Name = 'My Account');
upsert account;

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

for (Contact c : contacts) {
    c.AccountId = account.Id;
}
upsert contacts;

DML Lib

Account account = new Account(Name = 'My Account');

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

new DML()
    .toUpsert(account)
    .toUpsert(DML.Records(contacts).withRelationship(Contact.AccountId, account))
    .commitWork();

With Field

Set field values dynamically for multiple records using DML.Records.

Signature

Commitable toUpsert(DML.Records records);

Standard DML

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

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

DML Lib

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

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

upsertImmediately

Upsert records immediately and return the operation result without calling commitWork().

Signature

OperationResult upsertImmediately(SObject record);
OperationResult upsertImmediately(DML.Record record);
OperationResult upsertImmediately(List<SObject> records);
OperationResult upsertImmediately(DML.Records records);

TIP

All DML settings configured on the DML instance (such as userMode(), systemMode(), withSharing(), withoutSharing(), allowPartialSuccess()) are inherited when executing upsertImmediately.

Single Record

Signature

OperationResult upsertImmediately(SObject record);

Standard DML

Account account = new Account(Name = 'My Account');
Database.UpsertResult result = Database.upsert(account);

DML Lib

Account account = new Account(Name = 'My Account');
DML.OperationResult result = new DML().upsertImmediately(account);

Parent Relationship

Handle parent-child relationships automatically.

Signature

OperationResult upsertImmediately(DML.Record record);

Standard DML

Account account = new Account(Name = 'Parent Account');
Database.UpsertResult accountResult = Database.upsert(account);

Contact contact = new Contact(
    FirstName = 'John', 
    LastName = 'Doe', 
    AccountId = account.Id
);
Database.UpsertResult contactResult = Database.upsert(contact);

DML Lib

Account account = new Account(Name = 'Parent Account');
new DML().upsertImmediately(account);

Contact contact = new Contact(FirstName = 'John', LastName = 'Doe');
DML.OperationResult result = new DML()
    .upsertImmediately(DML.Record(contact).withRelationship(Contact.AccountId, account));

With Field

Set field values dynamically using DML.Record.

Signature

OperationResult upsertImmediately(DML.Record record);

Standard DML

Contact contact = new Contact(LastName = 'Doe');
contact.Email = 'john@example.com';
Database.UpsertResult result = Database.upsert(contact);

DML Lib

Contact contact = new Contact(LastName = 'Doe');
DML.OperationResult result = new DML()
    .upsertImmediately(DML.Record(contact).with(Contact.Email, 'john@example.com'));

Multiple Records

Signature

OperationResult upsertImmediately(List<SObject> records);
OperationResult upsertImmediately(DML.Records records);

Standard DML

List<Account> accounts = new List<Account>{
    new Account(Name = 'New Account'),
    new Account(Id = existingId, Name = 'Updated Account')
};
List<Database.UpsertResult> results = Database.upsert(accounts);

DML Lib

List<Account> accounts = new List<Account>{
    new Account(Name = 'New Account'),
    new Account(Id = existingId, Name = 'Updated Account')
};
DML.OperationResult result = new DML().upsertImmediately(accounts);

Parent Relationship

Signature

OperationResult upsertImmediately(DML.Records records);

Standard DML

Account account = new Account(Name = 'My Account');
Database.UpsertResult accountResult = Database.upsert(account);

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

for (Contact c : contacts) {
    c.AccountId = account.Id;
}
List<Database.UpsertResult> results = Database.upsert(contacts);

DML Lib

Account account = new Account(Name = 'My Account');
new DML().upsertImmediately(account);

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

DML.OperationResult result = new DML()
    .upsertImmediately(DML.Records(contacts).withRelationship(Contact.AccountId, account));

With Field

Set field values dynamically for multiple records using DML.Records.

Signature

OperationResult upsertImmediately(DML.Records records);

Standard DML

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

for (Contact c : contacts) {
    c.LeadSource = 'Web';
}
List<Database.UpsertResult> results = Database.upsert(contacts);

DML Lib

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

DML.OperationResult result = new DML()
    .upsertImmediately(DML.Records(contacts).with(Contact.LeadSource, 'Web'));