Expression builders

The standalone constructors for Expression nodes. Use them anywhere a where, orderBy, select, or projection accepts an expression — including via _raw on the typed where surface.

#Primitives — lit and fieldRef

5 lines


1import { lit, fieldRef } from 'zanith';
2 
3lit(42)                       // bound parameter — never interpolated
4lit('hello')                  // ditto
5fieldRef('User', 'email')     // reference a model field outside a query callback

lit(value) is the safe way to inject a literal. It always becomes a bound parameter — there is no path through these helpers that interpolates values into the SQL string. fieldRefis for the cases where you need to reference a field but aren't inside a typed .where(({ user }) => ...) callback.

#Control flow — caseWhen, coalesce, nullIf

13 lines


1import { caseWhen, coalesce, nullIf, lit, fieldRef } from 'zanith';
2 
3// CASE WHEN posts.viewCount > 1000 THEN 'high' ELSE 'low' END
4caseWhen(
5  [{ when: post.viewCount.gt(1000), then: lit('high') }],
6  { else: lit('low') },
7);
8 
9// COALESCE(nickname, email)
10coalesce([fieldRef('User', 'nickname'), fieldRef('User', 'email')]);
11 
12// NULLIF(name, '')   — turn empty strings into NULL for downstream COALESCE
13nullIf(fieldRef('User', 'name'), lit(''));

Helper	SQL	Use when
`caseWhen(branches, { else? })`	`CASE WHEN … THEN … [ELSE …] END`	Branching logic in projection or order key.
`coalesce([a, b, c])`	`COALESCE(a, b, c)`	First non-null wins. Often paired with `nullIf` to treat empty strings as missing.
`nullIf(a, b)`	`NULLIF(a, b)`	Return NULL when the two are equal. Useful before `coalesce`.

#Function escape hatch — fn

fn(name, args)is the escape hatch for any SQL function the engine doesn't wrap. Every argument is an Expression and gets compiled through the same parameter-binding path as the rest of the query.

7 lines


1import { fn, fieldRef, lit } from 'zanith';
2 
3// LOWER(email)
4fn('LOWER', [fieldRef('User', 'email')]);
5 
6// SUBSTRING(name FROM 1 FOR 3)  — note: SUBSTRING's syntax is special; for that one drop to raw SQL
7fn('REPEAT', [fieldRef('User', 'name'), lit(2)]);

#JSON helpers — standalone form

The chained .jsonText(...) form on field references covers most cases — see JSONB. The standalone helpers are for places where you already have an Expression in hand (a fn(...) call result, a parameter, or a field referenced via fieldRef).

Helper	Postgres operator
`jsonGet(field, key)`	`field->'key'`
`jsonGetText(field, key)`	`field->>'key'`
`jsonGetDeep(field, ['a','b','c'])`	`field#>'{a,b,c}'`
`jsonGetDeepText(field, ['a','b','c'])`	`field#>>'{a,b,c}'`
`jsonContains(field, value)`	`field @> value`
`jsonContainedBy(field, value)`	`field <@ value`
`jsonHasKey(field, key)`	`field ? key`
`jsonHasAllKeys(field, keys)`	`field ?& keys`
`jsonHasAnyKey(field, keys)`	`field ?\| keys`

#Array helpers

Helper	Postgres operator
`arrayContains(field, values)`	`field @> ARRAY[...]`
`arrayContainedBy(field, values)`	`field <@ ARRAY[...]`
`arrayOverlaps(field, values)`	`field && ARRAY[...]`
`arrayEquals(field, values)`	`field = ARRAY[...]`

4 lines


1import { arrayContains, lit, fieldRef } from 'zanith';
2 
3// tags @> ARRAY['rust', 'web']  — row's tags include both
4arrayContains(fieldRef('Post', 'tags'), [lit('rust'), lit('web')]);

#Range helpers

For Postgres range types — int4range, tstzrange, and friends.

Helper	Postgres operator
`rangeContains(range, value)`	`range @> value`
`rangeContainedBy(range, other)`	`range <@ other`
`rangeOverlaps(range, other)`	`range && other`
`rangeAdjacent(range, other)`	`range -\|- other`

4 lines


1import { rangeContains, fieldRef, lit } from 'zanith';
2 
3// active_period @> NOW()  — the row's tstzrange covers right now
4rangeContains(fieldRef('Subscription', 'activePeriod'), fn('now', []));

#Full-text search expression

6 lines


1import { textSearch, fieldRef, lit } from 'zanith';
2 
3textSearch(fieldRef('Post', 'body'), lit('rust web'), {
4  language: 'english',
5  parser: 'websearch',     // accept user-style queries ("foo bar" -baz)
6});

For most search workloads the higher-level search() builder is the right tool — it composes text + trigram + vector ranking in one query. textSearch is the primitive when you want one text predicate inside an otherwise-normal relational query.