Force.com Apex Code Developer's Guide
j
No Results
Search Tips:
- Please consider misspellings
- Try different search keywords
Newer Version Available
Apex DML Operations
You can perform DML operations using the Apex DML statements or the methods of the Database class.
For lead conversion, use the convertLead method of the Database class. There is no DML counterpart for it.
To learn more about data in Apex, see Working with Data in Apex.
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
1Account newAcct = new Account(name = 'Acme');
2try {
3 insert newAcct;
4} catch (DmlException e) {
5// Process exception here
6}Update Statement
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.
Syntax
update sObject[]
Example
1Account a = new Account(Name='Acme2');
2insert(a);
3
4Account myAcct = [SELECT Id, Name, BillingCity FROM Account WHERE Id = :a.Id];
5myAcct.BillingCity = 'San Francisco';
6
7try {
8 update myAcct;
9} catch (DmlException e) {
10 // Process exception here
11}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_external_id
opt_external_id is an optional variable that specifies the custom field that should be used to match records that already exist in your organization's data. This custom field must be created with the External Id attribute selected. Additionally, if the field does not have the Unique attribute selected, 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.
If opt_external_id is not specified, the sObject record's ID field is used by default.
How Upsert Chooses to Insert or Update
- If the key is not 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 is neither inserted or updated.
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 and Force.com.
Example
This example performs an upsert of a list of accounts.
1List<Account> acctList = new List<Account>();
2// Fill the accounts list with some accounts
3
4try {
5 upsert acctList;
6} catch (DmlException e) {
7
8}This next example performs an upsert of a list of accounts using a foreign key for matching existing records, if any.
1List<Account> acctList = new List<Account>();
2// Fill the accounts list with some accounts
3
4try {
5 // Upsert using an external ID field
6 upsert acctList myExtIDField__c;
7} catch (DmlException e) {
8
9}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[] | ID[]
Example
The following example deletes all accounts that are named 'DotCom':
1Account[] doomedAccts = [SELECT Id, Name FROM Account
2 WHERE Name = 'DotCom'];
3try {
4 delete doomedAccts;
5} catch (DmlException e) {
6 // Process exception here
7}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
1Account[] savedAccts = [SELECT Id, Name FROM Account WHERE Name = 'Trump' ALL ROWS];
2try {
3 undelete savedAccts;
4} catch (DmlException e) {
5 // Process exception here
6}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:
1List<Account> ls = new List<Account>{new Account(name='Acme Inc.'),new Account(name='Acme')};
2insert ls;
3Account masterAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme Inc.' LIMIT 1];
4Account mergeAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
5try {
6 merge masterAcct mergeAcct;
7} catch (DmlException e) {
8 // Process exception here
9}