JavaScript: Fetch data

from(table).select(columns?, options?) returns a builder that reads local SQLite. Filters, .order(), .limit(), .range(), and the other modifiers chain on it, and awaiting the builder runs the read. The call signature matches .select() in supabase-js, including the count and head options.

Examples#

Basic#

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

const { data } = await kizunasync
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .order('title', { ascending: true })

Single row#

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

export async function loadTodo(todoId: string) {
  const { data } = await kizunasync.from('todos').select('*').eq('id', todoId).single()

  return data
}

React: useQuery and Vue: useQuery take the same chain ending in .single() or .maybeSingle() and hold that row, or null, in data.

One page of rows#

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

const PAGE_SIZE = 20

export async function loadPage(page: number) {
  const from = page * PAGE_SIZE
  const { data } = await kizunasync
    .from('todos')
    .select('id, title, done')
    .order('title')
    .range(from, from + PAGE_SIZE - 1)

  return data
}

Both ends of range(from, to) are inclusive and count from zero after the sort, so page 1 holds rows 20 through 39.

Count the matches#

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

export async function loadOpenPage() {
  const { data, count } = await kizunasync
    .from('todos')
    .select('id, title', { count: 'exact' })
    .eq('done', false)
    .range(0, 19)

  return { todos: data, openTodos: count }
}

count is the number of open todos before .range() cut the page. Pass head: true as well to get the count with data set to null.

Typed rows#

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

interface ITodo {
  id: string
  title: string
  done: boolean
}

export async function loadTodos(): Promise<ITodo[]> {
  const { data } = await kizunasync.from('todos').select('id, title, done').returns<ITodo[]>()

  return data
}

returns() and overrideTypes() change only the static type, as in supabase-js; the rows are the same rows.

CSV text#

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

export async function exportTodos(): Promise<string> {
  const { data } = await kizunasync.from('todos').select('id, title, done').order('title').csv()

  return data
}

Stop a read the screen no longer needs#

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

export function loadTodosUntil(signal: AbortSignal) {
  return kizunasync.from('todos').select('id, title').abortSignal(signal)
}

When signal aborts before the read settles, the promise rejects with the signal's reason and the rows are discarded.

Parameters#

The builder carries the filters on Using filters plus the modifiers below. All of them join the plan the kernel evaluates when the read executes.

Returns#

Promise<ISelectResult> by default, and the two terminals narrow it.

Errors#

This method throws its errors rather than returning them, so wrap the await in try when a query can violate one of the conditions above.

Notes#

Every read is served from the local database, and there is no network fallback: rows a peer wrote appear only after a pull commits a boundary, which the automatic loop runs on its own and Sync or Pull once runs on demand. Rows your own app wrote are visible immediately, before the outbox drains, which is the optimistic path Offline writes describes. How Kizuna works places the local read in the whole cycle.

The server decides Row Level Security, never the device. The local store holds what earlier pulls delivered, so the server decided visibility when those rows arrived. The policies themselves stay in Supabase.

Supported query operators lists every postgrest-js method and option with its status in the JavaScript, Swift, and Kotlin app clients, and the reason each unsupported one is refused. An unsupported call throws a typed TEngineError with code LOCAL_UNSUPPORTED, from kizunasync, and nothing falls back to the network.

The app client selects the engine when its first use opens it, as Initializing describes. It reads a driver-carried engine transport first, which is how the browser runs Rust as WebAssembly in its worker. Failing that, it runs Rust through a linked UniFFI binding or the N-API addon. In every case the driver reports databasePath. A file path lets the kernel open the same database. null or the literal ':memory:' creates a private in-memory database. Where no binding resolves, that first call rejects with a typed TEngineError with code ENGINE_UNAVAILABLE that names what to install, rather than downgrading to another engine, and so does every later call. The kernel runs the conformance corpus for the supported local subset, and Project status records which runtime reaches it how.

An update or delete whose filter matches no local row is a no-op with no error, matching supabase-js zero-row behavior. Every supported filter is evaluated by the kernel over the local SQLite store, and none of them reaches the network. Offline writes covers what happens to the mutation those builders queue.

Example: filters offline#

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

const { data } = await kizunasync
  .from('todos')
  .select('id, title, rank')
  .gte('rank', 2)
  .or('done.eq.false,title.ilike.%urgent%')
  .order('rank')
  .limit(20)

Example: handling LOCAL_UNSUPPORTED#

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

try {
  await kizunasync.from('todos').select().regexMatch('title', '(works) \\1')
} catch (error) {
  if (error instanceof TEngineError && error.code === EEngineErrorCode.LOCAL_UNSUPPORTED) {
    // the local regex engine has no backreferences, so match the title with a simpler pattern
  }
}

Related reference#

• Insert data
• Using filters
• Supported query operators
• Sync
• React: useQuery
• Vue: useQuery
• Swift: Fetch data
• Kotlin: Fetch data