List - Filter
Type identifier:
list:filterCategory: List Operations
Description
Filters, sorts, and paginates an array of items. Apply filter conditions to select matching items, sort by multiple fields, remove duplicates, and limit results.
Input Handles
Handle | Data Type | Required | Description |
|---|---|---|---|
|
| Yes | The array to filter |
| Varies | Varies | Dynamic handles for filter variables |
Input Handle Details
source
- Type:
array Notes:
- Must be an array
- Items can be any type
Variable Handles
Input handles generated from variables configuration:
- Used to populate filter context values
- Similar pattern to Object - Query variables
Output Handles
Handle | Data Type | Description |
|---|---|---|
|
| Filtered results (single or array) |
Output Handle Details
filtered
- Type: Object (if
firstOnly) or Array (if multiple) Notes:
- Returns first item or
nulliffirstOnlyand empty
- Returns first item or
Configuration Options
Property | Type | Required | Default | Description |
|---|---|---|---|---|
|
| Yes |
| Display label for the node |
|
| No |
| Filter conditions |
|
| No |
| Sorting configuration |
|
| No |
| Return single item vs array |
|
| No |
| Maximum items to return |
|
| No |
| Skip N items |
|
| No |
| Remove duplicate items |
|
| No |
| Fields to determine uniqueness |
|
| No |
| Variable definitions for filtering |
Configuration Details
filter
- Type: Same filter structure as Object - Query
- Operators:
eq,ieq,ne,ine,gt,gte,lt,lte,contains,in,nin,isNull,isNotNull Notes:
- Filters the items in the array; it does not query the database
- Supports nested AND/OR logic
- Context values populated from variables
ieqandineperform locale-independent case-insensitive equality and are available for string properties onlycontainsremains a case-sensitive substring operation
sort
- Type: Array of
{ id, path, direction } Structure:
[ { "id": "sort1", "path": ["name"], "direction": "desc" }, { "id": "sort2", "path": ["createdAt"], "direction": "asc" } ]- Notes: Multiple sort fields applied in order
distinctBy
- Type:
string[][](array of path arrays) Notes:
- When
distinctis true butdistinctByis empty, uses full item equality - When
distinctByhas paths, uniqueness is determined by those fields only - In v2, field values retain their types when determining uniqueness:
1and"1"are distinct, as are missing values andnull. Objects and arrays are compared structurally; object property order does not affect uniqueness. Text containing|does not combine with adjacent fields.
- When
Behaviour
Processing Pipeline
- Resolve source - Get input array
- Filter - Apply filter conditions
- Distinct - Remove duplicates (before sort)
- Sort - Apply multi-field sorting
- Pagination - Apply offset and limit
- Return - First item or full array
Filter Matching
Each item is checked against the filter conditions:
- Handles nested object paths
- Supports all comparison operators
Error Handling
Scenario | Behaviour |
|---|---|
Source is not array | Fails with |
Empty source array | Returns empty array (or |
No matching items | Returns empty array (or |
Examples
Basic Filter
{
"type": "list:filter",
"data": {
"label": "Active Users Only",
"filter": {
"path": "active",
"type": "property",
"value": { "type": "literal", "value": true },
"operator": "eq"
}
}
}Filter with Sort and Limit
{
"type": "list:filter",
"data": {
"label": "Top 10 Recent Orders",
"filter": {
"path": "status",
"type": "property",
"value": { "type": "literal", "value": "completed" },
"operator": "eq"
},
"sort": [{ "id": "date", "path": ["createdAt"], "direction": "desc" }],
"limit": 10
}
}Distinct by Field
{
"type": "list:filter",
"data": {
"label": "Unique Categories",
"distinct": true,
"distinctBy": [["category"]],
"sort": [{ "id": "name", "path": ["category"], "direction": "asc" }]
}
}Get First Match
{
"type": "list:filter",
"data": {
"label": "Find User by Email",
"variables": [{ "id": "email", "type": { "type": "string", "required": true } }],
"filter": {
"path": "email",
"type": "property",
"value": { "type": "contextValue", "valueId": "email" },
"operator": "eq"
},
"firstOnly": true
}
}