SfSkills Domains Docs GitHub

Home / apex / batch-apex-patterns

batch-apex-patterns

Use when designing, reviewing, or debugging Batch Apex contracts, scope sizing, stateful behavior, chaining, and AsyncApexJob monitoring. Triggers: 'Database.Batchable', 'Database.Stateful', 'executeBatch', 'batch scope', 'AsyncApexJob'. NOT for choosing Batch vs Queueable vs Future — use apex/async-apex. NOT for running one batch after another — use apex/apex-batch-chaining.

Open the skill folder on GitHub

Use this skill when Queueable is no longer enough and the workload genuinely needs chunked processing across many transactions. Batch Apex is powerful because each execute() scope receives fresh limits, but that same power introduces lifecycle, state, chaining, and monitoring choices that teams routinely under-design.

Before Starting

Core Concepts

start, execute, And finish Are Separate Responsibilities

start defines the workload, execute processes each scope, and finish handles summary or follow-up actions. Treating them as one blurred method creates monitoring and retry pain. Keep start lightweight, execute idempotent, and finish focused on reporting or safe handoff.

Scope Size Is A Throughput Tradeoff

The default batch size is commonly 200, but that is not always optimal. Large scopes can increase throughput for simple DML work. Smaller scopes may be safer for heavy processing or callouts. Scope sizing is a performance choice tied to payload weight, lock contention, and external system tolerance.

Database.Stateful Is Useful But Not Free

Stateful batch classes retain instance state between execute() calls. That is useful for counters, failed IDs, and summary metrics, but it also means more serialization overhead. Use it when the accumulated state changes the outcome or the reporting story, not by default.

AsyncApexJob Is Part Of The Pattern

Operationally, a batch job is not complete just because Database.executeBatch() returned an ID. Job status, processed counts, and error counts live in AsyncApexJob, and serious batch designs account for that from the start.

Governor Limits Are The Real Constraint At Large Data Volumes

For a large-data-volume design, the hard platform ceilings dictate the shape of the solution far more than code style does. Know these before you commit to an approach:

The practical decision this drives: choose Iterable over QueryLocator once the addressable set exceeds 50 million records, and choose scope size with the 24-hour execution ceiling in mind, not just per-scope throughput.

Common Patterns

QueryLocator Batch For Large Record Sets

When to use: Salesforce data volume is large and query-driven.

How it works: Use Database.getQueryLocator() in start(), process a scope at a time in execute(), and monitor the resulting job.

Why not the alternative: Direct list loading in one transaction defeats the point of Batch Apex.

Stateful Error Accumulation

When to use: The team needs final counts, failed IDs, or summary reporting after all scopes finish.

How it works: Add Database.Stateful and store lightweight counters or IDs only.

Dispatch Follow-Up Work In finish()

When to use: Another batch, Queueable, or notification should happen only after the batch completes.

How it works: Query AsyncApexJob or accumulated counters in finish(), then launch the next safe step.

Decision Guidance

SituationRecommended ApproachReason
Very large Salesforce record set must be processed safelyQueryLocator BatchFresh limits per scope and large-volume support
Addressable record set exceeds 50 millionIterable in start()QueryLocator caps at 50M records; Iterable is not subject to that cap
Many batches need to run near-simultaneouslySerialize or schedule themOnly 5 batch jobs may be queued or active at once (flex queue holds 100 more)
Need only simple after-save async work for a modest set of recordsNot Batch; prefer QueueableLower framework overhead
Need summary counters across all scopesDatabase.StatefulKeeps lightweight cross-scope state
Need post-completion reporting or next-stage dispatchfinish() + AsyncApexJob dataClear completion boundary

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm the org edition, relevant objects, and current configuration state
  2. Review official sources — check the references in this skill's well-architected.md before making changes
  3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
  4. Validate — run the skill's checker script and verify against the Review Checklist below
  5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Salesforce-Specific Gotchas

  1. Each execute() scope gets fresh limits, but Database.Stateful still carries serialization cost — do not store large collections casually.
  2. Callout-enabled batches still need Database.AllowsCallouts — forgetting it breaks valid designs.
  3. A batch job ID is not observability by itself — you still need job status and error interpretation.
  4. Tests need Test.stopTest() for batch completion — otherwise assertions can run before the batch executes.
  5. Database.QueryLocator caps at 50 million records — a set larger than that must use an Iterable in start(), which then falls back under normal per-transaction SOQL limits.
  6. Only 5 batch jobs can be queued or active at once — additional submissions hold in the Apex flex queue (up to 100), so fan-out designs must serialize or schedule rather than fire everything immediately.

Output Artifacts

ArtifactDescription
Batch design reviewFindings on lifecycle, state, scope size, and monitoring
Batch decision guideRecommendation for when Batch is justified and how to size and monitor it
Batch scaffoldPattern for start, execute, finish, optional state, and summary behavior

Package files