Insert Operation

DML Statement Syntax

insert sObject

insert sObject[]

Database Method Syntax

SaveResult Database.insert(sObject recordToInsert, Boolean opt_allOrNone | database.DMLOptions opt_DMLOptions)
SaveResult[] Database.insert(sObject[] recordsToInsert, Boolean opt_allOrNone | database.DMLOptions opt_DMLOptions)

The optional opt_allOrNoneparameter specifies whether the operation allows partial success. If you specify false for this parameter and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to verify which records succeeded, which failed, and why.

For example:

Database.SaveResult[] MySaveResult = Database.Insert(MyAccounts, false);

The optional opt_DMLOptions parameter specifies additional data for the transaction, such as assignment rule information or rollback behavior when errors occur during record insertions.

For example:

//AssignmentRuleHeader 
    
//UseDefaultRule 
    
Database.DMLOptions dmo = new database.DMLOptions();
dmo.AssignmentRuleHeader.UseDefaultRule= true;

Lead l = new Lead(Company='ABC', LastName='Smith');
l.setOptions(dmo);

insert l;

For more information, see Database DMLOptions Properties.

Rules and Guidelines

When inserting sObject records, consider the following rules and guidelines:

Certain sObjects cannot be created. To create an sObject record, the createable property of the sObject must be set to true.
You must supply a non-null value for all required fields.
You can pass a maximum of 10,000 sObject records to a single insert method.
The insert statement automatically sets the ID value of all new sObject records. Inserting a record that already has an ID—and therefore already exists in your organization's data—produces an error. See Lists for information.
The insert statement can only set the foreign key ID of related sObject records. Fields on related records cannot be updated with insert. For example, if inserting a new contact, you can specify the contact's related account record by setting the value of the AccountId field. However, you cannot change the account's name without updating the account itself with a separate DML call.
The insert statement is not supported with some sObjects. See sObjects That Do Not Support DML Operations.
This operation checks each batch of records for duplicate ID values. If there are duplicates, the first five are processed. For the sixth and all additional duplicate IDs, the SaveResult for those entries is marked with an error similar to the following: Maximum number of duplicate updates in one batch (5 allowed). Attempt to update Id more than once in this API call: number_of_attempts.

SaveResult Object

An array of SaveResult objects is returned with the insert and update database methods. Each element in the SaveResult array corresponds to the sObject array passed as the sObject[] parameter in the database method, that is, the first element in the SaveResult array matches the first element passed in the sObject array, the second element corresponds with the second element, and so on. If only one sObject is passed in, the SaveResults array contains a single element.

A SaveResult object has the following methods:

Name	Type	Description
`getErrors`	Database.Error []	If an error occurred, an array of one or more database error objects providing the error code and description. For more information, see Database Error Object Methods.
`getId`	ID	The ID of the sObject you were trying to insert or update. If this field contains a value, the object was successfully inserted or updated. If this field is empty, the operation was not successful for that object.
`isSuccess`	Boolean	A Boolean that is set to true if the DML operation was successful for this object, false otherwise.

DML Statement Example

The following example inserts an account named 'Acme':

Account newAcct = new Account(name = 'Acme');
try {
   insert newAcct;
} catch (DmlException e) {
// Process exception here 
    
}

Note

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

Database Method Example

The following example inserts an account named 'Acme':

Account a = new Account(name = 'Acme');
Database.SaveResult[] lsr = Database.insert(new Account[]{a, new Account(Name = 'Acme')},
false);

// Iterate through the Save Results 
    
for(Database.SaveResult sr:lsr){
   if(!sr.isSuccess())
      Database.Error err = sr.getErrors()[0];
}