Filter 1.0.0

Overview

Function Beginner

Description

Filters a list of items using a configurable condition expression, returning only items that match the specified criteria. This block enables list processing and data subsetting based on complex logical conditions.

Expression Syntax: Use value to reference each individual item in the list, e.g., value.age >= 18 to filter objects by age.

Supports logical operators (and, or), comparison operators (==, !=, <, >, >=, <=, ~= for substring matching), nested field access (value.user.profile.active), length checks (len(value.items) == 3), and membership tests ('admin' in value.roles).

Literal lists/dicts are supported: value.status in ['active', 'pending'] or value.config == {"debug": true}. Keywords none|null|true|false are parsed as Python None|None|True|False.

Configuration Options

Name	Data Type	Description	Default Value
condition	str	Expression to evaluate against each item in the list. Default "value" filters truthy items. Use complex expressions like "value.age >= 21" to filter by specific criteria.	value

Inputs

Name	Data Type	Description
items	list[ValueT]	List of items to filter using the condition expression. Each item is evaluated individually against the configured condition.

Outputs

Name	Data Type	Description
items	list[ValueT]	Filtered list containing only items that matched the condition expression. Preserves original item structure and order.

Examples

Basic Usage Advanced

# Filter truthy values from list
- id: filter_non_empty
  uses: Filter@1.0.0
  with:
    condition: "value"  # Default condition filters truthy values
    items: ["hello", "", "world", null, "test", 0, "final"]
  outputs:
    items: filtered_strings

# Filter adults from user list
- id: filter_adults
  uses: Filter@1.0.0
  with:
    condition: "value.age >= 18"
    items:
      - name: "Alice"
        age: 25
        role: "admin"
      - name: "Bob"
        age: 16
        role: "user"
      - name: "Charlie"
        age: 30
        role: "user"
  outputs:
    items: adult_users

# Filter active products
- id: filter_active_products
  uses: Filter@1.0.0
  with:
    condition: "value.status == 'active'"
    items:
      - name: "Product A"
        status: "active"
        price: 99.99
      - name: "Product B"
        status: "discontinued"
        price: 49.99
      - name: "Product C"
        status: "active"
        price: 149.99
  outputs:
    items: active_products

# Complex filtering with multiple conditions
- id: filter_premium_users
  uses: Filter@1.0.0
  with:
    condition: "value.subscription == 'premium' and value.active == true and value.last_login_days <= 30"
    items:
      - id: 1
        name: "John Doe"
        subscription: "premium"
        active: true
        last_login_days: 5
      - id: 2
        name: "Jane Smith"
        subscription: "free"
        active: true
        last_login_days: 2
      - id: 3
        name: "Bob Johnson"
        subscription: "premium"
        active: false
        last_login_days: 10
  outputs:
    items: premium_active_users

# Filter by role permissions
- id: filter_admin_users
  uses: Filter@1.0.0
  with:
    condition: "'admin' in value.roles or 'superuser' in value.roles"
    items:
      - username: "alice"
        roles: ["user", "admin"]
        department: "IT"
      - username: "bob"
        roles: ["user"]
        department: "Sales"
      - username: "charlie"
        roles: ["user", "superuser"]
        department: "Engineering"
  outputs:
    items: admin_users

# Filter by substring matching
- id: filter_company_emails
  uses: Filter@1.0.0
  with:
    condition: "value.email ~= '@company.com'"
    items:
      - name: "Alice"
        email: "alice@company.com"
      - name: "Bob"
        email: "bob@external.org"
      - name: "Charlie"
        email: "charlie@company.com"
  outputs:
    items: internal_users

# Filter by nested object properties
- id: filter_notification_enabled
  uses: Filter@1.0.0
  with:
    condition: "value.settings is not none and value.settings.notifications.email == true"
    items:
      - user_id: 1
        settings:
          notifications:
            email: true
            sms: false
      - user_id: 2
        settings:
          notifications:
            email: false
            sms: true
      - user_id: 3
        settings: null
  outputs:
    items: email_notification_users

# Filter by list length and membership
- id: filter_multi_project_users
  uses: Filter@1.0.0
  with:
    condition: "len(value.projects) >= 2 and 'critical' in value.project_types"
    items:
      - name: "Developer A"
        projects: ["proj1", "proj2", "proj3"]
        project_types: ["web", "mobile", "critical"]
      - name: "Developer B"
        projects: ["proj1"]
        project_types: ["web"]
      - name: "Developer C"
        projects: ["proj4", "proj5"]
        project_types: ["mobile", "critical"]
  outputs:
    items: senior_developers

Error Handling

ExpressionSyntaxError

Error Code

filter_expression_syntax_invalid

Common Cause

Invalid expression syntax in the condition parameter (malformed operators, missing quotes, incorrect parentheses)

Solution

Verify expression syntax, check operator spelling (and/or/is not/in), ensure proper quoting of string literals, validate parentheses matching

PropertyAccessError

Error Code

filter_property_access_failed

Common Cause

Attempting to access non-existent properties on list items during filtering evaluation

Solution

Use "is not none" checks before accessing nested properties, verify property names match item structure, handle optional fields gracefully

TypeComparisonError

Error Code

filter_type_comparison_failed

Common Cause

Invalid type comparison during filtering (e.g., comparing mixed data types in list items)

Solution

Ensure consistent data types across list items, add type checks in conditions, or use string conversion for comparisons

FAQ

How does Filter differ from If block?

Filter processes each item in a list individually and returns matching items, while If evaluates a single value and routes it to true/false outputs. Filter is for list processing, If is for conditional routing.

Can I filter by multiple conditions?

Yes, combine conditions with "and"/"or": "value.age >= 18 and value.status == 'active' and 'admin' in value.roles". Use parentheses to control precedence for complex logic.

What happens when no items match the condition?

Filter returns an empty list [] when no items match the condition. This is normal behavior and can be handled by checking list length in subsequent blocks if needed.

How do I handle mixed data types in my list?

Use type-safe conditions with null checks: "value.age is not none and value.age >= 18" or add type verification: "value.type == 'user' and value.age >= 18" to avoid errors with inconsistent data structures.

Can I filter by properties of nested objects?

Yes, use dot notation for nested access: "value.profile.settings.notifications == true". Always check for null values first: "value.profile is not none and value.profile.active == true" to prevent errors.