List - Filter

Type identifier: list:filter Category: 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

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

Output Handle Details

filtered

• Type: Object (if firstOnly) or Array (if multiple)

• Notes:

  • Returns first item or null if firstOnly and empty

Configuration Options

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
  • ieq and ine perform locale-independent case-insensitive equality and are available for string properties only
  • contains remains 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 distinct is true but distinctBy is empty, uses full item equality
  • When distinctBy has paths, uniqueness is determined by those fields only

Behaviour

Processing Pipeline

1. Resolve source - Get input array
2. Filter - Apply filter conditions
3. Distinct - Remove duplicates (before sort)
4. Sort - Apply multi-field sorting
5. Pagination - Apply offset and limit
6. 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

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
  }
}