JavaScript: Using filters

A filter narrows the rows a read returns. It also picks the rows a write targets. The chain is the one supabase-js documents operator by operator under Using filters, with the same argument order and the same names. Every operator below becomes a node of the plan the Rust kernel evaluates against the local database. No request leaves the device, and no Postgres operator class decides the match.

Examples#

Narrow a read#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

const { data } = await kizunasync
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .ilike('title', '%plane%')

Pick the rows a write targets#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

export async function completeTodos(todoIds: string[]): Promise<void> {
  await kizunasync
    .from('todos')
    .update({ done: true })
    .in('id', todoIds)
}

Several patterns, a regular expression, and a null-safe comparison#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

const { data } = await kizunasync
  .from('todos')
  .select('id, title')
  .likeAnyOf('title', ['%plane%', '%train%'])
  .regexMatch('title', '^[A-Z]')
  .isDistinct('image_path', null)

A PostgREST-style clause list#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

const { data } = await kizunasync
  .from('todos')
  .select('*')
  .or('done.is.false,title.like.works%')

Parameters#

Chained filters combine with AND, in the order they were added.

The clause grammar that .or(), its AND counterpart, .filter(), and the negation above accept:

Unsupported operators#

These supabase-js operators exist on the builder as typed stubs so a call is a loud failure rather than a silent one. Each throws LOCAL_UNSUPPORTED naming the construct and the reason.

A projection is subject to the same rule: a columns string containing ( or : is a relational embed or a rename, which Fetch data rejects with the same code.

Errors#

Notes#

supabase-js forwards the .or() and .and() string to PostgREST without parsing it; Kizuna decodes it locally against the ten-operator subset listed in the clause grammar table above.

Filters follow the three-valued logic of SQL. A comparison with a null or absent cell, or with a null argument, answers unknown, a third value beside true and false. Negating an unknown clause leaves it unknown, .or() and .and() combine unknown clauses the way Postgres does, and a read returns a row, or a write targets it, only when the whole filter is true on that row. A .not('rank', 'in', [2, null]) therefore matches no row, the same answer rank not in (2, null) gives in Postgres. .is() never answers unknown, so it is the filter that finds nulls.

Filters that select rows for a write are a smaller set than the ones a read accepts: the write builder carries every operator in the Parameters table except the two search operators. A write also requires at least one filter that names rows; the kernel refuses an unfiltered write, or one whose filter matches every row by construction (an empty match({}), an empty likeAllOf() list), with LOCAL_UNSUPPORTED when it executes, rather than queuing it.

Both builders carry .includeDeleted(), with the same key and the same default as Fetch data: a row a softDelete column marks is excluded from a read and from write targeting until it is chained, so an update() or delete() whose filters would otherwise match that row skips it by default.

An update or delete resolves every row the filters match and applies the mutation to each in one apply_where call to the kernel. A write targeted by id, alone or alongside another filter, by .in('id', …), or inside .or('id.eq.…'), matches a row a pull delivered.

Nothing here consults Row Level Security. The local database holds the rows earlier pulls delivered. The server decides what those pulls contain. A policy runs when the push carries the queued write, as Validate writes shows. Postgres itself keeps the authoritative behavior for every operator. On mixed types, a value may therefore sort or match differently in the database than it does here. Same-type numbers compare numerically, and every other non-null pair compares as text.

A filtered write applies locally first. It then waits in the outbox until a run delivers it. Offline writes describes that optimistic path. How Kizuna works places it in the whole cycle.

Rows a peer wrote appear only after Sync or Pull once commits a pull boundary, so a filter can only see what the local store already has.

Related reference#

• Fetch data
• Update data
• Delete data
• Using transforms
• Swift: Using filters
• Kotlin: Using filters