Skip to main content

Advanced Filters

Advanced Filters let users build queries from conditions joined with AND / OR, nested in groups, with an operator per condition (is_not, greater_than, is_empty, …). They appear automatically on any index page with :single_select, :multi_select, :range, :date or :string filters.

Quick example​

cm_index do
filter :title, :string
filter :status, :single_select, helper_method: :status_options
filter :age, :range
end

On the index page, open Filters β†’ Add advanced filter to build status is active AND (age > 60 OR title contains "draft"). The standard filter bar only supports "equals / between"; no extra DSL or generator is needed.

Using advanced filters​

Declare filters as usual:

cm_admin do
cm_index do
filter %i[name email], :search, placeholder: 'Search'
filter :title, :string, placeholder: 'Search title'
filter :status, :single_select, helper_method: :status_options
filter :age, :range, placeholder: 'Age'
filter :created_at, :date, placeholder: 'Created at'
end
end

On the index page, open Filters β†’ Add advanced filter, then:

  1. Pick a field, an operator, and a value.
  2. Use Add condition to add more rows, and switch the connector between And and Or.
  3. Use Add condition group to nest conditions, for example status is active AND (age > 60 OR created_at between …).
  4. Click Apply.
note

While Advanced Filters are active, the standard filter bar is hidden. Standard filters, including their default_values, are ignored: only search and the advanced conditions are applied. Exports follow the same rule.

Operators​

Filter typeOperatorsDefault
:single_select, :multi_selectis, is_not, is_empty, is_not_emptyis
:datebetween, not_between, is_empty, is_not_emptybetween
:rangebetween, not_between, is, is_not, greater_than, less_than, greater_than_or_equal_to, less_than_or_equal_to, is_empty, is_not_emptybetween
:stringis, is_not, contains, does_not_contain, is_empty, is_not_emptycontains
  • between / not_between take a range value ("18 to 30", "2026-01-01 to 2026-01-31").
  • is_empty / is_not_empty take no value and check for NULL (for :string, is_empty also matches empty strings).
  • All other operators take a single value.
  • :string matches are case-insensitive and the value is matched literally β€” %, _ and \ are escaped, not treated as wildcards. is_not and does_not_contain also match NULL rows.

Conditions are evaluated left to right: A OR B AND C means (A OR B) AND C. Use a condition group when you need a different precedence.

Custom filter scopes (filter_with)​

Filters that use filter_with work in Advanced Filters too. The scope receives the selected operator as a second argument, condition, which is nil when the scope is called from the standard filter bar:

# :single_select / :multi_select
scope :by_company_country, lambda { |value, condition = nil|
left_joins(:company).ct_dropdown_filter_condition(column: :country, value:, condition:, table: 'companies')
}

# :range / :date. `value` is the raw string, e.g. "18 to 30" or "18"
scope :by_company_size, lambda { |value, condition = nil|
left_joins(:company).ct_range_filter_condition(column: :employee_count, value:, condition:, table: 'companies')
}

# :string
scope :by_company_name, lambda { |value, condition = nil|
left_joins(:company).ct_string_filter_condition(column: :name, value:, condition:, table: 'companies')
}

ct_dropdown_filter_condition, ct_range_filter_condition and ct_string_filter_condition are available on every ActiveRecord model and implement all of the operators above. table: defaults to the model's own table. If you write the logic yourself, remember to handle is_empty / is_not_empty, which are called with a blank value. See Custom Filter Method.

URL format​

Filters, both standard and advanced, are stored in the filters query param as zlib-compressed, base64url-encoded JSON. Once decoded, an advanced filter looks like this:

{
"search": "john",
"advanced": [
{
"filter_type": "single_select",
"filter_name": "status",
"condition": "is",
"value": "active",
"operator": "and"
},
{
"filter_type": "group",
"operator": "and",
"value": [
{
"filter_type": "range",
"filter_name": "age",
"condition": "greater_than",
"value": "60",
"operator": "and"
},
{
"filter_type": "date",
"filter_name": "created_at",
"condition": "between",
"value": "2026-01-01 to 2026-01-31",
"operator": "or"
}
]
}
]
}

operator joins an item to the items before it. The first item's operator is ignored.

Use the helpers below whenever you read or build this param in Ruby. The legacy nested filters[...] hash is still accepted:

filters = CmAdmin::Utils.decode_filter_params(params[:filters]) || {}

cm_admin.cm_index_user_path(filters: CmAdmin::Utils.encode_filter_params(filters))

To save a set of advanced filters and reuse it later, see Saved Views.