Every Salesforce team hits the same wall eventually. A business stakeholder walks over and says: “We need to update the Region__c field on 2.3 million Account records based on a new territory model.” Someone opens Data Loader, exports a CSV, runs a VLOOKUP in Excel, and re-imports. It takes a full afternoon. Two weeks later, the territory model changes again.
There’s a better way. Batch Apex lets you encode the logic of that update - not just the data - so it’s repeatable, testable, auditable, and parameterized for the next time it happens. This article covers how to design batch classes that are genuinely reusable across backfill scenarios, the trade-offs you need to understand before choosing this approach, and how to monitor jobs once they’re running.
The Anatomy of a Batch Class (Quick Refresher)
If you’ve written Batch Apex before, skim this section. If not, here’s the contract you’re implementing:
public class AccountRegionBackfill implements Database.Batchable {
public class AccountRegionBackfill implements Database.Batchable {
// 1. QUERY – what records are we operating on?
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(
‘SELECT Id, BillingState FROM Account WHERE Region_c = null’
);
}
// 2. PROCESS – what do we do to each chunk?
public void execute(Database.BatchableContext bc, List scope) {
for (Account acc : scope) {
acc.Region_c = TerritoryUtil.deriveRegion(acc.BillingState);
}
update scope;
}
// 3. CLEANUP – what happens when we’re done?
public void finish(Database.BatchableContext bc) {
AsyncApexJob job = [
SELECT TotalJobItems, JobItemsProcessed, NumberOfErrors
FROM AsyncApexJob WHERE Id = :bc.getJobId()
];
System.debug(‘Completed: ‘ + job.JobItemsProcessed + ‘/’ +
job.TotalJobItems + ‘ batches, ‘ +
job.NumberOfErrors + ‘ errors’);
}
}
You invoke it from Anonymous Apex, a trigger, or a scheduled class:
Database.executeBatch(new AccountRegionBackfill(), 200);
The 200 is the batch size - the number of records passed to each execute call. Salesforce then breaks your query result into chunks, runs execute for each chunk in its own transaction with fresh governor limits, and calls finish once everything’s done.
That’s the textbook version. Let’s talk about what the textbook leaves out.
Why Batch Apex Beats Data Loader for Backfills
Data Loader is a fine tool for one-off imports. But for data updates that involve logic, it introduces problems that compound over time.
Data Loader requires you to externalize your logic. If the update rule is “set Region__c based on BillingState, but only for Accounts created after 2020 that aren’t owned by the integration user,” you have to express that in an Excel formula, a Python script, or your own head. None of those live in your Salesforce org. None of them are version-controlled by default. None of them fire when requirements change.
Batch Apex keeps the logic where the data is. The derivation logic, the filter criteria, and the error handling all live in the same class, deployed through the same CI pipeline as the rest of your code. When the territory model changes, you update one class - you don’t re-export 2.3 million records and pray the VLOOKUP columns still line up.
Here’s a practical comparison for the scenarios that matter most:
Runtime business logic. Data Loader can’t call an Apex utility method, execute a formula at write-time, or make an API callout to an external mapping service mid-update. Batch Apex can. If your backfill rule is “call the Geocoding API for every Account missing coordinates,” Data Loader simply can’t do it.
Trigger and flow execution. Data Loader updates fire triggers and flows, which is sometimes what you want and sometimes catastrophic. With Batch Apex, you can structure your DML to use Database.update(scope, false) for partial success, and you can add conditional logic to skip trigger paths when appropriate using a static bypass flag.
Repeatability. When a PM says “run it again but only for EMEA,” you change one parameter. With Data Loader, you re-export, re-filter, re-import.
Auditability. Every Batch Apex execution creates an AsyncApexJob record with start time, end time, error count, and the submitting user. Data Loader logs live on whoever’s laptop ran it.
There are scenarios where Data Loader is the right call: simple one-time imports of static CSVs, sandbox data seeding, or situations where a non-developer needs to do a quick update. But if you’re doing the same type of update more than twice, Batch Apex pays for itself.
Parameterizing for Reuse
The mistake most teams make is building one batch class per backfill task. You end up with AccountRegionBackfill, AccountIndustryBackfill, ContactEmailNormalizeBatch, and thirty other classes that all follow the same pattern: query records matching a filter, apply a transformation, update.
Instead, build one parameterized class that accepts its configuration at construction time.
Pattern 1: Constructor-Injected Parameters
The simplest approach. Pass the query and the field-value map into the constructor:
public class GenericFieldUpdateBatch implements Database.Batchable {
private String query;
private Map fieldValues;
private Boolean allOrNone;
public GenericFieldUpdateBatch(String query, Map fieldValues) {
this(query, fieldValues, false);
}
public GenericFieldUpdateBatch(
String query,
Map fieldValues,
Boolean allOrNone
) {
this.query = query;
this.fieldValues = fieldValues;
this.allOrNone = allOrNone;
}
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(query);
}
public void execute(Database.BatchableContext bc, List scope) {
for (SObject record : scope) {
for (String field : fieldValues.keySet()) {
record.put(field, fieldValues.get(field));
}
}
Database.update(scope, allOrNone);
}
public void finish(Database.BatchableContext bc) {
// Send notification, chain next batch, etc.
}
}
Invocation becomes declarative:
// Backfill Region for all null-region Accounts in California
Database.executeBatch(
new GenericFieldUpdateBatch(
‘SELECT Id FROM Account WHERE Region_c = null AND BillingState = ‘CA”,
new Map{ ‘Regionc’ => ‘West’ }
),
200
);
// Normalize a status field on Opportunities
Database.executeBatch(
new GenericFieldUpdateBatch(
‘SELECT Id FROM Opportunity WHERE StageName = ‘Closed/Won”,
new Map{ ‘StageName’ => ‘Closed Won’ }
),
200
);
This single class replaces dozens of one-off batch classes for simple field-value updates.
Pattern 2: Strategy Interface for Complex Logic
When the transformation isn’t a static value but requires computation, inject a strategy:
public interface IBatchTransform {
void apply(List records);
}
public class TransformableBatch implements Database.Batchable {
private String query;
private IBatchTransform transformer;
public TransformableBatch(String query, IBatchTransform transformer) {
this.query = query;
this.transformer = transformer;
}
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(query);
}
public void execute(Database.BatchableContext bc, List scope) {
transformer.apply(scope);
Database.update(scope, false);
}
public void finish(Database.BatchableContext bc) { }
}
Now a territory-mapping backfill looks like this:
public class TerritoryTransform implements IBatchTransform {
public void apply(List records) {
for (SObject rec : records) {
Account acc = (Account) rec;
acc.Regionc = TerritoryUtil.deriveRegion(acc.BillingState);
}
}
}
// Run it
Database.executeBatch(
new TransformableBatch(
‘SELECT Id, BillingState FROM Account WHERE Regionc = null’,
new TerritoryTransform()
),
200
);
The batch infrastructure and the business logic are fully separated. You can unit-test TerritoryTransform without ever invoking the batch framework.
Pattern 3: Custom Metadata–Driven Configuration
For teams that want admins (not just developers) to control batch behavior, store your parameters in Custom Metadata:
Batch_Job_Configmdt
├── DeveloperName: Account_Region_Backfill
├── SOQL_Queryc: SELECT Id, BillingState FROM Account WHERE Regionc = null
├── Batch_Sizec: 200
├── Activec: true
└── Notification_Email_c: [email protected]
Your batch class reads from this at runtime. Combined with a Scheduled Apex wrapper, you can toggle jobs on and off without a deployment.
Managing State and Error Handling
Tracking Errors Across Batches
By default, Batch Apex is stateless - instance variables reset between execute calls. If you need to accumulate errors or counts across the entire job, implement Database.Stateful:
public class AccountBackfillWithTracking
implements Database.Batchable, Database.Stateful {
private Integer successCount = 0;
private Integer errorCount = 0;
private List errorMessages = new List();
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(
‘SELECT Id, BillingState FROM Account WHERE Region_c = null’
);
}
public void execute(Database.BatchableContext bc, List scope) {
for (Account acc : scope) {
acc.Region_c = TerritoryUtil.deriveRegion(acc.BillingState);
}
List results = Database.update(scope, false);
for (Integer i = 0; i < results.size(); i++) {
if (results[i].isSuccess()) {
successCount++;
} else {
errorCount++;
for (Database.Error err : results[i].getErrors()) {
errorMessages.add(
scope[i].Id + ‘: ‘ + err.getMessage()
);
}
}
}
}
public void finish(Database.BatchableContext bc) {
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
mail.setToAddresses(new List{ ‘[email protected]‘ });
mail.setSubject(‘Backfill Complete: ‘ + successCount + ‘ updated, ‘
+ errorCount + ‘ errors’);
mail.setPlainTextBody(
errorMessages.isEmpty()
? ‘All records updated successfully.’
: ‘Errors:n’ + String.join(errorMessages, ‘n’)
);
Messaging.sendEmail(new List{ mail });
}
}
The trade-off with Database.Stateful: Salesforce serializes and deserializes your instance variables between every batch execution. If you’re accumulating a list of 50,000 error messages, you’ll hit heap limits. Keep your state lean - store counts and a capped list of errors, not the full record set.
Partial Success with Database.update(records, false)
This is critical for backfills. The false parameter means “don’t roll back the whole batch if one record fails.” Without it, a single validation rule failure on record #47 kills the entire chunk of 200 records. With it, 199 succeed and you log the one failure.
Always use allOrNone = false for backfills unless you have a specific reason to require atomicity within a chunk.
Batch Size: The Trade-Off Nobody Explains Well
The batch size parameter (the second argument to Database.executeBatch) controls how many records land in each execute call. The default is 200. The maximum is 2,000.
Here’s the decision framework:
Smaller batches (50–100) when your execute method does heavy work per record - callouts, complex cross-object queries, CPU-intensive calculations. Each execute gets its own governor limits (100 SOQL queries, 150 DML statements, 10-second CPU time). Fewer records per batch means you’re less likely to hit those limits.
Larger batches (200–2,000) when your execute method is simple - setting a field value, light computation. More records per batch means fewer total transactions, which means the job finishes faster and you consume fewer of your org’s daily async execution quota (250,000 batch executions per 24 hours).
If you’re making callouts (Database.AllowsCallouts), the max batch size is effectively limited by the 100-callout-per-transaction limit. If each record needs one callout, your batch size can’t exceed 100.
A common mistake is setting the batch size to 2,000 without testing it first. Start at 200, monitor for governor limit errors, and adjust up or down based on what the AsyncApexJob record tells you.
Monitoring Your Jobs
In the UI
Navigate to Setup → Apex Jobs to see all running, queued, and completed batch jobs. Each row shows the class name, status (Queued, Processing, Completed, Failed, Aborted), and the number of batches processed versus total.
The Apex Flex Queue (Setup → Apex Flex Queue) shows jobs waiting to start. Salesforce allows 5 concurrent batch jobs; the rest queue here (up to 100). You can drag to reorder priority.
Programmatically via SOQL
The AsyncApexJob object is your best friend for building dashboards, sending alerts, or chaining jobs:
AsyncApexJob job = [
SELECT Id,
Status,
JobItemsProcessed,
TotalJobItems,
NumberOfErrors,
CreatedDate,
CompletedDate,
ExtendedStatus,
ApexClass.Name
FROM AsyncApexJob
WHERE Id = :batchJobId
];
// Calculate progress
Decimal progress = (job.TotalJobItems == 0) ? 0 :
(Decimal.valueOf(job.JobItemsProcessed) /
Decimal.valueOf(job.TotalJobItems) * 100).setScale(1);
System.debug(job.ApexClass.Name + ‘: ‘ + progress + ‘% complete, ‘
+ job.NumberOfErrors + ‘ errors’);
Building a Lightweight Monitoring Dashboard
Create a simple LWC or Flow that queries AsyncApexJob and displays active jobs:
// Controller method for a monitoring component
@AuraEnabled(cacheable=true)
public static List getActiveBatchJobs() {
return [
SELECT Id, ApexClass.Name, Status, JobItemsProcessed,
TotalJobItems, NumberOfErrors, CreatedDate
FROM AsyncApexJob
WHERE JobType = ‘BatchApex’
AND Status IN (‘Queued’, ‘Preparing’, ‘Processing’, ‘Holding’)
ORDER BY CreatedDate DESC
LIMIT 20
];
}
Alerting on Failures
In your finish method, always check NumberOfErrors. If it’s non-zero, send an email, post to a Slack webhook (via a Platform Event or a quick callout), or create a custom Batch_Job_Log__c record that an admin dashboard monitors.
Chaining Batches for Multi-Step Backfills
Sometimes a backfill isn’t one query - it’s a sequence. First update Accounts, then recalculate Opportunities, then refresh a rollup on a custom object. You chain batches from the finish method:
public void finish(Database.BatchableContext bc) {
// After Account backfill completes, start Opportunity recalc
Database.executeBatch(new OpportunityRecalcBatch(), 200);
}
For more complex chains, use a dispatcher pattern:
public class BatchChain {
private List> steps;
private Integer batchSize;
public BatchChain(List> steps, Integer batchSize) {
this.steps = steps;
this.batchSize = batchSize;
}
public void start() {
if (!steps.isEmpty()) {
Database.executeBatch(steps.remove(0), batchSize);
}
}
}
Be careful here. Each batch in the chain consumes one of your 5 concurrent batch slots. If you chain 8 batches and other processes are also submitting batch jobs, you’ll start seeing jobs stuck in the Flex Queue. For chains longer than 3–4 steps, consider using Queueable Apex instead, which has a higher concurrency ceiling.
The Trade-Offs You Should Know About
Batch Apex isn’t always the right tool. Here’s when it’s not:
Small record counts (under 10,000). The overhead of the batch framework - job queuing, context serialization, async scheduling - can make a simple anonymous Apex script or even a Flow faster for small updates.
Real-time requirements. Batch jobs can sit in the queue for minutes (or longer during peak hours). If you need an update to happen within seconds, use Queueable Apex or a trigger.
Complex transaction boundaries. Each execute call is its own transaction. If your backfill requires that all 50,000 records either succeed together or fail together, Batch Apex can’t give you that. (Though in practice, all-or-nothing at that scale is rarely the real requirement.)
Callout-heavy workloads. The 100-callout-per-transaction limit applies per execute call. If every record needs a callout, your effective batch size is ≤100, which means a million-record job takes 10,000+ transactions. At that point, evaluate whether a Mulesoft or Heroku integration might be more appropriate.
A Production-Ready Template
Here’s the pattern I use on every project. It combines parameterization, error tracking, optional chaining, and notification:
public class ConfigurableBackfillBatch
implements Database.Batchable, Database.Stateful {
private String query;
private IBatchTransform transformer;
private String notificationEmail;
private Database.Batchable nextBatch;
private Integer nextBatchSize;
// Error tracking
private Integer totalProcessed = 0;
private Integer totalErrors = 0;
private List sampleErrors = new List();
private static final Integer MAX_SAMPLE_ERRORS = 50;
public ConfigurableBackfillBatch(
String query,
IBatchTransform transformer,
String notificationEmail
) {
this.query = query;
this.transformer = transformer;
this.notificationEmail = notificationEmail;
}
public ConfigurableBackfillBatch chainNext(
Database.Batchable nextBatch,
Integer batchSize
) {
this.nextBatch = nextBatch;
this.nextBatchSize = batchSize;
return this; // fluent API
}
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(query);
}
public void execute(Database.BatchableContext bc, List scope) {
transformer.apply(scope);
List results = Database.update(scope, false);
for (Integer i = 0; i < results.size(); i++) {
if (results[i].isSuccess()) {
totalProcessed++;
} else {
totalErrors++;
if (sampleErrors.size() < MAX_SAMPLE_ERRORS) {
sampleErrors.add(
scope[i].Id + ‘: ‘
+ results[i].getErrors()[0].getMessage()
);
}
}
}
}
public void finish(Database.BatchableContext bc) {
// Send summary email
if (String.isNotBlank(notificationEmail)) {
String body = ‘Batch complete.n’
+ ‘Records updated: ‘ + totalProcessed + ‘n’
+ ‘Errors: ‘ + totalErrors + ‘n’;
if (!sampleErrors.isEmpty()) {
body += ‘nSample errors:n’
+ String.join(sampleErrors, ‘n’);
}
Messaging.SingleEmailMessage mail =
new Messaging.SingleEmailMessage();
mail.setToAddresses(new List{ notificationEmail });
mail.setSubject(‘Backfill Job: ‘ + totalProcessed
+ ‘ updated, ‘ + totalErrors + ‘ errors’);
mail.setPlainTextBody(body);
Messaging.sendEmail(
new List{ mail }
);
}
// Chain next batch if configured
if (nextBatch != null) {
Database.executeBatch(nextBatch, nextBatchSize);
}
}
}
Invoke it:
Database.executeBatch(
new ConfigurableBackfillBatch(
‘SELECT Id, BillingState FROM Account WHERE Region__c = null’,
new TerritoryTransform(),
‘[email protected]‘
).chainNext(new OpportunityRecalcBatch(), 200),
200
);
One class. Reusable across any backfill. Error tracking built in. Chaining built in. Notifications built in.
Final Checklist Before You Run a Backfill
Before kicking off a batch job in production, walk through this list:
Test in a sandbox first. Use a representative data volume - not 50 records, but 50,000.
Check the Flex Queue. If there are already 5 active batch jobs, yours will queue. Timing matters.
Use Database.update(scope, false). Partial success is almost always what you want for backfills.
Cap your error logging. If you’re using Database.Stateful, don’t accumulate unbounded lists. Set a maximum.
Add a notification in finish. You will forget to check manually. Your finish method should tell you the job is done.
Document the job. A comment in the class header that says “Run this when: the territory model changes. Last run: 2026–03–15 by Author Name” is worth more than you think.
Consider bypass flags. If your records have triggers or flows that shouldn’t fire during a backfill, use a static variable or Custom Permission to bypass them.
