---
url: https://trigger.beyondthecloud.dev/guide/execution-order.md
description: >-
  The order in which Trigger Lib runs bypasses, handlers, parent queries,
  providers, Finalizers and unit-of-work commits, and what one run costs in SOQL
  queries and DML statements.
---

# Execution Order & Cost

## One Run per Chunk {#run}

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 {#order}

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](/guide/unit-of-work#which-unit) 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 {#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 {#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 {#nested}

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](/after-update/add-ons/recursion-guard) sets its own depth and also skips the record there.
* **Salesforce allows 16 levels.** The next one fails with "maximum trigger depth exceeded".
