Selector

The Selector node picks one item — or a subset — from an upstream list. It coexists with the per-edge selector (outputMode: "item", range tab, list tab): the edge is the quick path for trivial picks, the node is what you reach for when the selection is shared across multiple downstream consumers, complex enough to deserve a label on the canvas, or needs operators the edge doesn’t support (random, modulo, predicate, named-key).

List ──▶ Selector ──▶ DownstreamNode (uses `picked`)
                 ╰──▶ FallbackNode (uses `rest`)

Inputs

Handle	Accepts	Notes
in	text, image-url, video-url, audio-url, json	Single list source. Multiple incoming edges concatenate in connection order.

Outputs

Handle	Emits
picked	Items selected by the active mode. Always a list (1-element list for single-item modes).
rest	Items NOT selected, in source order. Partition invariants: picked ∪ rest = in, picked ∩ rest = ∅.

Both outputs are always visible. Downstream consumers receive the first item by default; set the edge’s each mode to fan out across the list.

Modes

Pick one mode in the config panel. Each behaves differently:

#	Mode	Required config	Picked size	Example
1	item	itemIndex (1-based: "3", "last", "last-1")	1	["a","b","c","d"] + itemIndex="last-1" → picked=["c"], rest=["a","b","d"]
2	range	rangeFrom, rangeTo, rangeStep	N	["a","b","c","d","e"] + from="2", to="4", step=1 → picked=["b","c","d"], rest=["a","e"]
3	list	listExpression (e.g., "1,3,5..last")	N	["a","b","c","d","e"] + "1,3,5" → picked=["a","c","e"], rest=["b","d"]
4	random	seed (optional), randomCount (default 1)	randomCount	["a","b","c","d"] + seed="42", randomCount=2 → deterministic 2-item pick, rest = the other two
5	modulo	moduloDivisor (literal int or {NodeLabel} ref)	1	["a","b","c"] + moduloDivisor="5" → idx = 5%3 = 2 → picked=["c"], rest=["a","b"]
6	predicate	predicateField, predicateOp, predicateValue, predicateMatch ("first" / "all"), predicateCaseSensitive	1 or N	items=[{score:10},{score:20},{score:30}] + field="score", op=">=", value="15", match="all" → picked = items where score≥15 (b, c)
7	named-key	namedKeyField, namedKeyValue	0 or 1	items=[{name:"hero",url:"x"},{name:"villain",url:"y"}] + field="name", value="hero" → picked = hero item

Per-mode notes

• item. Supports "last" and "last-N" for relative-from-end picks. Out-of-bounds indices clamp; malformed expressions fall back to the first item.
• range. Inclusive from/to. Negative step reverses (from="last", to="1", step=-1 → full reverse). Step 0 is treated as 1. Direction mismatch (e.g., forward range with negative step) returns [].
• list. Mixes literal indices and ranges: "1, 3..5, last". Duplicates and order are preserved. Malformed parts fall back to all items.
• random. With a non-empty seed, uses a deterministic mulberry32 PRNG hashed from the seed — same seed always produces the same pick within one workflow. Empty seed → Math.random() (new randomness per run). Samples without replacement; randomCount > items.length clamps to length.
• modulo. Index = divisor % items.length. Divisor accepts {NodeLabel} refs — typical usage inside a Loop is moduloDivisor="{LoopIteration}" to cycle through a shorter list. Non-numeric or unresolvable divisor falls back to index 0.
• predicate. Reuses the Filter List operator set (>, <, >=, <=, =, !=, contains, not_contains, starts_with, ends_with, regex, exists, not_exists). match="first" returns only the first matching item; match="all" returns every match.
• named-key. Equivalent to predicate(op="=", match="first"). Surfaced as a separate mode because “look up by name” is the common shape (two fields vs predicate’s three).

Template ref interpolation

These fields accept {NodeLabel} refs and resolve them inline at execution time:

Field	Mode	Why
moduloDivisor	modulo	Common case: {LoopIteration} cycles through assets
predicateValue	predicate	Mirrors Filter List’s value field — compare against upstream node output
namedKeyValue	named-key	Mirrors Filter List — e.g., look up by {CharacterName}
seed	random	Derive a deterministic seed from upstream content (e.g., {Project})

All other fields (itemIndex, rangeFrom, rangeTo, rangeStep, listExpression, randomCount, predicateField, predicateOp, predicateMatch, predicateCaseSensitive, namedKeyField) are treated as literals — they’re either selector-lib expressions ("last-1", "1, 3..5") or type-constrained (numbers, enums, JSON paths).

Pricing

Free — 0 credits. Selector is pure logic that runs inline (no provider call). Available in every edition.

Error and fallback behavior

Selector is lenient — it never fails the whole workflow on bad config. Each failure mode falls back to sensible defaults and surfaces a warning via errorMessage where appropriate.

Case	Behavior
Empty input (no upstream / upstream emits [])	picked=[], rest=[], status completed, no error
No upstream connected	Same as empty input
Multiple upstreams connected to in	Concatenated in connection order
Invalid itemIndex expression	Falls back to first item, errorMessage="Invalid index expression — used first item", status completed
Index out of bounds	Clamped to the nearest valid index
predicate matches nothing	picked=[], rest=items, no error
modulo divisor non-numeric or unresolvable ref	Index 0, errorMessage set, status completed
random count > list length	Clamped to list length
named-key no match	picked=[], rest=items, no error
Library throws unexpectedly	status="failed", errorMessage set to the thrown message

Contract: status="failed" only on unexpected errors. Configuration mistakes degrade gracefully — a Selector with a typo never takes down the workflow.

When to use Selector vs. the edge selector

Reach for the edge selector when…	Reach for the Selector node when…
Trivial single pick (item:3, range, list) feeding one consumer	The same selection feeds multiple downstream consumers (DRY)
You want the picker invisible on the canvas	The selection logic is important enough to deserve a label
Operator coverage is item/range/list	You need random / modulo / predicate / named-key
One output is enough	You want to route rejected items through rest

Edge and node coexist indefinitely — the edge selector isn’t being deprecated.

Notes

• Selector emits a uniform list shape (picked: string[]) regardless of mode — single-item modes return a 1-element list. Downstream consumers default to the first item and opt into fan-out via the edge’s each mode.
• Partitions are by index, not value. Duplicates land in the correct bucket: ["a","b","a","c"] with range 2..3 → picked=["b","a"] (indices 1, 2), rest=["a","c"] (indices 0, 3).
• The shared selector library powering Selector also drives the edge selector — item / range / list semantics are identical between the two.