Flow Loop Element Patterns

Flow Loop Element Patterns

Use this skill when a Flow contains a Loop element and you need to confirm the loop is safe, correct, and necessary. The Loop element is the most common source of governor-limit failures in Flow because anything placed inside its body executes once per iteration — and Salesforce's per-transaction limits (150 DML statements, 100 SOQL queries, 2,000 Flow elements) are shared across every iteration AND every other automation in the same transaction.

This skill is the canonical reference for: (1) what Loop semantics actually are, (2) the four anti-patterns that the flow-builder and flow-analyzer agents must flag (DML-in-loop, SOQL-in-loop, subflow-with-DML-in-loop, nested loops), (3) the collect-then-DML refactor that fixes most of them, and (4) when a Loop should be deleted entirely in favour of Collection Filter, Transform, or a tighter Get Records.

Before Starting

Gather this context before reviewing or editing any Flow with a Loop element:

• The flow type and trigger — record-triggered (which save phase), autolaunched, screen, scheduled. Record-triggered flows multiply the per-iteration cost by the trigger batch size (up to 200 in a single Bulk API chunk), and ALL iterations share one transaction.
• The loop's input collection — its source (Get Records output, manually built collection, prior loop's accumulator), its sObject type, and its expected size. A loop that worked at 5 records may fail at 200.
• Every element inside the loop body — flag any of: Create Records, Update Records, Delete Records, Get Records, Action (especially Apex invocable), Subflow. Loops containing only Assignment / Decision / formula evaluation are usually safe.
• Whether the iteration variable is modified — Flow's Loop iterator is a reference into the source SObject collection; a common practitioner assumption is that Assignment: loopItem.Field__c = X updates the source. It does not persist to the database; you must Add the modified item to a separate Update collection.
• Existing fault paths — an unhandled DML failure inside a loop rolls back the entire transaction (see flow/fault-handling), making the symptom appear at iteration 1 even when the bad data is at iteration 73.

Core Concepts

1. Loop element semantics and iteration variable scope

A Loop element takes an input collection (SObject Collection or primitive collection) and exposes a current item variable on each pass. Iteration order matches the order of the source collection — Flow does not sort or dedupe. The current-item variable is scoped at the flow level, not the loop level: after the loop's End connector executes, the variable retains the LAST item processed (or remains null only if the input collection was empty). Practitioners frequently rely on this for "last record processed" logic, but it is also a foot-gun if a downstream element accidentally references it.

For SObject collections, the current item is a reference to the same SObject instance held in the source collection — not a copy. Mutating fields on the iteration variable visibly changes the in-memory source collection, but does NOT issue a DML to the database. To persist changes you must call Update Records on a collection (typically the source collection itself, or a separate collection you accumulated). This is the single biggest semantic surprise in Flow.

2. Why DML / SOQL / Subflow-with-DML inside a loop is a P0

Salesforce enforces per-transaction governor limits that are shared across every flow, trigger, and Apex class in the same transaction: 150 DML statements, 100 SOQL queries (synchronous), 50,000 records retrieved, 6 MB of Apex heap. A Loop iterating 200 records with one Update Records inside the body issues 200 DML statements in that transaction, busting the 150 limit on iteration 76 and rolling back the whole thing. Same math for Get Records inside a loop versus the 100-SOQL ceiling. The flow does not "release" budget between iterations — there is one transaction, one budget.

Subflow-in-loop is the same anti-pattern in disguise. If LoopOverCases → Subflow_NotifyOwner calls a subflow whose body contains an Update Records, every iteration executes that subflow's DML — the parent loop bulkifies-fails just as if the DML were inline. Reviewers must inspect every subflow called inside a loop body. Action elements that wrap Apex invocables are equally suspect; the Apex method runs once per iteration unless its invocableMethod declaration accepts a List<> and the flow passes a collection (the action's bulkified-input contract is what matters, not whether it "looks bulky").

3. Collection-based alternatives — collect-then-DML, Collection Filter, Transform, Get-with-criteria

The fix for DML-in-loop is the collect-then-DML idiom: inside the loop body use Assignment with the Add operator to append the current item (modified as needed) into a separate SObject Collection variable, then place a single Update / Create / Delete Records element AFTER the loop, operating on the accumulated collection. One DML statement, regardless of input size.

