Intermediate 20 min read

Insert

By the end of this lesson, you'll be able to:

  • Insert a single record and a list of records
  • Read the auto-populated Id after an insert succeeds
  • Handle a validation failure using try/catch

Prerequisites: "What Is DML?"

Inserting a single record

Account acc = new Account(Name = 'Riverbend Farms');
insert acc;

System.debug(acc.Id); // now populated — e.g. 001XX000003DHP0YAO
  1. Account acc = new Account(Name = 'Riverbend Farms'); — before insert, acc.Id is null.
  2. insert acc; — assigns the Id automatically the instant the insert succeeds.
  3. (blank line)
  4. System.debug(acc.Id); — now populated — this is exactly the 18-character Id format from Module 18.

Inserting a List at once

List<Account> newAccounts = new List<Account>{
    new Account(Name = 'Riverbend Farms'),
    new Account(Name = 'Northwind Traders')
};

insert newAccounts;

for (Account acc : newAccounts) {
    System.debug(acc.Id);
}
  1. List<Account> newAccounts = new List<Account>{ — a list of records to create.
  2. new Account(Name = 'Riverbend Farms'), — the first, not yet saved.
  3. new Account(Name = 'Northwind Traders') — the second, not yet saved.
  4. }; — closes the list literal.
  5. (blank line)
  6. insert newAccounts; — a single DML statement covering every record in the list — this is exactly the bulkification instinct from Module 7's "Loops and Governor Limits" lesson.
  7. (blank line)
  8. for (Account acc : newAccounts) { — loops over the now-saved records.
  9. System.debug(acc.Id); — each one now has a real, permanent Id.
  10. } — closes the loop.

Handling a validation failure

try {
    Account acc = new Account(); // no Name — Name is required on Account
    insert acc;
} catch (DmlException e) {
    System.debug('Insert failed: ' + e.getMessage());
}
  1. try { — wraps the risky insert.
  2. Account acc = new Account(); — no Name — Name is required on Account.
  3. insert acc; — a record that violates a required-field or validation rule throws a DmlException here.
  4. } catch (DmlException e) { — exactly Module 13's try/catch pattern, now catching a database-level failure instead of a runtime language error.
  5. System.debug('Insert failed: ' + e.getMessage()); — handles it instead of crashing.
  6. } — closes the catch.

Exercise

Build a List<Account> with two new Accounts (Name only), insert them, and debug each one's Id after the insert.

Show hint

insert the whole List at once.

Salesforce: ○ Not connected Connect
APEX

Execution Results

Run your code to see the result.

Insert Quiz

1. When is an sObject's Id field populated?

Log in to submit the quiz and save your score.

My Notes

Log in to keep private notes on this lesson.

Questions about this lesson

No questions yet — be the first to ask.

Log in to ask a question about this lesson.

Summary

insert creates one or more brand-new records — a single sObject or a whole List at once — and Salesforce assigns each one a real, permanent Id the moment it succeeds.