Schema builders

s is a drop-in for Zod’s z that also records a SurrealQL type for each field. Use it anywhere you would use z. This page lists every builder and the TYPE it emits in DDL. For the conceptual side, see from schema to DDL; for the full type-by-type matrix with support status, see type mapping.

Primitives

Primitives

s.* SurrealQL TYPE DESCRIPTION
s.string() string A UTF-8 string.
s.boolean() bool A boolean.
s.number() number Any numeric value; use int/float for a specific kind.
s.literal(v) <value> An exact literal value.
s.enum([...]) <a> | <b> | … A union of string literals.

Numbers

s.int, s.float, and friends share Zod’s numeric base; the format decides the SurrealQL type.

Numbers

s.* SurrealQL TYPE DESCRIPTION
s.int() int An integer.
s.float() float A floating-point number.
s.int32() int A 32-bit integer (validated in app).
s.uint32() int An unsigned 32-bit integer (validated in app).
s.bigint() int A bigint, stored as a SurrealDB int.
s.decimal() decimal An arbitrary-precision Decimal (native, no conversion).

Native SurrealDB types

These map to SurrealDB’s built-in types. datetime, uuid, and bytes convert between app and wire values (see codecs); the rest pass through as their SDK class.

Native types

s.* SurrealQL TYPE DESCRIPTION
s.datetime() datetime Date (app) <-> DateTime (wire). Alias: s.date().
s.duration() duration A Duration (native, no conversion).
s.uuid() uuid string (app) <-> Uuid (wire).
s.bytes() bytes Uint8Array; normalizes a wire ArrayBuffer on decode.
s.file() file A FileRef (native, no conversion).
s.geometry(kind) geometry<kind> A Geometry of the given kind (or geometry if omitted).

String formats

Each format is a string that emits the matching ASSERT in DDL, so SurrealDB enforces the rule on write. They fall in two groups.

Backed by a Zod format:

Zod-backed formats

s.* SurrealQL TYPE DESCRIPTION
s.email() string ASSERT string::is_email($value).
s.url() string ASSERT a valid URL.
s.uuid() uuid See native types — uuid, not a plain string.
s.guid() / nanoid() / cuid() / cuid2() / ulid() / xid() / ksuid() string ASSERT the matching id format.
s.ipv4() / ipv6() / cidrv4() / cidrv6() string ASSERT the matching network format.
s.base64() / base64url() / e164() / jwt() / emoji() string ASSERT the matching format.

Plain string plus a string::is_* assertion:

Assertion-backed formats

s.* SurrealQL TYPE DESCRIPTION
s.alpha() / alphanum() / ascii() / numeric() string ASSERT the matching string::is_* check.
s.semver() / hexadecimal() string ASSERT the matching string::is_* check.
s.latitude() / longitude() string ASSERT a valid coordinate.
s.ip() / domain() string ASSERT a valid IP / domain.

Record links

s.* SurrealQL TYPE DESCRIPTION
User.record() record<user> A link to a user record, from the imported table def (carries its id type).
s.recordId([User, Service]) record<user | service> A link to one of several tables.
s.recordId() record A link to any table.

Structural types

Structural types

s.* SurrealQL TYPE DESCRIPTION
s.object({ ... }) object A nested object; each key becomes a DEFINE FIELD.
s.array(el, { max }) array<el> A list; optional max length.
s.set(el) set<el> A set of unique elements.
s.record(k, v) object A map keyed by k with values v.
s.tuple([...]) array A fixed-length, positionally-typed array.
s.union([...]) <a> | <b> A union of types.
s.discriminatedUnion(key, [...]) <a> | <b> A tagged union.
s.intersection(a, b) object Merged object types.
s.lazy(() => ...) (recursive) A self-referential schema.

s.union / s.intersection also have chainable forms: a.or(b) builds a union (a | b) and a.and(b) an intersection. See field methods.

Wrappers and escape hatches

Wrappers & escape hatches

s.* SurrealQL TYPE DESCRIPTION
.optional() option<T> The field may be absent.
.nullable() T | null The field may be null.
.array() array<T> A list of T.
s.any() / s.unknown() any Any value; opts out of a specific type.
s.coerce.* (per base) Coercing variant of a primitive.

Where to go next

  • Field methods — the $-clauses you chain onto these.
  • Type mapping — every type with support status and notes.
  • Definers — defineTable, defineRelation, and the rest.