Reference Field Filtering

Table Configuration > Reference Field Filtering

Make your forms smarter with intelligent reference field filtering that shows only relevant records based on context and form data.

What is Reference Field Filtering?

Reference Field Filtering allows you to control which records appear in reference field dropdowns by applying filters based on:

• Static conditions - Always filter out inactive records or specific categories
• Dynamic conditions - Show different options based on other field values in the same form
• Complex logic - Combine multiple conditions with AND/OR operators

How Reference Field Filtering Works

When a user opens a reference field dropdown, the system:

1. Evaluates filter conditions - Processes both static and dynamic filter rules
2. Applies type conversion - Automatically converts string values to appropriate types (boolean, number)
3. Fetches filtered records - Retrieves only records matching the filter criteria
4. Validates existing selections - Automatically clears invalid selections when filters change

Filter Configuration

Basic Setup

Reference field filters are configured in the field's Constraints JSON property:

{
  "filter": {
    "field_name": { "_eq": "value" }
  }
}

Static Filters

Static filters apply the same conditions every time:

{
  "filter": {
    "is_active": { "_eq": true },
    "status": { "_eq": "approved" }
  }
}

Dynamic Filters

Dynamic filters use values from other fields in the same form:

{
  "filter": {
    "department_id": { "_eq": "$record.department" },
    "role_level": { "_gte": "$record.min_level" }
  }
}

Dynamic Syntax: Use $record.fieldName to reference other field values.

Complex Filters

Combine multiple conditions with logical operators:

{
  "filter": {
    "_and": [
      { "is_active": { "_eq": true } },
      {
        "_or": [
          { "department_id": { "_eq": "$record.department" } },
          { "is_global": { "_eq": true } }
        ]
      }
    ]
  }
}

GraphQL Operators

Reference field filters support standard GraphQL comparison operators:

Operator	Description	Example
_eq	Equals	{"status": {"_eq": "active"}}
_neq	Not equals	{"status": {"_neq": "deleted"}}
_gt	Greater than	{"priority": {"_gt": 5}}
_gte	Greater than or equal	{"level": {"_gte": "$record.min_level"}}
_lt	Less than	{"age": {"_lt": 65}}
_lte	Less than or equal	{"score": {"_lte": 100}}
_in	In array	{"category": {"_in": ["A", "B", "C"]}}
_nin	Not in array	{"status": {"_nin": ["deleted", "archived"]}}
_like	Pattern match	{"name": {"_like": "%manager%"}}
_ilike	Case-insensitive pattern	{"email": {"_ilike": "%@company.com"}}

Real-World Examples

Employee Management System

Scenario: When assigning a project manager, show only managers from the selected department.

{
  "filter": {
    "_and": [
      { "department_id": { "_eq": "$record.department" } },
      { "role": { "_eq": "manager" } },
      { "is_active": { "_eq": true } }
    ]
  }
}

Result: Users see only active managers from the relevant department, reducing selection time by 80%.

Customer Support Ticketing

Scenario: When escalating a ticket, show only agents with appropriate skill level and availability.

{
  "filter": {
    "_and": [
      { "skill_level": { "_gte": "$record.complexity_level" } },
      { "is_available": { "_eq": true } },
      { "department": { "_eq": "$record.category" } }
    ]
  }
}

Result: Tickets get routed to qualified, available agents automatically.

Product Configuration

Scenario: When selecting product options, show only compatible accessories.

{
  "filter": {
    "_and": [
      { "product_category": { "_eq": "$record.base_product_category" } },
      { "compatibility_version": { "_gte": "$record.product_version" } },
      { "is_available": { "_eq": true } }
    ]
  }
}

Result: Customers see only compatible accessories, reducing configuration errors by 90%.

Advanced Features

Automatic Type Conversion

The system automatically converts string values to appropriate types:

• "true" → true (boolean)
• "false" → false (boolean)
• "123" → 123 (integer)
• "45.67" → 45.67 (float)

This ensures GraphQL queries work correctly regardless of how form data is stored.

Null Value Handling

When dynamic filter values are null or undefined:

• Individual conditions with null values are automatically removed
• Valid conditions in the same filter are preserved
• Empty filters show all records (no filtering applied)

Automatic Validation

When filter conditions change:

• Invalid selections are automatically cleared
• Users receive immediate feedback about cleared selections
• Data integrity is maintained without manual intervention

Configuration Steps

1. Identify Your Use Case

Determine what filtering logic you need:

• Static filtering for permanent restrictions
• Dynamic filtering for contextual relevance
• Complex filtering for sophisticated business rules

2. Design Your Filter

Plan your filter structure:

• List the conditions you need
• Identify which fields provide dynamic values
• Choose appropriate GraphQL operators

3. Configure the Field

1. Go to Settings → Table Fields
2. Find your reference field
3. Open the field record
4. Add your filter to the Constraints JSON:

{
  "filter": {
    "your_field": { "_eq": "$record.source_field" }
  }
}

4. Test Your Filter

1. Create or edit a record using your form
2. Change the source field values
3. Verify the reference field dropdown updates correctly
4. Confirm invalid selections are cleared appropriately

Best Practices

Filter Design

Start Simple: Begin with basic static filters, then add dynamic conditions as needed.

Use Meaningful Names: Reference field names that clearly indicate their purpose in filters.

Test Edge Cases: Verify behavior when source fields are empty or contain unexpected values.

Performance Optimization

Limit Result Sets: Use filters to keep dropdown options manageable (under 100 items when possible).

Index Filter Fields: Ensure database indexes exist on fields used in filter conditions.

Combine Conditions Efficiently: Structure _and/_or conditions to eliminate the most records first.

User Experience

Provide Clear Labels: Use descriptive display names for both source and target fields.

Add Field Descriptions: Help users understand how filtering works with helpful descriptions.

Handle Empty States: Ensure meaningful messages appear when filters return no results.

Troubleshooting

Common Issues

Filter Not Working

• Check JSON syntax in the constraints field
• Verify field names match exactly (case-sensitive)
• Ensure GraphQL operators are spelled correctly

Wrong Data Types

• Confirm boolean fields use true/false, not "true"/"false"
• Check that numeric comparisons use numbers, not strings
• Verify date formats match your database schema

Performance Problems

• Add database indexes on filtered fields
• Limit result sets with additional filter conditions
• Consider caching for frequently accessed reference data

Debug Tips

Test Filters Incrementally: Start with simple conditions and add complexity gradually.

Check Browser Console: Look for GraphQL errors or network issues in developer tools.

Verify Data Types: Use your database tools to confirm field types and sample values.

Next Steps

With reference field filtering configured, explore these related features:

• Field Configuration - Configure display names, descriptions, and positioning
• Relationship Display Configuration - Control how relationships appear in your interfaces
• Custom Views - Create specialized interfaces with filtered data

Back to Overview

Return to Table Configuration for a complete overview of all configuration options.