Skip to content

DML_Builder ​

Class · Group: DML

Learn it: Fast Start - DML and DML guide

apex
global inherited sharing class DML_Builder

Fluent DML API for building and running database operations: you set it up by chaining method calls. A static method, newTransaction(), starts a transaction. Chained methods add operations and change how they run. A final method, execute(), saves all operations through DML_Transaction.

Example

apex
DML_Builder.TransactionResult result = DML_Builder.newTransaction()
    .doInsert(account)
    .doInsert(contact, Contact.AccountId, account)
    .doUpdate(existingRecord)
    .allowPartial()
    .execute();

See Also: DML_Transaction


Methods by task ​

Find a method by what you want to do. A group links to a worked example when a guide has one. Every method is described in the full list below.

GroupMethodsWorked example
Register records and save themasync doDelete doInsert doUndelete doUpdate doUpsert execute newTransactionTransactional DML Pattern (DML_Builder), Mixed Operations and Rollback
Handle records that fail to saveallowPartial expectRefusal suppressExceptions suppressLogging withRetryOnLockLogging a refusal you expect below ERROR, Retrying When Another Transaction Holds the Row
Choose security and sharingbypassSharing withSystemMode withUserModeOperation-Level Sharing, Access Mode (USER_MODE / SYSTEM_MODE)

Methods ​

MethodDescription
global DML_Builder allowPartial()Enables partial success mode.
global DML_Builder.DML_AsyncBuilder async()Switches to asynchronous mode.
global DML_Builder bypassSharing()Ignores record sharing for this save, so the running user can save records that other users own and that the user cannot see.
global DML_Builder doDelete(List<SObject> records)Registers multiple records for deletion.
global DML_Builder doDelete(SObject record)Registers a single record for deletion.
global DML_Builder doInsert(List<SObject> records)Registers multiple records for insertion.
global DML_Builder doInsert(SObject record)Registers a single record for insertion.
global DML_Builder doInsert(SObject child, SObjectField relationshipField, SObject parent)Registers a child record for insertion with a relationship to a parent record.
global DML_Builder doUndelete(List<SObject> records)Registers multiple records for undelete.
global DML_Builder doUndelete(SObject record)Registers a single record for undelete.
global DML_Builder doUpdate(List<SObject> records)Registers multiple records for update.
global DML_Builder doUpdate(SObject record)Registers a single record for update.
global DML_Builder doUpsert(List<SObject> records)Registers multiple records for upsert.
global DML_Builder doUpsert(List<SObject> records, SObjectField externalIdField)Registers multiple records for upsert with a specific external ID field.
global DML_Builder doUpsert(SObject record)Registers a single record for upsert.
global DML_Builder doUpsert(SObject record, SObjectField externalIdField)Registers a single record for upsert with a specific external ID field.
global DML_Builder.TransactionResult execute()Commits all registered DML operations via DML_Transaction and returns the result.
global DML_Builder expectRefusal(System.StatusCode statusCode)Declares a refusal you expect and handle, so a row refused for that reason is logged at WARN instead of ERROR when the transaction allows partial success.
global static DML_Builder newTransaction()Creates a new DML_Builder instance representing a DML transaction.
global DML_Builder suppressExceptions()Stops a DmlException from being thrown again in all-or-nothing mode.
global DML_Builder suppressLogging()Turns off LOG_Builder error logging for DML failures.
global DML_Builder withRetryOnLock()Tries the save again, once, when the platform refuses it because another transaction holds a record (UNABLE_TO_LOCK_ROW).
global DML_Builder withRetryOnLock(Integer retries)Tries the save again up to the given number of times when the platform refuses it because another transaction holds a record (UNABLE_TO_LOCK_ROW).
global DML_Builder withSystemMode()Forces AccessLevel.SYSTEM_MODE on every DML operation in this transaction.
global DML_Builder withUserMode()Forces AccessLevel.USER_MODE on every DML operation in this transaction, whatever the UserModeDml_Enabled feature flag says.

allowPartial ​

apex
global DML_Builder allowPartial()

Enables partial success mode. Failed records do not cause the entire transaction to fail. An exception during the save is not thrown either, and nothing is rolled back: the statements already done stay saved, and the statements not yet run do not run. The returned TransactionResult then reports a failure, and getFailureMessage() gives the reason.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(records)
    .allowPartial()
    .execute();

async ​

apex
global DML_Builder.DML_AsyncBuilder async()

Switches to asynchronous mode. Returns a DML_AsyncBuilder that hands the work to PROC_ExecuteDML and UTIL_AsynchronousJobLauncher, which pick a Queueable or Batch job to suit the volume.

Five settings you made still apply in the job: the access mode (.withUserMode() or .withSystemMode()), partial success (.allowPartial()), ignoring record sharing (.bypassSharing()), the refusals you declared with .expectRefusal(), which the job logs at WARN as a save in your own transaction would, and the row-lock retry count (.withRetryOnLock()), which every batch applies within its own limits. The async job itself runs without sharing, so the job sets record sharing explicitly: enforced by default, ignored only when .bypassSharing() was called. The sharing of your own class does not carry into the job. .suppressExceptions() and .suppressLogging() are dropped on purpose. They change the return value and error logging of a save in your own transaction, and an async job has no caller to return a result to. The job's failures are always logged and reported through the async framework's own error handling.

