Overview
Selects elements from a list with a conditional expression. Only elements for
which an expression such as item >= 0.75 evaluates to true remain. Use it to
thin candidates, select by threshold, or extract a regular pattern such as
"even positions only."
Usage tips
- It is the counterpart to
list_map(transformation): map processes every element, while filter selects elements. When using both, filter → map avoids unnecessary work. - Expose a threshold through the
xinput pin for interactive workflows where a slider adjusts how aggressively the candidates are filtered. - Remember that the count changes. When connecting to a downstream setup that
expects a fixed count (such as
list_unpack), check thecountoutput.
Related nodes
list_map— transform instead of selectlist_slice— extract by position instead of conditionexpression_bool— single-value Bool version using the same expression enginevariant_range/cartesian_product— sources of candidates to filter
Read this first
predicateis evaluated once for every element.- The default predicate
trueis valid for every item type and initially keeps all elements. - An element remains when the result is
trueand is discarded when it isfalse. - Thus, with
list = [0.25, 0.75, 1.25]andpredicate = item >= 0.75:0.25 >= 0.75isfalse, so it is discarded0.75 >= 0.75istrue, so it remains1.25 >= 0.75istrue, so it remains
Names available by item type
Names derived from the current item depend on its type. item is not available for
every type.
| Item type | Names derived from the item |
|---|---|
Number / Float / Int / Bool |
item |
Color |
item_r, item_g, item_b, item_a |
Vec2 |
item (Vec2), item_x, item_y |
Vec3 |
item_x, item_y, item_z |
Map |
Key names described below |
| Other structured types | No item-derived expression variable |
With Any, a runtime Number, Color, Vec2, Vec3, or Map item exposes the names for its
actual type during evaluation. The following common names are available regardless of
item type.
| Name | Meaning | Example |
|---|---|---|
index |
The zero-based position of the element | index % 2 == 0 |
count |
Total number of elements | index / max(count - 1, 1) |
x, y, z, w |
Auxiliary input pins or numbers supplied in the Inspector | item >= x |
vec, vx, vy |
Auxiliary Vec2 input, or the Inspector's vec_x, vec_y |
length(vec) > 1 |
flag |
Auxiliary Bool input, or the Inspector default | flag && index > 0 |
time, frame, total_frames |
Timing information at evaluation | frame % 2 == 0 |
Map elements
When an element is a Map, a non-reserved key that is a valid identifier (such as
value, a, or _seed) can be written directly in the condition. Every valid key is
also exposed with the item_ prefix.
For example, if an element is:
{ "index": 0, "value": 0.25 }
You can write these directly in the condition:
value < 0.5
item_index == 0
index always means the current position in the list. Use item_index to read the
Map's index key. The reserved names item, index, count, x, y, z, w,
vec, vx, vy, flag, time, frame, and total_frames keep their standard
meaning; use item_<key> for a Map value with one of those names. A valid identifier
starts with an ASCII letter or _ and continues with ASCII letters, digits, or _;
other keys are not exposed as expression variables.
How to read common inputs:
| Input source | Element shape | Names available in the condition |
|---|---|---|
| Ordinary numeric list | 0.25, 0.75, 1.25 |
item, index, count |
List Enumerate |
{ "index": 0, "item": 10 } |
Current position as index; Map values as item_index, item_item |
List Zip |
{ "index": 0, "a": 1, "b": 10 } |
a, b; the Map index as item_index |
Cartesian Product |
Map with multiple keys | Non-reserved keys directly, or each valid key as item_<key> |
Common expressions
item >= 0.75- Retains only values at or above the threshold.
index % 2 == 0- Retains only even positions.
item >= x- Retains only elements at or above a threshold supplied from outside.
value < 0.5 && item_index == 0- Filters a Map with multiple conditions.
a * 10 == b- Filters by the relationship between two lists from
List Zip.
- Filters by the relationship between two lists from
Concrete examples
Example 1: Retain only values at or above 0.75
Input:
[0.25, 0.75, 1.25]
Settings:
item_type = Floatpredicate = item >= 0.75
Output:
list = [0.75, 1.25]
count = 2
Example 2: Retain part of a List Zip result
Input:
[
{ "index": 0, "a": 1, "b": 10 },
{ "index": 1, "a": 2, "b": 20 }
]
Settings:
item_type = Mappredicate = a * 10 == b
Output:
list = [
{ "index": 0, "a": 1, "b": 10 },
{ "index": 1, "a": 2, "b": 20 }
]
count = 2
Example 3: Retain only even positions
Input:
[10, 20, 30, 40, 50]
Settings:
item_type = Numberpredicate = index % 2 == 0
Output:
list = [10, 30, 50]
count = 3
Example 4: Use a variable or auxiliary input as the threshold
Input:
[0.25, 0.75, 1.25]
Settings:
item_type = Floatpredicate = item >= xx = 0.75
Output:
list = [0.75, 1.25]
count = 2
Enter x directly in the Inspector, or connect a Variable Ref to the x input pin.
When to use it
- When you want to retain only batch-production candidates that meet a condition
- When you want to reduce the number of candidates before sending them to
Batch Render
Notes
- v1 is based on constrained expressions.
- It is not intended to run an arbitrary subgraph as a predicate.
- Standard variables take priority over reserved Map keys. Read a same-named Map value
through
item_<key>.