For pure filtering, the Collection Filter element (GA since Winter '23) replaces a Loop+Decision+Add pattern with a single declarative element — fewer elements, fewer bugs, faster to read. For shape transformation between sObject types (e.g., Lead → Contact + Account + Opportunity), the Transform element (GA in Spring '24 for record-triggered/autolaunched flows) replaces a Loop that builds output records from input records. For "narrow this list to just the rows I care about," the cheapest fix is to push the filter into the upstream Get Records filter conditions or sort/limit clause — no loop at all.

Common Patterns

Pattern: Collect-Then-DML (the primary refactor)

When to use: Any time you have a Loop whose body needs to issue DML (Update / Create / Delete) on the iterated records or related records.

How it works:

1. Before the loop, initialize an empty SObject Collection variable, e.g. accountsToUpdate.
2. Inside the loop, use Assignment to set fields on the current item (or build a new SObject via constants/formulas).
3. In the same Assignment, add a row: accountsToUpdate Add {!CurrentAccount}.
4. After the loop ends, place ONE Update Records element with accountsToUpdate as the input.

Why not the alternative: Putting the DML directly inside the loop issues N DML statements (one per iteration) and bursts the 150-DML cap on any record-triggered flow processing a 200-record bulk insert.

Pattern: Map-Lookup via Pre-Loaded Collection

When to use: You need to enrich each row of collection A with a value derived from collection B, and B is not bounded to A by a parent-child relationship (so you cannot use a single Get Records with a related-list traversal).

How it works:

1. Use ONE Get Records to load all of B's relevant rows into a collection variable (e.g. all active Owners for a list of OwnerIds you're about to encounter).
2. Loop over A. Inside the loop, use a Decision element that filters the B collection by the lookup key (Flow does not have a native Map<Id, SObject> — you compare against the in-memory collection by iterating it OR by using a second short loop that breaks after the first match).
3. Use Assignment to set the enriched field on the current A item, then Add to an output collection.
4. Single DML on the output collection after the loop.

Why not the alternative: Get Records inside the outer loop issues one SOQL per A row — 200 A rows means 200 SOQL queries against the 100 sync SOQL limit. The pre-load pattern is one SOQL query regardless of size.

Pattern: Pre-Filter with Collection Filter Instead of Loop+Decision

When to use: You want to keep only rows of a collection that match a condition (no DML, no enrichment — pure filter).

How it works: Replace Loop → Decision → Assignment(Add) → end loop with a single Collection Filter element. The output is a new collection containing only the matching rows.

Why not the alternative: Loop+Decision+Assignment executes 3+ elements per iteration, so it burns roughly triple the CPU time of a single Collection Filter, is harder to read, and is one of the most common LLM-generated anti-patterns.

Pattern: Transform Element Instead of Loop+Build

When to use: Your loop body is constructing one output SObject per input SObject (typed conversion, e.g. Quote Line → Order Line). Spring '24+ on record-triggered and autolaunched flows.

How it works: Replace the loop with a single Transform element that maps source fields to target fields declaratively. Output is a target-type collection ready for Create Records.

Why not the alternative: Loop+Assignment(build new sObject)+Assignment(Add) consumes more elements, hides the field-mapping intent in two Assignment elements, and is harder to maintain when the target schema changes.

Decision Guidance

Recommended Workflow

1. Inventory every Loop element in the flow (and every subflow it calls). Record the input collection variable, sObject type, and expected size.
2. Classify each loop's body by what elements it contains: Pure (Assignment / Decision only), DML-in-loop (Create / Update / Delete), SOQL-in-loop (Get Records), Action-in-loop (Apex invocable), Subflow-in-loop (recurse and re-classify).
3. Refactor every DML-in-loop and SOQL-in-loop using Collect-Then-DML or Map-Lookup. Subflow-in-loop is refactored by either inlining the subflow logic or re-shaping the subflow to accept and operate on a collection.
4. Consider replacing the loop entirely — could a Collection Filter, Transform, or sharper Get Records eliminate the loop? If yes, prefer the loop-free version.
5. Validate against flow-bulkification — verify the redesigned flow respects the 200-record save-trigger contract and stays inside the transaction's CPU-time, SOQL, and DML budgets. For high-volume scenarios also consult flow-large-data-volume-patterns and flow-governor-limits-deep-dive.

Review Checklist