Returns DML_Builder.DML_AsyncBuilder — A DML_AsyncBuilder for configuring and executing async DML.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(records)
    .allowPartial()
    .async()
    .execute();

bypassSharing ​

apex
global DML_Builder bypassSharing()

Ignores record sharing for this save, so the running user can save records that other users own and that the user cannot see. What else is checked depends on the access mode:

  • In user mode (the default while the UserModeDml_Enabled flag is on, or after withUserMode()), the running user's object and field permissions still apply. A field the user cannot create or edit is left out of the save, with no error, and the save logs one warning that names the object and the field. A save the user has no object permission for, an upsert on an external Id field the user cannot read or edit, and a save that would leave out the field that links a record to its parent are refused as user mode refuses them. A record that names its parent only by an external Id the user cannot read is refused by Salesforce, with a message that does not name the field.

  • With withSystemMode(), in either order, the object and field permissions are not checked either.

  • With the UserModeDml_Enabled flag off, a save with no access mode runs in system mode, so nothing is checked, as for any save.

When the save runs, the framework's bypass audit records it: log entries, one for each kind of record saved, that say this save ignored record sharing.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
// Ignores record sharing; the running user's object and field permissions still apply.
DML_Builder.newTransaction()
    .doUpdate(records)
    .bypassSharing()
    .execute();
// Ignores record sharing and the running user's object and field permissions.
DML_Builder.newTransaction()
    .doUpdate(records)
    .withSystemMode()
    .bypassSharing()
    .execute();

doDelete ​

apex
global DML_Builder doDelete(List<SObject> records)

Registers multiple records for deletion.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to delete.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doDelete(records)
    .execute();
apex
global DML_Builder doDelete(SObject record)

Registers a single record for deletion.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to delete.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doDelete(record)
    .execute();

doInsert ​

apex
global DML_Builder doInsert(List<SObject> records)

Registers multiple records for insertion.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to insert.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(accounts)
    .execute();
apex
global DML_Builder doInsert(SObject record)

Registers a single record for insertion.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to insert.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(new Account(Name = 'Test'))
    .execute();
apex
global DML_Builder doInsert(SObject child, SObjectField relationshipField, SObject parent)

Registers a child record for insertion with a relationship to a parent record.

Parameters

ParameterTypeDescription
childSObjectThe child SObject to insert.
relationshipFieldSObjectFieldThe field linking the child to the parent.
parentSObjectThe parent SObject.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(account)
    .doInsert(contact, Contact.AccountId, account)
    .execute();

doUndelete ​

apex
global DML_Builder doUndelete(List<SObject> records)

Registers multiple records for undelete.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to undelete.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUndelete(records)
    .execute();
apex
global DML_Builder doUndelete(SObject record)

Registers a single record for undelete.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to undelete.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUndelete(record)
    .execute();

doUpdate ​

apex
global DML_Builder doUpdate(List<SObject> records)

Registers multiple records for update.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to update.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(accounts)
    .execute();
apex
global DML_Builder doUpdate(SObject record)

Registers a single record for update.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to update.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(account)
    .execute();

doUpsert ​

apex
global DML_Builder doUpsert(List<SObject> records)

Registers multiple records for upsert.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to upsert.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpsert(accounts)
    .execute();
apex
global DML_Builder doUpsert(List<SObject> records, SObjectField externalIdField)

Registers multiple records for upsert with a specific external ID field.

Parameters

ParameterTypeDescription
recordsListThe list of SObjects to upsert.
externalIdFieldSObjectThe external ID field for matching.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpsert(accounts, Account.ExternalId__c)
    .execute();
apex
global DML_Builder doUpsert(SObject record)

Registers a single record for upsert.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to upsert.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpsert(account)
    .execute();
apex
global DML_Builder doUpsert(SObject record, SObjectField externalIdField)

Registers a single record for upsert with a specific external ID field.

Parameters

ParameterTypeDescription
recordSObjectThe SObject to upsert.
externalIdFieldSObjectFieldThe external ID field for matching.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpsert(account, Account.ExternalId__c)
    .execute();

execute ​

apex
global DML_Builder.TransactionResult execute()

Commits all registered DML operations via DML_Transaction and returns the result.

Returns DML_Builder.TransactionResult — A TransactionResult containing the outcome of all DML operations.

Example

apex
DML_Builder.TransactionResult result = DML_Builder.newTransaction()
    .doInsert(account)
    .doInsert(contact, Contact.AccountId, account)
    .execute();

expectRefusal ​

apex
global DML_Builder expectRefusal(System.StatusCode statusCode)

Declares a refusal you expect and handle, so a row refused for that reason is logged at WARN instead of ERROR when the transaction allows partial success. Every other failed row still logs at ERROR, and the result is unchanged: the row still counts in getFailureCount() and getErrors(), and isSuccess() is still false. Call it once per status code. It has no effect in all-or-nothing mode, where any refusal fails the whole transaction. A row that also carries an error you did not declare logs at ERROR. The setting also applies after .async(). In a background job the log is the only place a refusal shows up, and the setting hides nothing there: the job logs the same refusal at WARN.

