Operators

A single filter condition is a ColumnFilter: a field, an operator, an optional value, and optional nested AND/OR arrays. parseFilterRequest builds these from the query string; applyFilter validates them and the Lucid adapter translates each into the matching where* call.

interface ColumnFilter {
  field: string;
  operator: FilterOperatorInput; // one of 22 operators, or a SQL-symbol alias
  value?: unknown;               // omitted for unary operators
  AND?: ColumnFilter[];          // nested AND group
  OR?: ColumnFilter[];           // nested OR group
}

The operator list is exported as FILTER_OPERATORS and the alias map as OPERATOR_ALIASES from @adonis-agora/filter.

All 22 operators

Comparison

String (all case-insensitive via whereILike)

Array

Range

Unary (no value)

SQL-symbol aliases

The six scalar comparison operators accept their familiar SQL symbols. Aliases are normalized to the canonical operator during validation (and persisted in-place on the ColumnFilter), so the query builder never sees a symbol form.

import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'

// A client sending `?filter[age][>=]=18` parses to operator '>=',
// which applyFilter normalizes to 'gte' before building the query.

If you need the canonical form programmatically, normalizeOperator() is exported:

import { normalizeOperator } from '@adonis-agora/filter'

normalizeOperator('=')         // 'equals'
normalizeOperator('<>')        // 'notEquals'
normalizeOperator('iContains') // 'iContains' (canonical operators pass through)

The wire format

parseFilterRequest reads the Spatie / JSON:API conventions. Given a decoded request.qs():

GET /users?filter[name][contains]=fleet&filter[age][gte]=18&filter[status]=active

parses to:

{
  filters: [
    { field: 'name', operator: 'contains', value: 'fleet' },
    { field: 'age', operator: 'gte', value: '18' },
    { field: 'status', operator: 'equals', value: 'active' },
  ],
}

Sort, pagination, search and distinct

?sort=-createdAt,name         → [{ field: 'createdAt', direction: 'desc' }, { field: 'name', direction: 'asc' }]
?page=2&size=50               → page: 2, size: 50
?page[number]=2&page[size]=50 → page: 2, size: 50   (JSON:API nested form)
?search=fleet                 → search: 'fleet'
?distinct=city,tier           → distinct: ['city', 'tier']
?distinct[]=city&distinct[]=tier → distinct: ['city', 'tier']  (repeated form)

A leading - on a sort entry means descending. distinct names the columns of a DISTINCT projection that applyFilter applies for you — allow-listed like any other field, and limited to root-table columns. Both parseFilterRequest and parseSpatieRequest read it.

The structured (POST) shape

The same parser accepts the object the client builder's .build() returns, so a POST /search endpoint can hand the body straight in:

parseFilterRequest({
  filter: { where: [{ field: 'age', operator: 'gte', value: 18 }] },
  sort: [{ field: 'createdAt', direction: 'desc' }],
  paginate: { page: 2, size: 25 },
})
// → { filters: [{ field: 'age', operator: 'gte', value: 18 }],
//     sort: [{ field: 'createdAt', direction: 'desc' }], page: 2, size: 25 }

An array of { field, operator } records under filter.where (or at the top level, which is where OR/AND groups serialize to) is read as the condition list itself. A real column named where is unaffected — filter[where]=lobby is still an ordinary equals on where.

AND / OR composition

Top-level filters in the filters array are implicitly ANDed. For richer boolean logic, nest AND/OR arrays on a ColumnFilter. The adapter maps these onto Lucid's grouped where/orWhere closures.

Nested OR

{
  filters: [
    {
      field: 'status',
      operator: 'equals',
      value: 'active',
      OR: [
        { field: 'name', operator: 'contains', value: 'sync' },
        { field: 'email', operator: 'contains', value: 'sync' },
      ],
    },
  ],
}

Produces roughly: WHERE (status = 'active' OR name ILIKE '%sync%' OR email ILIKE '%sync%').

Group nodes (no field of their own)

A ColumnFilter can be a pure group — an empty field plus an AND/OR array. This is what the client builder emits for .or() / .and(). The validator recognizes it and validates only the nested arrays:

{
  filters: [
    { field: '', operator: 'equals', value: undefined, OR: [
      { field: 'name', operator: 'contains', value: 'sync' },
      { field: 'email', operator: 'contains', value: 'sync' },
    ] },
  ],
}

Security

• Allow-list first. Operators only matter for fields that survive the allow-list in applyFilter. A condition on a disallowed field is dropped before it reaches the adapter. See Filter Classes.
• Field charset. validateColumnFilter rejects any field name not matching ^[a-zA-Z_][a-zA-Z0-9_.]*$, which blocks SQL injection through field names (dots are allowed for relation paths).
• Parameterized values. Every value goes through Lucid's parameter binding — no raw interpolation.
• LIKE escaping. All string operators escape %, _, and \ via escapeLike() before building the pattern, so user input can't inject wildcards.

import { escapeLike } from '@adonis-agora/filter'

escapeLike('50%_off') // '50\\%\\_off'

escapeLike(value, dialect?) takes an optional second argument, because the two major SQL families spell LIKE escaping differently:

The adapter always uses 'standard', which is what Postgres, MySQL and SQLite want. Pass 'mssql' only when you are building a pattern for SQL Server by hand.