Reference Field Filtering

Table Configuration > Reference Field Filtering

Dropdown menus (Reference Fields) are the connective tissue of your application. But a dropdown showing every record in the system is useless.

Reference Field Filtering allows you to turn dumb lists into intelligent, context-aware controls. You can define rules like "Only show Employees who belong to the selected Department."

The Competitors' Compromise

On platforms like ServiceNow, creating dependent dropdowns often requires writing "Reference Qualifiers"—server-side scripts that construct complex query strings. This approach is opaque, requires coding skills, and incurs performance penalties for every lookup.

The Simple Advantage

Simple uses Declarative JSON Filters. You define the logic using a standard, readable syntax directly on the field. There is no code to compile, no scripts to debug, and the platform handles execution, type safety, and edge cases instantly.

How It Works

Filters are defined in the field's Constraints JSON. They work by modifying the underlying GraphQL query used to fetch options for the dropdown.

You can filter based on:

1. Static Values: "Only show active records."
2. Dynamic Context: "Only show records related to the value in Field A."

1. Static Filters (The Baseline)

Apply a fixed rule to every user. For example, never show deleted or archived users in a selection list.

{
  "filter": {
    "is_active": { "_eq": true },
    "status": { "_neq": "Archived" }
  }
}

2. Dynamic Filters (The Context)

This is where forms become intelligent. You can reference other values in the current form using the $record.fieldName syntax.

Scenario: You are assigning a Task. You have selected a Department. You want the Assignee dropdown to only show users from that department.

{
  "filter": {
    "department_id": { "_eq": "$record.department_id" }
  }
}

The User Experience:

1. User selects "Engineering" in the Department field.
2. The Assignee dropdown instantly updates to show only Engineering staff.
3. If the user changes Department to "Sales," the Assignee selection is cleared and the list refreshes automatically.

Smart Platform Behaviors

The Simple Platform handles the edge cases that typically break scripts on legacy systems.

Automatic Type Casting

In standard JSON, everything is a string. In a database, types matter. Simple bridges this gap automatically. If your filter says "is_active": "true", but the database field is a boolean, the platform intelligently casts the value for you.

• "true" / "false" → true / false
• "123" → 123 (integer)

Graceful Null Handling

What happens if the user hasn't selected a Department yet?

• Legacy Platforms: The script errors out or returns 0 results.
• Simple Platform: Conditions relying on null or undefined values are automatically ignored. If a filter depends entirely on an empty field, the dropdown creates a "safe" query (or waits for input), preventing crashes and confusing empty states.

Advanced Logic

You are not limited to simple equality. You can use the full power of our GraphQL filter syntax, including _and, _or, and comparators.

Scenario: Show products that are active AND (match the selected category OR are flagged as "Global").

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

Supported Operators

We support a complete set of standard GraphQL operators:

Operator	Description	Example
_eq	Equals	{"status": {"_eq": "active"}}
_neq	Not Equals	{"status": {"_neq": "archived"}}
_gt	Greater Than	{"priority": {"_gt": 1}}
_gte	Greater Than or Equal	{"level": {"_gte": "$record.min_level"}}
_lt	Less Than	{"risk_score": {"_lt": 50}}
_lte	Less Than or Equal	{"budget": {"_lte": 1000}}
_in	In List	{"category": {"_in": ["Hardware", "Software"]}}
_nin	Not In List	{"type": {"_nin": ["Internal", "System"]}}
_like	Pattern Match (Case Sensitive)	{"sku": {"_like": "A-%"}}
_ilike	Pattern Match (Case Insensitive)	{"email": {"_ilike": "%@simple.com"}}

Best Practices

• Filter for Relevance, Secure via Policies: Use these filters to improve the User Experience (hide irrelevant options). Rely on Security Policies to enforce data access rules (hide unauthorized options).
• Index Filtered Columns: If you are filtering a list of 100,000 records by department_id, ensure department_id is indexed in the database for instant dropdown performance.
• Keep it Logical: If a filter depends on a field (e.g., Department), position that parent field above the dependent field (e.g., Assignee) in the form layout using Field Configuration.

Next Steps

Your data model is defined, your forms are clean, and your dropdowns are smart. Finally, let's configure how your tables relate to one another visually.

• Relationship Display: Customize the labels for Related Lists (e.g., rename "invoice_items" to "Line Items").