operators.md

Operator Reference

ActiveDataSource provides 30+ filter operators out of the box.

All operators have aliases — use whichever reads most naturally in your frontend.

---

Syntax

filter[field][operator]=value

With nested associations:

filter[association.field][operator]=value
# e.g. filter[organization.name][contains]=OpenAI

---

Equality

Operator	Aliases	SQL	Example
eq	equal, equals, is	field = ?	filter[status][eq]=active
neq	not_eq, not_equal, ne	field != ?	filter[status][neq]=inactive

Comparison

Operator	Aliases	SQL	Example
gt	greater_than, above	field > ?	filter[age][gt]=18
gte	gteq, greater_or_equal	field >= ?	filter[age][gte]=18
lt	less_than, below	field < ?	filter[age][lt]=65
lte	lteq, less_or_equal	field <= ?	filter[age][lte]=65

String Matching

Operator	Aliases	SQL	Example
contains	cont, include, like	field LIKE '%?%'	filter[name][contains]=john
starts_with	start, begins, prefix	field LIKE '?%'	filter[name][starts_with]=J
ends_with	end, suffix	field LIKE '%?'	filter[email][ends_with]=@example.com
matches	match, regex, ilike	field ILIKE ?	filter[name][matches]=J%hn

Set Membership

Operator	Aliases	SQL	Example
in	any, one_of	field IN (?)	filter[status][in]=active,pending
not_in	not_any, none_of	field NOT IN (?)	filter[status][not_in]=inactive

Use comma-separated values for in / not_in.

Range

Operator	Aliases	SQL	Example
between	range	field BETWEEN ? AND ?	filter[age][between]=18,65

Pass exactly two comma-separated values.

Null / Presence

Operator	Aliases	SQL	Example
null	is_null, nil	field IS NULL	filter[deleted_at][null]=1
not_null	is_not_null, present_id	field IS NOT NULL	filter[confirmed_at][not_null]=1
blank	empty, is_blank	(custom)	filter[bio][blank]=1
present	not_blank, is_present	(custom)	filter[bio][present]=1

Boolean

Operator	Aliases	SQL	Example
true	is_true, yes, on	field = TRUE	filter[admin][true]=1
false	is_false, no, off	field = FALSE	filter[admin][false]=1

Date / Time Helpers

These operators require no value — just pass any truthy value (e.g. =1).

Operator	Date Range	Example
today	today..today	filter[created_at][today]=1
yesterday	yesterday..yesterday	filter[created_at][yesterday]=1
this_week	start_of_week..end_of_week	filter[created_at][this_week]=1
last_week	previous week	filter[created_at][last_week]=1
this_month	start_of_month..end_of_month	filter[created_at][this_month]=1
last_month	previous month	filter[created_at][last_month]=1
this_year	start_of_year..end_of_year	filter[created_at][this_year]=1
last_year	previous year	filter[created_at][last_year]=1
date	exact date match	filter[created_at][date]=2024-01-15
time	exact datetime match	filter[created_at][time]=2024-01-15T10:30:00

Custom Scope

Apply a named ActiveRecord scope on the model:

filter[active][scope]=1

The model must define a scope named active.

---

Nested Association Filters

Use dot notation to filter by associated model attributes:

filter[organization.name][contains]=OpenAI
filter[organization.country][eq]=US
filter[roles.name][in]=admin,manager

The Ransack adapter converts these to organization_name_cont etc.

---

Restricting Operators Per Field

In the Resource DSL:

filterable :age, operators: [:gt, :lt, :gte, :lte, :between]
# Only comparison operators allowed for age — string operators are rejected

---

Combining Filters

Multiple filters are combined with AND:

filter[status][eq]=active&filter[age][gte]=18&filter[organization_id][eq]=5

All three conditions must be true.