Apex Reference Guide
j
No Results
Search Tips:
- Please consider misspellings
- Try different search keywords
Apex DML Operations
Apex DML Statements
Use Data Manipulation Language (DML) statements to insert, update, merge, delete, and restore data in Salesforce.
The following Apex DML statements are available:
Insert Statement
The insert DML operation adds one or more sObjects, such as individual accounts or contacts, to your organization’s data. insert is analogous to the INSERT statement in SQL.
Syntax
insert sObject[]
Example
Account newAcct = new Account(name = 'Acme');
try {
insert newAcct;
} catch (DmlException e) {
// Process exception here
}Update Statement
The update DML operation modifies one or more existing sObject records, such as individual accounts or contacts, in your organization’s data. update is analogous to the UPDATE statement in SQL.
Syntax
update sObject[]
Example
Account a = new Account(Name='Acme2');
insert(a);
Account myAcct = [SELECT Id, Name, BillingCity FROM Account WHERE Id = :a.Id];
myAcct.BillingCity = 'San Francisco';
try {
update myAcct;
} catch (DmlException e) {
// Process exception here
}Upsert Statement
The upsert DML operation creates new records and updates sObject records within a single statement, using a specified field to determine the presence of existing objects, or the ID field if no field is specified.
Syntax
upsert sObject[] [opt_field]
The upsert statement matches the sObjects with existing records by comparing values of one field. If you don’t specify a field when calling this statement, the upsert statement uses the sObject’s ID to match the sObject with existing records in Salesforce. Alternatively, you can specify a field to use for matching. For custom objects, specify a custom field marked as external ID. For standard objects, you can specify any field that has the idLookup attribute set to true. For example, the Email field of Contact or User has the idLookup attribute set. To check a field’s attribute, see the Object Reference for Salesforce.
Also, you can use foreign keys to upsert sObject records if they have been set as reference fields. For more information, see Field Types in the Object Reference for Salesforce.
upsert sObjectList Account.Fields.MyExternalId__c;If the field used for matching doesn’t have the Unique attribute set, the context user must have the “View All Records” object-level permission for the target object or the “View All Data” permission so that upsert doesn’t accidentally insert a duplicate record.
How Upsert Chooses to Insert or Update
- If the key isn’t matched, a new object record is created.
- If the key is matched once, the existing object record is updated.
- If the key is matched multiple times, an error is generated and the object record isn’t inserted or updated.
Example
This example performs an upsert of a list of accounts.
List<Account> acctList = new List<Account>();
// Fill the accounts list with some accounts
try {
upsert acctList;
} catch (DmlException e) {
}This next example performs an upsert of a list of accounts using a foreign key for matching existing records, if any.
List<Account> acctList = new List<Account>();
// Fill the accounts list with some accounts
try {
// Upsert using an external ID field
upsert acctList myExtIDField__c;
} catch (DmlException e) {
}Delete Statement
The delete DML operation deletes one or more existing sObject records, such as individual accounts or contacts, from your organization’s data. delete is analogous to the delete() statement in the SOAP API.
Syntax
delete sObject[]
Example
The following example deletes all accounts that are named 'DotCom':
Account[] doomedAccts = [SELECT Id, Name FROM Account
WHERE Name = 'DotCom'];
try {
delete doomedAccts;
} catch (DmlException e) {
// Process exception here
}Undelete Statement
The undelete DML operation restores one or more existing sObject records, such as individual accounts or contacts, from your organization’s Recycle Bin. undelete is analogous to the UNDELETE statement in SQL.
Syntax
undelete sObject[] | ID[]
Example
Account[] savedAccts = [SELECT Id, Name FROM Account WHERE Name = 'Universal Containers' ALL ROWS];
try {
undelete savedAccts;
} catch (DmlException e) {
// Process exception here
}Merge Statement
The merge statement merges up to three records of the same sObject type into one of the records, deleting the others, and re-parenting any related records.
Syntax
merge sObject sObject[]
merge sObject ID
merge sObject ID[]
The first parameter represents the master record into which the other records are to be merged. The second parameter represents the one or two other records that should be merged and then deleted. You can pass these other records into the merge statement as a single sObject record or ID, or as a list of two sObject records or IDs.
Example
The following example merges two accounts named 'Acme Inc.' and 'Acme' into a single record:
List<Account> ls = new List<Account>{new Account(name='Acme Inc.'),new Account(name='Acme')};
insert ls;
Account masterAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme Inc.' LIMIT 1];
Account mergeAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
try {
merge masterAcct mergeAcct;
} catch (DmlException e) {
// Process exception here
}