Column Types

Look up every column type of the schema.ts builders and what it maps to in TypeScript and SQL.

There are a number of column types available which cover most common use cases. In schema.ts, each column is a builder from s:

schema.tsTypeScript typeSQL type
s.string()stringTEXT
s.boolean()booleanBOOLEAN
s.int()numberINTEGER
s.bigint()bigintBIGINT
s.float()numberREAL
s.timestamp()DateTIMESTAMP
s.bytes()Uint8ArrayBYTEA
s.uuid()string (row ID)UUID
s.array(s.string())string[]TEXT[]
s.enum("a", "b")"a" | "b"ENUM('a','b')
s.json()JsonValueJSON
s.json(schema)generated from the schemaJSON

Any column can be made nullable with .optional(). Options chain onto the builder: s.int().default(0), s.string().merge("text"), s.array(s.uuid()).optional().

s.int() values are signed 32-bit integers from -2,147,483,648 through 2,147,483,647. The runtime rejects fractional, non-finite, and out-of-range values before sending a write to the native engine. Use s.float() when a wider or fractional numeric range is required.

JSON columns are atomic. The entire value is replaced on every write. Use s.json() for untyped JSON, or s.json(schema) with a Zod-compatible schema to validate values and get a TypeScript type for them. generate writes the schema into jazz.app.json as JSON Schema; the generated type covers type, properties/required, items, enum, const, anyOf/oneOf and nullable, and other keywords give unknown. For structured data that needs per-field updates, use separate columns or a related table instead.

Declare relationships separately in the second argument to s.table, using s.rel("targetTable", "localUuidColumn") and s.reverse("sourceTable", "forwardRelationName"). UUID columns have no naming convention.

JSON pointer selections require a JSON column (s.json()). Text columns containing JSON text are not JSON columns. JSON is validated when written; pointer reads can therefore skip unrelated chunks in a large value. Array indices must be canonical (0, 1, …); /01 does not select array index 1, but can select an object property named "01".

Mergeable Text Columns

By default, a string column keeps one value: when two people edit it at the same time from the same starting point, one edit wins the whole field. For prose that several people edit at once, opt the column into a text merge strategy instead:

schema.ts
import { schema as s } from "jazz-tools";
​
export const schema = s.defineSchema({
docs: s.table({
title: s.string(), // one value: a concurrent edit replaces it whole
body: s.string().merge("text"),
notes: s.string().merge("markdown"),
page: s.string().merge("html"),
}),
});

The column still stores and syncs a plain string, so you read and write it like any other string, large values included. What changes is what happens when two people edit different parts of the text at once: Jazz merges the edits, so Alice adding a sentence at the top while Bob fixes a typo at the bottom keeps both changes.

The three formats differ in the pieces the merge works on. When both people replace the same piece, one replacement wins it whole rather than mixing the two:

StrategyKept whole
merge("text")Words, single spaces and punctuation marks. In scripts written without spaces (Chinese, Japanese, Thai and the like) and for emoji, each character. Accents, emoji modifiers and joined emoji stay with their character.
merge("markdown")Everything text keeps, plus runs of markup characters such as ** or ##, list markers like 1., and link targets like ](https://example.com).
merge("html")Everything text keeps, plus whole tags (<p class="intro">) and entities (&amp;).

There is one finer case. When both people type into the same word at once, each only adding or deleting letters at one spot, that word merges by character and both keep what they typed. If one person changes "color" to "colour" while another changes it to "colors", the result is "colours". This applies to words written only in scripts whose letters stand alone (Latin, Greek, Cyrillic, Chinese, Japanese kana, Hangul and the like). A word in other scripts, or one holding an emoji or a curly apostrophe (don’t), is merged whole.

The merge works on these pieces, not on a document tree: it keeps markup intact but does not check that the merged Markdown or HTML is well formed. See Collaborative text editing for how to use one with an editor.

A text merge column can be optional (s.string().optional().merge("text")). null means no text yet, and an empty string is ordinary text:

  • Two people adding text to a null column at the same time both keep their text, the earlier write first, just as they would on an empty string.
  • Clearing the column to null while someone else edits it is not merged: whichever write reaches the server later wins the whole value.

