Filters and operators

Simple filters

addFilter() takes a field and one or more values.

qb.addFilter('status', 'published');
qb.addFilter('id', 1, 2, 3);         // multiple values
qb.deleteFilters('status');

How that renders is the driver’s business:

Strapi      filters[status][$eq]=published
PostgREST   status=eq.published
OData       $filter=status eq 'published'
Spatie      filter[status]=published

Values are encoded for you

Filter values, operator values and the search term are percent-encoded before they reach the URI, so pass them exactly as the user typed them:

qb.addFilter('name', '%foo & bar%');
// JSON:API   filter[name]=%25foo%20%26%20bar%25

Everything around the values stays literal — bracketed keys, operator syntax such as eq. or $eq:, and the , that joins several values. A comma inside a value is encoded as %2C, so it cannot be mistaken for a separator.

Strings are the only values encoded; numbers and booleans are emitted as they are. Field names, includes, sorts and the resource are yours rather than your users’, and are not encoded.

Bee aware

Don’t call encodeURIComponent() on a value yourself — it will be encoded twice. If you did that to work around unencoded values before 1.1.0, remove it when you upgrade.

Explicit operators

addFilterOperator() takes a FilterOperatorEnum.

import { FilterOperatorEnum } from '@qubeejs/core';

qb.addFilterOperator('price', FilterOperatorEnum.GTE, 10);
qb.addFilterOperator('price', FilterOperatorEnum.BTW, 10, 100);
qb.addFilterOperator('deletedAt', FilterOperatorEnum.NULL, true);

Available operators

Operator	Meaning	Notes
EQ	equals
NOT	not equal
GT / GTE	greater than / or equal
LT / LTE	less than / or equal
IN	matches any value	takes several values
BTW	between	requires exactly two values
NULL	is / is not null	requires exactly one boolean
CONTAINS	substring
ILIKE	case-insensitive match
SW	starts with
FTS / PHFTS / PLFTS / WFTS	full-text search variants	PostgREST

Arity is enforced

BTW and NULL have shape rules the library checks, so misuse fails loudly rather than producing an invalid request:

qb.addFilterOperator('price', FilterOperatorEnum.BTW, 10);
// InvalidFilterOperatorValueError: BTW requires exactly 2 values (min, max)

Bee aware

Enum values use the NestJS wire form ($eq, $btw). Each request strategy translates them into its own notation — PostgREST renders col=eq.val, not $eq. You never write the backend’s spelling yourself.

Operator support varies

Fifteen of the twenty drivers support explicit operators. The rest accept simple filters only:

qb.addFilterOperator('price', FilterOperatorEnum.GTE, 10);
// UnsupportedFilterOperatorError: The 'json-api' driver does not support filter operators.

Check the capability matrix before reaching for one.

The JSON:API driver is one of them by design. The specification reserves the filter parameter but deliberately leaves what goes inside it to each server, so a convention such as filter[name][ilike]=… belongs to your backend rather than to JSON:API. To target one, extend JsonApiRequestStrategy in your own driver — see Writing a driver.