Execution Order & Cost
One Run per Chunk
The platform fires a trigger once per context for each chunk of records, up to 200 in insert and update. Each firing is one run. An insert of 201 records makes four runs: before insert and after insert for the first 200 records, then both again for the last one.
Each run calls <ctx>Handlers(), loads parents, runs providers and commits again. Handlers created in <ctx>Handlers() start with empty instance fields. Static fields, bypasses set with TriggerOrchestrator.bypass() and recursion counts last the whole transaction.
Order of a Run
- Run bypasses.
TriggerOrchestrator.bypass()(all(),sObject(…),orchestrator(…)) or a checkedTriggerObject__mdt.Bypass__cends the run before any of your code. So does an orchestrator that does not implement the context. - Handler list.
<ctx>Handlers()runs. UnderrunFromMetadata(), the library instead creates the class of every unbypassedTriggerHandler__mdtrecord whose field for the context names the object, inOrder__corder. A class without the context'sHandlerinterface throws. A class that implements two roles runs only as the first: Populator over Validator, Validator over Writer, Writer over Dispatcher. - Handler bypasses.
bypass().handler(…), thenTriggerHandler__mdt.Bypass__cfor this context, thenbypassOn<Ctx>When(). A skipped handler declares no parents. When no handler is left, the run ends here, and only the Logger step follows. - Parent declarations. The remaining handlers declare their parents. A lookup is queried the first time a handler reads its parent.
- Each handler runs, in list order.
- Each RelatedQuery provider runs over all records the first time the handler reads it.
- Per record, the predicate decides and the action runs. A Dispatcher collects the records and dispatches once.
- The Finalizer runs when at least one record qualified.
- A Writer with OwnUnitOfWork or ContinueOnError commits its own unit of work.
- Shared commit. In before delete and the after contexts, the shared unit of work commits once.
- Logger. The outermost run calls
flush()on the org's Logger. After amaximum trigger depth exceededfailure, no later run in the transaction does.
Query Cost
SOQL queries a run spends outside your code:
| Source | SOQL queries |
|---|---|
| Bypass and registration metadata | 0, once per transaction |
| Logger discovery | 1, once per transaction |
| Parents in before contexts and after delete | 1 per lookup read |
| Parents in after insert, update and undelete | 1 on the trigger object at the first ParentQuery read, plus 1 per lookup read that it missed and, in after update, per PriorParentQuery lookup read |
| Parents after a Populator | 1 per lookup already read and re-pointed to a parent not loaded yet |
| RelatedQuery providers | what each query runs, per handler that reads it |
- Declarations merge. Handlers that declare the same lookup share one query.
- Parents load on the first read. A declared lookup whose parent no handler reads costs no query.
- Providers run on the first read. A provider its handler never reads costs no query. A read in a predicate runs it even when no record qualifies.
- Never query in a predicate or an action. They run once per record, so a query there throws. Declare a ParentQuery or a RelatedQuery, or query once in a Finalizer. The parents and providers the library loads for them do not count.
DML Cost
- Before insert and before update: none. DML or an event publish throws.
- Shared unit of work: one commit per run. It costs one statement per operation and object type. An empty unit costs nothing.
- A Writer with OwnUnitOfWork or ContinueOnError: one more commit per run, when a record qualified.
- Direct DML in a Dispatcher's dispatch method or a Finalizer costs what it runs. In a predicate or an action it throws.
- Events: a Publish After Commit event counts as a DML statement. A Publish Immediately event counts toward
Limits.getPublishImmediateDML().
Nested Runs
A commit or direct DML fires the triggers of the saved records at once. Each is a full nested run with its own parents, providers and commit.
- Recursion counts are shared. In the update contexts, when a record comes back to a Populator, Writer or Dispatcher that already acted on it 3 times in the transaction, the run logs an error and the handler keeps running. A RecursionGuard sets its own depth and also skips the record there.
- Salesforce allows 16 levels. The next one fails with "maximum trigger depth exceeded".
