Skip to main content
Every app gets a typed database client, generated from the workspace schema. Import it from zitejs/db:
The client is used inside backend workflows. The frontend never talks to the database directly. Each table is a property on zite, addressed by its SDK name in camelCase (zite.tickets, zite.timeSlots), with fully-typed record types. Read the generated .zite/db.ts to see the exact names and types.

Methods

A findOne by an id that doesn’t exist throws a NOT_FOUND ZiteError rather than returning undefined, and an id that isn’t a record UUID throws BAD_REQUEST. bulkCreate takes at most 100 records per call. More than that is rejected, so chunk larger imports.

Filters and sorting

Filters are objects keyed by field SDK name. A bare value means equality; an object applies an operator:
There is no eq or neq here: equality is the bare-value shorthand.
A filter key that isn’t a field SDK name is silently dropped, not rejected. The condition is discarded and the rest of the filter still applies, so the query comes back broader than you wrote. If every key was a typo, nothing is filtered and you get every row. Check names against .zite/db.ts. That includes createdAt: sort accepts it, but a createdAt filter is dropped. Filter on creation time in zite.sql() with the created_at column.
Sort is an array: sort: [{ field: 'createdAt', direction: 'desc' }]. Use fields: ['subject', 'status'] to fetch only the columns you need.
limit defaults to 500 and caps at 2,000 (hasMore tells you there are more). Passing a larger limit is an error, not a silent clamp. For counts, sums, group-bys, and joins, use zite.sql(). Aggregating in JavaScript over a capped result set gives wrong numbers on large tables.

Read-only SQL

zite.sql() runs a single read-only SELECT against the workspace database using human-readable SDK names:
Always use SDK names, never display labels. A wrong name is a runtime error, not a type error: Postgres lowercases unquoted names, which is why everything but the system columns must be double-quoted. The .zite/db.ts header lists the link tables for your workspace.
SELECT only. Pass runtime values through params ($1, $2, …), and never string-interpolate them into the query. Soft-deleted rows are excluded automatically.
Results are capped at 2,000 rows. The cap truncates silently rather than erroring, so check truncated and paginate in SQL rather than assuming you got everything. Queries time out after 10 seconds.

Also on the client

The generated zite object also exposes the workspace’s users:
Each user has id, name, firstName, lastName, email, and image. total is the match count before pagination. updateUserProfile changes firstName, lastName, and image (pass null to clear one). Email addresses can’t be changed.