Query operators reference
Every non-trivial where clause in prorm is expressed with operators. Write one
by name, inside the condition object for a column:User.findAll({ where: { age: { gte: 18 } } });
User.findAll({ where: { name: { like: 'A%' } } });
User.findAll({ where: { or: [{ age: { lt: 40 } }, { status: 'retired' }] } });
That is the form to reach for. Three others mean exactly the same thing and all
still work, so existing code needs no change:User.findAll({ where: { age: { $gte: 18 } } }); // $-prefixed
User.findAll({ where: { age: { [Op.gte]: 18 } } }); // Op symbol
User.findAll({ where: gte('age', 18) }); // helper function
All four compile to the same SQL on every engine:Op is exported from src/operators.ts (also
as Operators), alongside helper functions such as and, or, eq, like,
between.The examples below use a small shop schema — users, orders, products —
defined in Querying. The SQL is what each engine's
builder produced for the call, with values escaped in the way a define()
model sends them.A bare value is shorthand for equality: { name: 'John' } is identical to
{ name: { eq: 'John' } }.Note: the tables below name each operator with its $ prefix, because that is
the canonical internal form. Drop the $ and you have the plain name — $gte
is gte, $notILike is notILike.
Where a name is read as an operator#
Inside a column's condition — the { … } after a column name — every key is an
operator, so any operator name is understood there.At the top level of a where, keys are column names, so only the logical
operators and, or and not are read as operators. A column called
contains or like therefore keeps working:Not every builder renders every operator below. One it does not render is
refused with UnsupportedWhereError before the statement is sent, naming the
operator and the dialect, rather than dropped from the SQL — see
Query safety.User.findAll({ where: { contains: 'x' } }); // the column "contains"
User.findAll({ where: { and: [{ age: { gte: 18 } }, { active: true }] } }); // the AND operator
A column actually named and, or or not has to be reached another way —
they are SQL reserved words, so this is unlikely to come up.[!NOTE]
Before this, a bare name was silently treated as a value —
{ age: { gte: 18 } } compiled to age = '{"gte":18}', a query that ran and
quietly matched nothing rather than raising an error. If you have a query that
mysteriously returned no rows, this may be why.
Engine support at a glance#
The portable core — comparisons, in / notIn, between, null checks,
like / notLike and the logical operators — renders on every SQL engine.
Past that, support varies, and the fail-closed guard turns a gap into an error
rather than a missing condition. Captured from the builders:| Operator | PostgreSQL | MySQL | SQLite | SQL Server |
|---|
eq ne gt gte lt lte in notIn between isNull like notLike | yes | yes | yes | yes |
and or not (top level) | yes | yes | yes | yes |
isDistinctFrom | IS DISTINCT FROM | NOT (… <=> …) | IS NOT | (… IS NULL OR … <> …) |
iLike notILike | ILIKE | throws | LIKE | throws |
startsWith endsWith substring | ILIKE … ESCAPE | LIKE | LIKE … ESCAPE | throws |
regexp | ~ | REGEXP | needs a registered regexp function | throws |
iRegexp | ~* | throws | throws | throws |
not on a column | != | != | != | <> |
is: null / not: null | IS [NOT] NULL | IS [NOT] NULL | IS [NOT] NULL | IS [NOT] NULL |
col() / literal() as the value | yes | throws | yes | throws |
exists notExists inSubquery | yes | throws | yes | throws |
match | @@ plainto_tsquery | MATCH … AGAINST | MATCH (FTS5) | throws |
contains (JSON) | @> | throws | json_each subquery | throws |
keyExists | ? | throws | throws | throws |
Op.json(path) | #>> | JSON_EXTRACT | json_extract | JSON_VALUE |
arrayContains arrayOverlaps arrayAny | @> && = ANY | throws | throws | throws |
"throws" means UnsupportedWhereError (or a dialect error naming the
operator) before anything reaches the database — see
Query safety.Comparison operators#
The core comparison operators map directly to SQL comparison operators. Each takes a single value.User.findAll({ where: { status: { [Op.eq]: 'active' } } }); // status = ?
User.findAll({ where: { status: { [Op.ne]: 'banned' } } }); // status != ?
User.findAll({ where: { age: { [Op.gt]: 18 } } }); // age > ?
User.findAll({ where: { age: { [Op.gte]: 18 } } }); // age >= ?
User.findAll({ where: { age: { [Op.lt]: 65 } } }); // age < ?
User.findAll({ where: { age: { [Op.lte]: 64 } } }); // age <= ?
Helper equivalents: eq, ne, gt, gte, lt, lte. Each is called as helper(column, value):User.findAll({ where: and(gte('age', 18), lte('age', 64)) });
A realistic filter — "large orders that are not cancelled":await Order.findAll({ where: { total: { gte: 500 }, status: { ne: 'cancelled' } } });
ne does not match NULL — in SQL, NULL != 'cancelled' is unknown, not
true. When the column is nullable and you want "anything but", use
isDistinctFrom, which each engine spells differently:await Order.findAll({ where: { status: { [Op.isDistinctFrom]: 'paid' } } });
Any comparison value may be a column reference (col()) or a raw literal (Op.literal) instead of a bound value — see Column & literal references.import { col } from 'ts-prorm-orm';
Product.findAll({ where: { stock: { lte: col('reorderLevel') } } });
// "stock" <= "reorderLevel"
Range & set operators#
in / notIn take an array of candidate values. between / notBetween take a two-element [start, end] tuple.User.findAll({ where: { status: { [Op.in]: ['active', 'pending'] } } }); // status IN (?, ?)
User.findAll({ where: { status: { [Op.notIn]: ['banned', 'deleted'] } } }); // status NOT IN (?, ?)
User.findAll({ where: { age: { [Op.between]: [18, 65] } } }); // age BETWEEN ? AND ?
User.findAll({ where: { age: { [Op.notBetween]: [13, 17] } } }); // age NOT BETWEEN ? AND ?
Helpers: inOp (exported as in), notIn, between(column, start, end), notBetween(column, start, end).An empty list is legal and means what it says — in: [] matches nothing,
notIn: [] matches everything — rather than producing the invalid IN ():await Order.findAll({ where: { status: { in: [] } } }); // WHERE FALSE (1 = 0 on SQLite / SQL Server)
await Order.findAll({ where: { status: { notIn: [] } } }); // WHERE TRUE (1 = 1 on SQLite / SQL Server)
import { in as inOp, notIn, between } from 'ts-prorm-orm';
User.findAll({ where: inOp('status', ['active', 'pending']) });
User.findAll({ where: between('age', 18, 65) });
NULL checks#
isNull and isNotNull emit IS NULL / IS NOT NULL. In symbol form pass true; the value is only used to pick the direction ({ [Op.isNull]: false } compiles to IS NOT NULL).User.findAll({ where: { deletedAt: { [Op.isNull]: true } } }); // "deletedAt" IS NULL
User.findAll({ where: { email: { [Op.isNotNull]: true } } }); // "email" IS NOT NULL
Helpers isNull(column) and isNotNull(column) are the concise form:User.findAll({ where: isNull('deletedAt') });
User.findAll({ where: isNotNull('email') });
A null value is also turned into IS NULL — { status: null } compiles to
"status" IS NULL, never = NULL, which would match nothing.Op.is and Op.not also exist. { deletedAt: { [Op.is]: null } } is
"deletedAt" IS NULL and { deletedAt: { [Op.not]: null } } is
IS NOT NULL, on every engine in the table above. Op.not used as a field key
with a value negates equality ({ status: { [Op.not]: 'active' } } →
status != ?, <> on SQL Server); Op.not used as a top-level key negates a
whole condition (see Logical operators). Before 4.9.2,
MySQL and SQL Server refused is and not on a column with
UnsupportedWhereError.Pattern matching (LIKE)#
like / notLike are case-sensitive; iLike / notILike are the case-insensitive (ILIKE) variants. In symbol form you supply the full pattern including % wildcards.User.findAll({ where: { name: { [Op.like]: '%john%' } } }); // name LIKE '%john%'
User.findAll({ where: { name: { [Op.notLike]: 'test%' } } }); // name NOT LIKE 'test%'
User.findAll({ where: { email: { [Op.iLike]: '%@GMAIL.com' } } }); // email ILIKE '%@GMAIL.com'
The helper functions (like, notLike, iLike, notILike) wrap the value in %…% for you (contains matching), so you pass the bare term:User.findAll({ where: like('name', 'john') }); // name LIKE '%john%'
User.findAll({ where: iLike('name', 'john') }); // name ILIKE '%john%'
Case-insensitive matching is where the engines split. PostgreSQL has ILIKE;
SQLite's LIKE is already case-insensitive for ASCII, so iLike becomes plain
LIKE; MySQL and SQL Server have no builder for it and refuse:await User.findAll({ where: { email: { iLike: '%@GMAIL.com' } } });
UnsupportedWhereError: Cannot render WHERE condition at email.$iLike for mysql:
the operator '$iLike' is not implemented by its WHERE builder.
UnsupportedWhereError: Cannot render WHERE condition at email.$iLike for mssql:
the operator '$iLike' is not implemented by its WHERE builder.
On MySQL and SQL Server use plain like: their default collations are
case-insensitive already.Affix helpers — startsWith / endsWith / contains#
These helpers build one-sided or two-sided LIKE patterns without you writing %:import { startsWith, endsWith, substring, notStartsWith, notEndsWith } from 'ts-prorm-orm';
User.findAll({ where: startsWith('name', 'John') }); // name LIKE 'John%'
User.findAll({ where: endsWith('email', '@gmail.com') }); // email LIKE '%@gmail.com'
User.findAll({ where: substring('name', 'oh') }); // name LIKE '%oh%'
User.findAll({ where: notStartsWith('name', 'test') }); // name NOT LIKE 'test%'
User.findAll({ where: notEndsWith('file', '.tmp') }); // file NOT LIKE '%.tmp'
substring is the "contains" helper (identical to like). notSubstring is its negation.Unlike like, the affix helpers treat the term as text, not a pattern: a %
or _ in it is escaped. "Products whose name mentions 50%":await Product.findAll({ where: substring('name', '50%') });
UnsupportedWhereError: Cannot render WHERE condition at name.$substring for mssql:
the operator '$substring' is not implemented by its WHERE builder.
[!WARNING] The affix helpers are case-insensitive on PostgreSQL
startsWith, endsWith and substring compile to ILIKE on PostgreSQL but
LIKE elsewhere, so startsWith('sku', 'kb-') matches KB-01 there and —
under a case-sensitive collation — not on the others. Use { like: 'KB-%' }
when case must count.
Regular-expression operators#
regexp / notRegexp and their case-insensitive forms iRegexp / notIRegexp emit database-specific REGEXP clauses. Values may be a string or a RegExp.User.findAll({ where: { name: { [Op.regexp]: '^[A-Z]' } } }); // name REGEXP '^[A-Z]'
User.findAll({ where: { name: { [Op.notRegexp]: '[0-9]' } } }); // name NOT REGEXP '[0-9]'
Helpers: regexp, notRegexp, iRegexp, notIRegexp — each helper(column, pattern)."SKUs of the form KB- followed by digits":await Product.findAll({ where: { sku: { regexp: '^KB-[0-9]+$' } } });
[ORM] sqlite: $regexp on "sku" needs a REGEXP function, and SQLite has none built in.
Register one on the connection — getConnection().function('regexp', { deterministic: true },
(pattern, value) => (new RegExp(pattern).test(value) ? 1 : 0)) — or create the dialect with
{ regexp: true } for an engine that ships one.
UnsupportedWhereError: Cannot render WHERE condition at sku.$regexp for mssql:
the operator '$regexp' is not implemented by its WHERE builder.
iRegexp renders only on PostgreSQL (~*).Logical operators#
and, or, not combine or negate conditions. The helper functions are the ergonomic form: and(...conditions), or(...conditions), not(condition).// AND — all must hold
User.findAll({ where: and({ status: 'active' }, gte('age', 18)) });
// OR — any may hold
User.findAll({ where: or({ role: 'admin' }, { role: 'moderator' }) });
// NOT — negate a nested condition
User.findAll({ where: not({ status: 'banned' }) });
// Nested combination
User.findAll({
where: and(
{ status: 'active' },
or(gte('age', 65), lt('age', 18)),
),
});
All four engines render the nested combination the same way apart from
quoting:The where({ AND: [...] }) / where({ OR: [...] }) object form is also accepted and normalized to $and / $or. The Op.and / Op.or / Op.not symbols work as keys too, but the helper functions are clearer.Existence & subquery operators#
exists / notExists wrap a correlated subquery (a SQL string or Op.literal). Useful for semi-joins and anti-joins.import { exists, notExists, inSubquery, notInSubquery } from 'ts-prorm-orm';
// Users that have at least one order
User.findAll({ where: exists('SELECT 1 FROM orders WHERE orders.user_id = users.id') });
// Users with no orders (anti-join)
User.findAll({ where: notExists('SELECT 1 FROM orders WHERE orders.user_id = users.id') });
inSubquery(column, subquery) and notInSubquery(column, subquery) build IN (…) / NOT IN (…) against a subquery instead of a value array:User.findAll({ where: inSubquery('id', 'SELECT user_id FROM orders') });
User.findAll({ where: notInSubquery('id', 'SELECT user_id FROM banned_users') });
On PostgreSQL and SQLite these compile as written:MySQL and SQL Server refuse them with UnsupportedWhereError (their builders
do not render subquery predicates yet), so on those engines express the
semi-join as an include with required: true, or run
it through prorm.query().[!CAUTION]
The subquery string is spliced into the statement verbatim — it is not
parameterised. Never build it from request input.
For join-based exclusion there are also antiJoin(model, options) and its alias exclude(model, options), used inside include.Array operators (PostgreSQL)#
For PostgreSQL array columns:import { arrayContains, arrayContainedBy, arrayOverlaps, arrayAny, arrayAll } from 'ts-prorm-orm';
Product.findAll({ where: { tags: { [Op.arrayContains]: ['electronics', 'sale'] } } }); // tags @> ARRAY[...]
Product.findAll({ where: { tags: { [Op.arrayContainedBy]: ['a', 'b', 'c'] } } }); // tags <@ ARRAY[...]
Product.findAll({ where: { tags: { [Op.arrayOverlaps]: ['electronics', 'sale'] } } }); // tags && ARRAY[...]
Product.findAll({ where: { tags: { [Op.arrayAny]: 'electronics' } } }); // 'electronics' = ANY(tags)
Product.findAll({ where: { prices: { [Op.arrayAll]: { [Op.gt]: 100 } } } }); // 100 > ALL(prices)
With the values escaped in, the first compiles to
SELECT * FROM "products" WHERE "tags" @> ARRAY['electronics', 'sale']. The
other SQL engines have no array type and refuse these operators.Each has a matching helper (arrayContains, arrayContainedBy, arrayOverlaps, arrayAny, arrayAll). The generic Op.any / Op.all symbols (helpers anyOp/allOp, exported as any/all) build = ANY(...) / = ALL(...) comparisons.JSON / JSONB operators#
For JSON and JSONB columns. The most common are contains, containedBy, keyExists, and overlap:User.findAll({ where: { preferences: { [Op.contains]: { theme: 'dark' } } } }); // @> (PG) / JSON_CONTAINS (MySQL)
User.findAll({ where: { settings: { [Op.containedBy]: { theme: 'dark', lang: 'en' } } } }); // <@
User.findAll({ where: { data: { [Op.keyExists]: 'role' } } }); // key/index exists
User.findAll({ where: { tags: { [Op.overlap]: ['admin', 'vip'] } } }); // && (arrays overlap)
"Users who chose the dark theme", by containment:await User.findAll({ where: { preferences: { contains: { theme: 'dark' } } } });
UnsupportedWhereError: Cannot render WHERE condition at preferences.$contains for mysql:
the operator '$contains' is not implemented by its WHERE builder.
UnsupportedWhereError: Cannot render WHERE condition at preferences.$contains for mssql:
the operator '$contains' is not implemented by its WHERE builder.
To query a value at a JSON path, use Op.json(path) as a computed key. The
value can be a plain value, null, or an operator object such as
{ gt: 30 }, which then applies to the value at the path:await User.findAll({ where: { preferences: { [Op.json('$.theme')]: 'dark' } } });
Where the engine extracts the value as text (PostgreSQL, SQL Server, DuckDB),
it is cast to match what you compare it with: a number compares as a number,
a boolean as a boolean. Oracle and CockroachDB refuse Op.json with
UnsupportedWhereError.{ [Op.key]: { path, value } } is the same condition as
{ [Op.json(path)]: value }, and { [Op.key]: 'path' } matches rows where the
path holds a value. In TypeScript, write the key as [Op.key as any].PostgreSQL-specific JSONB operators are also available as symbols: jsonContains (@>), jsonHasKey (?), jsonbExtract (->), jsonbExtractText (->>), jsonbExtractPath (#>), jsonbExtractPathText (#>>), jsonConcat (||), jsonDelete (-), jsonDeletePath (#-), jsonPathExists (@?), jsonPathQuery (@@), and jsonTypeOf (json_typeof). A legacy Op.$json symbol also exists.User.findAll({ where: { data: { [Op.jsonHasKey]: 'role' } } }); // data ? 'role'
User.findAll({ where: { data: { [Op.jsonPathExists]: '$.address.city' } } }); // data @? '$.address.city'
Column & literal references#
Op.col(name) references another column; Op.literal(sql) embeds a raw SQL expression. Both are values, usable anywhere a comparison value is expected.col() is exported from the package root (Op.col is the operator symbol,
not this function).import { col, Op } from 'ts-prorm-orm';
// Compare two columns: products that need reordering
Product.findAll({ where: { stock: { [Op.lte]: col('reorderLevel') } } });
// "stock" <= "reorderLevel"
// Compare against a raw SQL expression
Order.findAll({ where: { createdAt: { [Op.lt]: Op.literal('CURRENT_TIMESTAMP') } } });
// "createdAt" < CURRENT_TIMESTAMP
// Set a column to a literal in an update
User.update({ lastLogin: Op.literal('NOW()') }, { where: { id: 1 } });
As an operand, col() and Op.literal() render on PostgreSQL and SQLite. The
MySQL and SQL Server builders would bind them as a JSON string, so the guard
refuses them there instead.Op.where(column, value) or Op.where(column, operator, value) builds an explicit clause, accepting either a column name or col(...) and string operators ('=', '!=', '>', 'like', 'between', 'is null', …) or operator symbols:import { col, Op } from 'ts-prorm-orm';
User.findAll({ where: Op.where(col('email'), 'ada@example.com') }); // "email" = 'ada@example.com'
Product.findAll({ where: Op.where(col('price'), '>', col('cost')) }); // "price" > "cost"
Used as the whole where, this form is rendered by the PostgreSQL builder
only; the others refuse it. The object form ({ price: { gt: col('cost') } })
is the portable spelling.Full-text search#
Op.match / helper match(column, term) build a database-appropriate full-text clause. For MySQL, Op.matchAgainst(columns, { mode }) and Op.matchFulltext(columns) produce MATCH … AGAINST … keys; for PostgreSQL, Op.toTsvector(column, config) and Op.toTsquery(query, config) build to_tsvector / to_tsquery expressions.Article.findAll({ where: match('body', 'javascript programming') });
Article.findAll({
where: { [Op.matchAgainst(['title', 'body'], { mode: 'boolean' })]: '+mysql -oracle' },
});
The same match() against the product catalogue, per engine:import { match } from 'ts-prorm-orm';
await Product.findAll({ where: match('name', 'wireless keyboard') });
UnsupportedWhereError: Cannot render WHERE condition at name.$match for mssql:
the operator '$match' is not implemented by its WHERE builder.
Each needs the engine's full-text machinery behind it: a FULLTEXT index on
MySQL, an FTS5 virtual table on SQLite, and ideally a tsvector index on
PostgreSQL — see SQL features.Spatial / geometric operators#
Symbol operators for PostGIS / MySQL spatial columns: stDistance, stWithin, stContains, stIntersects, stDWithin, stCrosses, stOverlaps, stTouches, stEquals, stIsValid.Place.findAll({
where: {
location: { [Op.stDWithin]: { from: 'POINT(-122.4 37.7)', distance: 1000, srid: 4326 } },
},
});
Range/interval operators strictLeft, strictRight, noExtendRight, noExtendLeft, adj, notAdj are likewise available as symbols for PostgreSQL range types.Expression & ordering helpers#
Op also carries expression builders used in attributes and order, not just where:import { col, Op } from 'ts-prorm-orm';
Product.findAll({ attributes: [[Op.cast(col('price'), 'DECIMAL(10,2)'), 'priceDecimal']] });
Order.findAll({ attributes: [[Op.extract('createdAt', 'year'), 'year']] }); // EXTRACT(YEAR FROM ...)
User.findAll({ order: [Op.asc('name'), Op.desc('createdAt')] }); // ORDER BY "name" ASC, "createdAt" DESC
User.findAll({ order: [Op.random()], limit: 5 }); // random sample
[!NOTE] How Op.extract is spelled per engine
PostgreSQL and MySQL render EXTRACT(YEAR FROM "createdAt"), SQL Server
DATEPART(year, [createdAt]), and SQLite
CAST(strftime('%Y', "createdAt") AS INTEGER). SQLite has no strftime()
form for millisecond, microsecond or isodow and refuses them.
Op.conv(value, from, to) builds a MySQL CONVERT / cast expression.Cheat sheet#
Grouped rather than listed, so you can find the row you want. Every operator
below is documented in full further up this page.Comparison#
| Operator | SQL |
|---|
Op.eq Op.ne | = ? · != ? |
Op.gt Op.gte | > ? · >= ? |
Op.lt Op.lte | < ? · <= ? |
Sets, ranges and null#
| Operator | SQL |
|---|
Op.in Op.notIn | IN (…) · NOT IN (…) |
Op.between Op.notBetween | BETWEEN ? AND ? · NOT BETWEEN ? AND ? |
Op.isNull Op.isNotNull | IS NULL · IS NOT NULL |
Pattern matching#
| Operator | SQL |
|---|
Op.like Op.notLike | LIKE ? · NOT LIKE ? |
Op.iLike Op.notILike | ILIKE ? · NOT ILIKE ? (PostgreSQL) |
startsWith endsWith substring | LIKE 'v%' · LIKE '%v' · LIKE '%v%' |
Op.regexp Op.iRegexp | REGEXP · case-insensitive REGEXP |
Logic and subqueries#
| Operator | SQL |
|---|
Op.and Op.or Op.not | AND · OR · NOT (…) |
Op.exists Op.notExists | EXISTS · NOT EXISTS |
inSubquery notInSubquery | IN (SELECT …) · NOT IN (SELECT …) |
Arrays — PostgreSQL#
| Operator | SQL |
|---|
Op.arrayContains Op.arrayContainedBy | @> · <@ |
Op.arrayOverlaps | && |
Op.any Op.all | = ANY(…) · ALL(…) |
JSON#
| Operator | SQL |
|---|
Op.contains Op.containedBy | @> · <@ |
Op.keyExists Op.overlap | key exists · && |
Op.json(path) Op.key | path extraction |
Op.jsonHasKey Op.jsonbExtract Op.jsonPathExists | ? · -> · @? (PostgreSQL) |
Expressions and ordering#
| Operator | SQL |
|---|
Op.col Op.literal Op.where | a column · raw SQL · a bare condition |
Op.cast Op.extract Op.conv | CAST · EXTRACT · CONVERT |
Op.asc Op.desc Op.random | ORDER BY … ASC · DESC · RANDOM() |
Op.match Op.matchAgainst | MATCH … AGAINST · @@ |
Op.stWithin Op.stDWithin Op.stIntersects | the ST_* spatial functions |
Next: Associations — the four relationship shapes and which side owns the foreign key.Querying — where these operators are used Modified at 2026-10-04 00:40:16