Flows/Utilities/Flow Control/Bundle Limit

Bundle Limit

Limit how many bundles pass through your flow

Overview

The Bundle Limit utility filters bundles from an iterator, controlling which bundles pass through to downstream nodes. It supports multiple operation modes for flexible filtering.

Use Bundle Limit to keep only the first N items, last N items, a specific range, or skip items from the beginning or end of an iteration.

Configuration

Operation

Select how to filter bundles:

Keep First

Return only the first N bundles. Requires Max Items.

Keep Last

Return only the last N bundles. Requires Max Items.

Keep Range

Return bundles from position X to Y (1-based). Requires Start Position and End Position.

Skip First

Skip the first N bundles, return the rest. Requires Max Items.

Skip Last

Skip the last N bundles, return the rest. Requires Max Items.

Max Items

Number of bundles to keep or skip (used by Keep First, Keep Last, Skip First, Skip Last). Supports templates: {{#1.data.limit}}

Start Position / End Position

1-based positions for Keep Range operation. Position 1 is the first bundle. Supports templates for dynamic ranges.

Output

Bundles that pass the filter continue to downstream nodes with their data unchanged. Blocked bundles are skipped and do not execute downstream nodes.

Behavior:

Passing bundles: Original bundle data passed through unchanged
Blocked bundles: Downstream nodes are skipped for that bundle

Examples

Example 1: Keep First 5 Items

Process only the first 5 records from an iteration:

Operation:Keep First

Max Items:5

From 100 bundles → Only bundles 1-5 pass through.

Example 2: Get Last 3 Items

Process only the last 3 records (e.g., most recent items):

Operation:Keep Last

Max Items:3

From 10 bundles → Only bundles 8, 9, 10 pass through.

Example 3: Process a Range

Process items 5 through 10 (useful for pagination testing):

Operation:Keep Range

Start Position:5

End Position:10

From 20 bundles → Only bundles 5-10 pass through.

Example 4: Skip Header Row

Skip the first row (e.g., header in CSV data):

Operation:Skip First

Max Items:1

From 100 bundles → Bundles 2-100 pass through (first bundle skipped).

Advanced: Nested Iterators

Bundle Limit intelligently handles nested iterator contexts. It always affects only its immediate parent iterator (the innermost iterator in the scope stack), never corrupting parent or grandparent iterator counts.

Immediate Parent Iterator Rule

Consider this nested flow structure:

i1 (5 bundles) → i2 (6 bundles) → Bundle Limit (keep_first: 3) → a2

In this example:

Bundle Limit targets i2 (the innermost iterator)
Each iteration of i2 is limited to 3 bundles
i1 keeps all 5 bundles unchanged
Total operations: 5 × 3 = 15

After Aggregator Context

When an aggregator finalizes, it pops its source iterator from the scope stack. Bundle Limit then correctly targets the remaining innermost iterator:

i1 (5 bundles) → i2 (6 bundles) → a2 → Bundle Limit (keep_first: 4)

Here, after a2 aggregates i2, only i1 remains in scope. Bundle Limit correctly limits i1 to 4 bundles.

Per-Outer-Bundle State

Bundle Limit maintains separate state for each outer bundle iteration:

Outer[0] → Inner[0,1,2] → Bundle Limit (keep_first: 2)  // Keeps 0,1
Outer[1] → Inner[0,1,2] → Bundle Limit (keep_first: 2)  // Keeps 0,1
Outer[2] → Inner[0,1,2] → Bundle Limit (keep_first: 2)  // Keeps 0,1

Each outer iteration gets its own bundle count, ensuring consistent filtering regardless of nesting depth.

Advanced: Multiple Bundle Limits

You can chain multiple Bundle Limits in the same iterator context. Each Bundle Limit maintains its own independent state, keyed by node ID.

Chained Bundle Limits

i1 (10 items) → Bundle Limit #1 (keep_first: 6) → IF → Bundle Limit #2 (keep_first: 3)

In this example:

Bundle Limit #1 limits i1 to 6 bundles
IF may filter some bundles based on conditions
Bundle Limit #2 independently counts bundles that pass IF, keeping only the first 3

Post-IF Independent Counting

When Bundle Limit is placed after an IF or Bundle Filter node, it tracks bundles independently. Only bundles that pass the condition are counted.

Supported operations after IF: keep_first, skip_first, keep_range

Limitations after IF: keep_last and skip_last pass all bundles (cannot determine total ahead of time)

Advanced: Complex Flow Patterns

Example: Triple-Nested with Limits

i1 (5) → i2 (6) → Bundle Limit (3) → a2 → i3 (4) → a3 → Bundle Limit (4)

Execution breakdown:

First Bundle Limit targets i2, limiting to 3 bundles per i1 iteration
a2 aggregates i2 results (3 items each)
i3 iterates over aggregated data (4 items)
a3 aggregates i3 results
Second Bundle Limit targets i1 (only iterator left), limiting to 4 bundles
Total i1 iterations: 4 (not 5)

Example: Conditional + Multiple Limits

i1 (20) → Bundle Limit (10) → IF (filter odds) → Bundle Limit (3) → Process

Execution breakdown:

First limit: Only first 10 bundles pass
IF: Filters to odd numbers only (5 bundles pass)
Second limit: Only first 3 of the 5 passing bundles continue
Result: 3 bundles processed

Tips

Tip: Place Bundle Limit early in your flow (right after the iterator) to save processing time and resources.

Tip: Use Bundle Limit during development, then remove or increase the limit for production.

Tip: In nested iterators, remember Bundle Limit always affects the innermost iterator. If you need to limit an outer iterator, place Bundle Limit after its aggregator.

Note: Bundle Limit counts bundles sequentially. If you need random sampling, use a Code utility to filter randomly before Bundle Limit.

Note: For keep_last/skip_last after IF nodes, use an Array Aggregator to collect passing bundles first, then apply Bundle Limit.

IF Break Iteration