Transformed Columns

Experimental: Transformed columns are an early API and may change before the stable release.

A transformed column is stored as one type while your app reads and writes it as another. Call .transform(name, viewType) on the column: the column's own type is the stored type, viewType is the type your app sees. Then implement the transform under that name in jazz.computed.ts:

schema.ts
import { schema as s } from "jazz-tools";
​
export const schema = s.defineSchema({
tasks: s.table({
title: s.string(),
priority: s.int().transform("priorityLevel", s.enum("low", "medium", "high")),
}),
});
jazz.computed.ts
import type { AppTransforms } from "./jazz.generated";
​
export const transforms = {
priorityLevel: {
from: (score) => (score >= 8 ? "high" : score >= 4 ? "medium" : "low"),
to: (priority) => ({ low: 1, medium: 5, high: 10 })[priority],
},
} satisfies AppTransforms;

from converts a stored value into the value your app reads; to converts it back before inserts and updates. The view type carries no .optional(): the column says whether it is optional, and null is passed through. The generated bindings import jazz.computed.ts, so a transform the file declares but doesn't implement (or the other way round) fails to typecheck, and bindApp refuses it at runtime.

With this schema, priority is stored as an INTEGER, but TypeScript treats it as "low" | "medium" | "high" when reading and writing rows:

const { value: created } = db.insert(app.tasks, {
title: "Write launch notes",
priority: "high",
});
​
db.update(app.tasks, created.id, {
priority: "medium",
});
​
const task = await db.one(app.tasks.where({ id: created.id }));
task?.priority; // "low" | "medium" | "high"

Filters still use the stored column value, because arbitrary transforms cannot be translated into SQL predicates:

await db.all(app.tasks.where({ priority: { gte: 8 } }));

Each language implements the transforms itself; the stored values, migrations, permissions and indexes see only the stored type. Permissions can't refer to a transformed column's app-facing value.

A transform converts one value on its own: it can't read other columns of the row. (alpha.65's dependsOn option is gone, and jazz-tools upgrade refuses an app that uses it.) To derive a read-only value from several columns, use a computed field.

Computed Columns

A computed field is derived from other columns when a row is read. It has no stored column and is read-only. Declare it among the table's columns with s.computed(type, from), where from lists the columns it is computed from, and implement it in jazz.computed.ts:

schema.ts
import { schema as s } from "jazz-tools";
​
export const schema = s.defineSchema({
tasks: s.table({
title: s.string(),
score: s.int(),
priority: s.computed(s.enum("low", "medium", "high"), ["score"]),
}),
});
jazz.computed.ts
import type { AppComputed } from "./jazz.generated";
​
export const computed = {
tasks: {
priority: (row) => (row.score >= 8 ? "high" : row.score >= 4 ? "medium" : "low"),
},
} satisfies AppComputed;

The callback receives the from columns, read-only, with their app-facing values (after any column transforms). The returned row has a read-only priority property, typed TaskPriority in the generated module. The callback gets only the columns from names, so reading one it doesn't list is a type error.

A file can declare both: export computed and transforms from the same jazz.computed.ts.

Computed callbacks run synchronously in the TypeScript client and must be pure: do not mutate inputs or perform side effects. Jazz fetches the from columns whenever a read asks for the computed field, even when you don't select them, and leaves them out of the returned row unless you asked for them. Ordinary reads, transaction reads, included rows, relationship hops and subscriptions all do this; an update of a from column recomputes the result without writing a computed value.

Reads use complete from values. To return a partial value alongside a computed field, pass the partial projection together with the computed field name, for example app.tasks.select({ title: { from: 0, to: 10 } }, "priority"). A computation reading title still receives the complete title, so listing a large text, JSON or byte column in from loads the entire value.

Computed fields cannot be inserted, updated, filtered, sorted, indexed, used as relationship keys or used for branching. Filter and sort by stored columns. Permissions can't refer to computed fields; the ordinary permissions on their from columns still apply. Computed declarations don't change the stored schema, so adding or changing one needs no migration.