Swift: Using filters

A filter is a dictionary with a kind key and the operands that kind needs. KizunaSyncQuery builds the common ones; any other kind is written out as a dictionary and passed the same way. Filters are used by Fetch data to select rows and by Write with filters to choose the rows a write targets.

Supported filters#

KizunaSyncQuery has a helper for every kind in the table above. client.from("todos").select() chains the same names and sends the plan to the kernel.

Builder operators#

The select builder and the write builder also chain the supabase-swift operators below. Each one builds a filter kind the kernel evaluates, or a combination of the kinds above.

// TodoApp/TodoListView.swift (excerpt)
import KizunaSync

let travel = try await kizunasync.from("todos")
  .select()
  .likeAnyOf("title", patterns: ["%plane%", "%train%"])
  .notIn("id", values: hiddenIds)
  .filter("title", operator: "not.like", value: "draft*")
  .execute()

Ordering, limiting, and cardinality#

Usage#

// TodoApp/TodoListView.swift (excerpt)
import KizunaSync

let plan = KizunaSyncQuery.plan(
  filters: [
    KizunaSyncQuery.eq("done", false),
    KizunaSyncQuery.ilike("title", "%plane%")
  ],
  order: [KizunaSyncQuery.order("title")],
  limit: 20
)
let raw = try await kizunasync.query(table: "todos", plan: plan)
let also = try await kizunasync.from("todos").select().eq("done", false).ilike("title", "%plane%").limit(20).execute()

Two filters in one plan mean both must match. Use an explicit or to widen it:

// TodoApp/TodoListView.swift (excerpt)
import Foundation
import KizunaSync

let plan = KizunaSyncQuery.many(filters: [[
  "kind": "or",
  "filters": [
    KizunaSyncQuery.eq("done", false),
    ["kind": "is", "column": "done", "value": NSNull()]
  ]
]])

Unsupported operators#

The local evaluator implements the kinds in the tables above and nothing else. A kind outside that list, a malformed operand, or an unusable like pattern throws LOCAL_UNSUPPORTED rather than being forwarded to the database, because there is no request to forward it on.

The builders also carry the supabase-swift methods that have no local meaning, so a call compiles and the read or write that runs it throws LOCAL_UNSUPPORTED naming the reason: dryRun() (there is no server transaction to roll back; local writes enter the outbox), geojson() (PostGIS output has no local representation), explain(analyze:verbose:settings:buffers:wal:format:) (it describes the server query planner), and setHeader(name:value:) (a local read or write sends no HTTP request). retry(enabled:) returns the builder unchanged, because a local call makes no network attempt.

Supported query operators lists every postgrest-js method and option, with its status and its Swift name.

Notes#

The names and their meaning follow Supabase Using filters, and the modifiers follow Using modifiers. One local-first difference applies: they run over local SQLite, so they also see writes that have not reached the server. Comparisons and text search behave like their PostgREST counterparts on ordinary data. They are a local reimplementation rather than the Postgres operator, so collation-sensitive ordering and dictionary-based text search are out of scope.

Filters follow the three-valued logic of SQL. A comparison with a null or absent cell, or with a null value, answers unknown, a third value beside true and false. not leaves an unknown filter unknown, and and or combine unknown members the way Postgres does, and a read returns a row, or a write targets it, only when every filter of the plan is true on that row. is never answers unknown, so it is the filter that finds nulls.

Related reference#

• Fetch data
• Write with filters
• Update data
• Delete data
• Supported query operators
• Kotlin: Using filters
• JavaScript: Using filters