Parameters

ParameterTypeDescription
statusCodeSystem.StatusCodeThe status code of the refusal you expect, such as StatusCode.DUPLICATE_VALUE for a unique field that blocks a second copy when two processes save the same record at the same time, a clash that does no harm.

Returns DML_Builder — This builder instance for fluent chaining.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen statusCode is null.

Example

apex
DML_Builder.newTransaction()
    .doInsert(contacts)
    .allowPartial()
    .expectRefusal(StatusCode.DUPLICATE_VALUE)
    .execute();

newTransaction ​

apex
global static DML_Builder newTransaction()

Creates a new DML_Builder instance representing a DML transaction.

Returns DML_Builder — A new DML_Builder instance.

Example

apex
DML_Builder.newTransaction()
    .doInsert(account)
    .execute();

suppressExceptions ​

apex
global DML_Builder suppressExceptions()

Stops a DmlException from being thrown again in all-or-nothing mode. The failure shows on the returned TransactionResult instead of reaching the caller as an exception. The save's single ERROR entry, written in DML_Transaction.commitWork, still records it unless suppressLogging() is also set. In user mode, a save refused because the running user lacks the object permission it needs also returns a failed result instead of throwing. getFailureMessage() on the result gives the reason for the failure.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(record)
    .suppressExceptions()
    .execute();

suppressLogging ​

apex
global DML_Builder suppressLogging()

Turns off LOG_Builder error logging for DML failures. This covers the entry for each failed row of a partial save. It also covers the single ERROR entry the transaction writes when a save fails completely, or when partial mode catches an exception thrown during the save. It also turns off the warning that bypassSharing() logs in user mode when it leaves out fields the user cannot create or edit.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(records)
    .allowPartial()
    .suppressLogging()
    .execute();

withRetryOnLock ​

apex
global DML_Builder withRetryOnLock()

Tries the save again, once, when the platform refuses it because another transaction holds a record (UNABLE_TO_LOCK_ROW). This refusal is called a row lock. In all-or-nothing mode the whole save is rolled back and runs again. In partial mode only the rows refused for a lock are saved again, before the save moves on, and the rows that saved stay saved. Nothing else is retried: any other refusal is reported at once. There is no pause between attempts. The platform already waits up to about ten seconds for the lock before it refuses. So when another transaction holds the record, each attempt costs about ten seconds, and when none does, the setting costs nothing extra. The retries stop early when the DML limits left cannot cover another attempt. One WARN entry records a save that met a lock and then got through. A save still refused after its last attempt carries the same details on its ERROR entry. suppressLogging() turns off both. The setting also applies after .async(), where every batch applies it within its own limits. A retry cannot undo two things. Platform events published immediately during a rolled-back attempt are published again. And static values a failed attempt set, such as a trigger's own "already ran" flag, are not reset.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(records)
    .withRetryOnLock()
    .execute();
apex
global DML_Builder withRetryOnLock(Integer retries)

Tries the save again up to the given number of times when the platform refuses it because another transaction holds a record (UNABLE_TO_LOCK_ROW). The count is the extra attempts after the first, from 1 to 5. Each attempt can wait about ten seconds when the record is held. A request that runs longer than five seconds in the user's own transaction counts toward the org's limit on long-running requests at the same time. So code that a user waits on should keep the default, and larger counts belong in asynchronous work. Everything else is as withRetryOnLock() describes.

Parameters

ParameterTypeDescription
retriesIntegerExtra attempts after the first, 1 to 5.

Returns DML_Builder — This builder instance for fluent chaining.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen retries is null or outside 1 to 5.

Example

apex
DML_Builder.newTransaction()
    .doUpdate(records)
    .withRetryOnLock(3)
    .async()
    .execute();

withSystemMode ​

apex
global DML_Builder withSystemMode()

Forces AccessLevel.SYSTEM_MODE on every DML operation in this transaction. Use it when code must write objects that the running user is not meant to have object or field access (CRUD/FLS) to, such as logs, records that track background work, or other objects the framework owns. When the save runs, the framework's bypass audit records it: log entries, one for each kind of record saved, that say this save skipped object and field permissions.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(logEntryEvent)
    .withSystemMode()
    .execute();

withUserMode ​

apex
global DML_Builder withUserMode()

Forces AccessLevel.USER_MODE on every DML operation in this transaction, whatever the UserModeDml_Enabled feature flag says. Use it when a flow that serves your users must check object and field access (CRUD/FLS), even in orgs where an admin has turned the flag off. With bypassSharing(), the save ignores record sharing but still checks the object and field permissions.

Returns DML_Builder — This builder instance for fluent chaining.

Example

apex
DML_Builder.newTransaction()
    .doInsert(accountFromUserInput)
    .withUserMode()
    .execute();

Inner Classes ​

ClassDescription
DatabaseOperationEnum to specify the type of DML operation for external use.
DML_AsyncBuilderRuns DML in an async job.
TransactionResultResult object returned by execute() containing the outcome of all DML operations in the transaction.