• No Create / Update / Delete Records element appears inside any Loop body (direct or via subflow / action).
• No Get Records element appears inside any Loop body.
• Every loop with mutation has a corresponding Assignment-with-Add into a target collection AND a single post-loop DML.
• No nested loops unless the inner-collection size is hard-bounded to a small constant AND a Map-Lookup pattern was rejected with reason documented.
• Iteration-variable assignments are NOT relied on to persist to the database (a separate Update Records on a collection exists).
• Element-count estimate (loops counted as body_elements * iterations) stays under 2,000 per interview at expected volume.
• Pure-filter loops have been replaced with Collection Filter; pure-transform loops have been replaced with Transform where Spring '24+ permits.
• Subflows called inside a loop have been inspected for hidden DML / SOQL.

Salesforce-Specific Gotchas

1. Iteration variable for SObject collections is a reference, not a copy — modifying loopItem.Field__c inside an Assignment changes the in-memory source collection, but does NOT persist to the database. Practitioners assume the change is saved and skip the post-loop Update Records. Result: silent data loss until QA notices.
2. Iteration variable retains the last item after the loop ends — the variable is flow-scoped, not loop-scoped. Downstream elements that reference it get the last record processed (or null if the input collection was empty). Convenient for "last item" logic, but a bug if accidentally referenced.
3. Element count is a CPU-time proxy, not a limit of its own (on API 57.0+) — the old per-interview ceiling of 2,000 executed elements applied to API version 56.0 and earlier only; Salesforce removed it in API 57.0 (Spring '23). Flows pinned to an older API version still hit it and fail with Number of iterations exceeded. On a current flow, high element counts are still the problem — they just surface as the 10,000 ms synchronous CPU-time limit instead. A loop body of 4 elements iterating 200 records is 800 element-executions; nested loops at 200×200 are 40,000+, which will exhaust CPU time long before anything else. Estimate element-executions for the same reason you always did; just do not quote a 2,000 ceiling.
4. DML budget is per-transaction, shared across the whole call stack — the 150-DML cap is shared with every other trigger, flow, and Apex class in the same transaction. A loop with one DML inside, called from a record-triggered context already running 50 other automations, busts the limit much earlier than 150 iterations.
5. Subflow-in-loop hides the anti-pattern from a casual review — LoopOverContacts → Subflow_RefreshAccountSummary looks innocuous. Open the subflow and it does Get Records + Update Records — congratulations, you have SOQL-in-loop AND DML-in-loop, just two screens away.
6. Collection variables are NOT auto-deduped — Add on Assignment appends every time, including duplicates. If a loop with branching paths can Add the same record from two branches, your post-loop Update Records will issue duplicate writes (one DML, but the same row updated twice in memory) — and worse, can hit the "duplicate id in collection" runtime error on Update.
7. Loop iteration order is the source-collection order, not deterministic — if the input came from Get Records without a Sort Order, ordering depends on the database's chosen index. Order-dependent loop logic is a bug waiting to happen across orgs.

Output Artifacts

Related Skills

• flow-bulkification — the broader framing for designing flows that survive 200-record bulk save contexts. This skill is the loop-specific subset of that work.
• flow-collection-processing — full reference for Loop, Assignment-with-Add, Collection Filter, Collection Sort, and Transform semantics. Read this first for collection element selection.
• flow-cross-object-updates — when the loop body reaches into related records, the cross-object update patterns describe how to batch parent / child writes.
• flow-get-records-optimization — most SOQL-in-loop refactors collapse into a single optimized Get Records; this skill shows how to write that query.
• flow-governor-limits-deep-dive — exhaustive treatment of the CPU-time / 150-DML / 100-SOQL ceilings the loop must respect.
• flow-large-data-volume-patterns — when the input collection itself is too big for a single transaction (move to scheduled-paths or invocable Apex).
• fault-handling — fault paths around the post-loop DML so a single bad row does not silently roll back the whole interview.
• subflows-and-reusability — when refactoring subflow-in-loop, the contract for bulk-safe subflow inputs.

Official Sources Used

• Flow Loop element reference — https://help.salesforce.com/s/articleView?id=platform.flow_ref_elements_loop.htm&type=5
• Flow Builder Considerations and Limits — https://help.salesforce.com/s/articleView?id=sf.flow_considerations_limits_general.htm&type=5
• Flow Best Practices (avoid DML/SOQL inside loops) — https://help.salesforce.com/s/articleView?id=sf.flow_prep_bestpractices.htm&type=5
• Apex Governor Limits (per-transaction DML and SOQL ceilings the flow shares) — https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_gov_limits.htm
• Collection Filter element — https://help.salesforce.com/s/articleView?id=platform.flow_ref_elements_collection_filter.htm&type=5
• Transform element — https://help.salesforce.com/s/articleView?id=platform.flow_ref_elements_transform.htm&type=5