Skip to content

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 ​

  1. Run bypasses. TriggerOrchestrator.bypass() (all(), sObject(…), orchestrator(…)) or a checked TriggerObject__mdt.Bypass__c ends the run before any of your code. So does an orchestrator that does not implement the context.
  2. Handler list. <ctx>Handlers() runs. Under runFromMetadata(), the library instead creates the class of every unbypassed TriggerHandler__mdt record whose field for the context names the object, in Order__c order. A class without the context's Handler interface throws. A class that implements two roles runs only as the first: Populator over Validator, Validator over Writer, Writer over Dispatcher.
  3. Handler bypasses. bypass().handler(…), then TriggerHandler__mdt.Bypass__c for this context, then bypassOn<Ctx>When(). A skipped handler declares no parents. When no handler is left, the run ends here, and only the Logger step follows.
  4. Parent declarations. The remaining handlers declare their parents. A lookup is queried the first time a handler reads its parent.
  5. 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.
  6. Shared commit. In before delete and the after contexts, the shared unit of work commits once.
  7. Logger. The outermost run calls flush() on the org's Logger. After a maximum trigger depth exceeded failure, no later run in the transaction does.

Query Cost ​

SOQL queries a run spends outside your code:

SourceSOQL queries
Bypass and registration metadata0, once per transaction
Logger discovery1, once per transaction
Parents in before contexts and after delete1 per lookup read
Parents in after insert, update and undelete1 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 Populator1 per lookup already read and re-pointed to a parent not loaded yet
RelatedQuery providerswhat 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".