Apex Developer Guide

Apex Developer Guide
Release Notes
Getting Started with Apex
Writing Apex
Data Types and Variables
Control Flow Statements
Classes, Objects, and Interfaces
Working with Data in Apex
Working with sObjects
Data Manipulation Language
How DML Works
Adding and Retrieving Data With DML
DML Statements vs. Database Class Methods
DML Operations As Atomic Transactions
DML Operations
Inserting and Updating Records
Upserting Records
Merging Records
Deleting Records
Restoring Deleted Records
Converting Leads
Exception Handling
More About DML
Locking Records
SOQL and SOSL Queries
SOQL For Loops
sObject Collections
Dynamic Apex
Apex Security and Sharing
Custom Settings
Running Apex
Debugging, Testing, and Deploying Apex
Apex Reference
Appendices
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Upserting Records

Using the upsert operation, you can either insert or update an existing record in one call. To determine whether a record already exists, the upsert statement or Database method uses the record’s ID as the key to match records, a custom external ID field, or a standard field with the idLookup attribute set to true.
  • If the key isn’t matched, then a new object record is created.
  • If the key is matched once, then the existing object record is updated.
  • If the key is matched multiple times, then an error is generated and the object record is not inserted or updated.

Custom field matching is case-insensitive only if the custom field has the Unique and Treat "ABC" and "abc" as duplicate values (case insensitive) attributes selected as part of the field definition. If this is the case, “ABC123” is matched with “abc123.” For more information, see Create Custom Fields.

Note

Examples

The following example updates the city name for all existing accounts in the city formerly known as Bombay, and also inserts a new account in San Francisco:

For more information on processing DmlExceptions, see Bulk DML Exception Handling.

Note

This next example uses the Database.upsert method to upsert a collection of leads that are passed in. This example allows for partial processing of records, that is, in case some records fail processing, the remaining records are still inserted or updated. It iterates through the results and adds a task to each record that was processed successfully. The task sObjects are saved in a list, which is then bulk inserted. This example is followed by a test class that contains a test method for testing the example.

Use of upsert with an external ID can reduce the number of DML statements in your code, and help you to avoid hitting governor limits (see Execution Governors and Limits).

This example uses upsert and an external ID field Line_Item_Id__c on the Asset object to maintain a one-to-one relationship between an asset and an opportunity line item. Before running the sample, create a custom text field on the Asset object named Line_Item_Id__c and mark it as an external ID. For information on custom fields, see Salesforce Help.

External ID fields used in upsert calls must be unique or the user must have the View All Data permission.

Note