Use Data Manipulation Language (DML) statements to insert, update, merge, delete, and restore data in Salesforce.
The following Apex DML statements are available:
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.
insert sObject[]
Account newAcct = new Account(name = 'Acme'); try { insert newAcct; } catch (DmlException e) { // Process exception here }
The update DML operation modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements, in your organization’s data. update is analogous to the UPDATE statement in SQL.
update sObject[]
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 }
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.
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 maching doesn’t have the Unique attribute set, the context user must have the “View All” object-level permission for the target object or the “View All Data” permission so that upsert does not accidentally insert a duplicate record.
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) { }
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.
delete sObject[]
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 }
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.
undelete sObject[] | ID[]
Account[] savedAccts = [SELECT Id, Name FROM Account WHERE Name = 'Universal Containers' ALL ROWS]; try { undelete savedAccts; } catch (DmlException e) { // Process exception here }
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.
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.
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 }