Overview

Cerial supports 15 built-in field types plus user-defined enums, tuples, objects, and literals. Each type maps to a specific SurrealDB type and TypeScript type.

Type Reference

Basic Types

String

Plain text. The most common field type.

model User {
  id Record @id
  name String
  bio String?
}

Email

An email address stored as a string with database-level validation. SurrealDB enforces the format via a string::is::email assertion.

model User {
  id Record @id
  email Email @unique
}

Int

Integer number — whole numbers only. SurrealDB truncates any decimal portion.

model Product {
  id Record @id
  stock Int
  rating Int?
}

Float

IEEE 754 double-precision floating-point number. Use when you need explicit decimal representation.

model Measurement {
  id Record @id
  temperature Float
  pressure Float?
}

Bool

Boolean value — true or false.

model User {
  id Record @id
  isActive Bool @default(true)
  isVerified Bool @default(false)
}

Date

Date/DateTime value. Stored as datetime in SurrealDB, represented as a JavaScript Date in TypeScript. Commonly used with timestamp decorators.

model Event {
  id Record @id
  startDate Date
  endDate Date?
  createdAt Date @createdAt
  updatedAt Date @updatedAt
}

Record & Relation

Record fields store foreign keys in SurrealDB's table:id format. They produce CerialId<T> on output and accept RecordIdInput<T> on input.

Relation fields are virtual — they don't store data but describe how to traverse between models. Forward relations use @field() and @model(), reverse relations use only @model().

model User {
  id Record @id
  posts Relation[] @model(Post)
}

model Post {
  id Record @id
  authorId Record
  author Relation @field(authorId) @model(User)
}

Record fields support typed IDs (Record(int) @id, Record(uuid) @id) for narrower type safety. See the Record and Relation pages for full details, or the Relations section for relationship patterns.

Special Types

These types have dedicated wrapper classes with rich APIs for construction, comparison, conversion, and SDK interop:

• Uuid — UUID identifiers with v4/v7 generation, comparison, and auto-generation decorators.
• Number — Auto-detect numeric type — accepts both integers and decimals.
• Duration — Time durations with unit accessors, comparison, and string parsing.
• Decimal — Arbitrary-precision decimals with immutable arithmetic for financial calculations.
• Bytes — Binary data with base64 encoding, Uint8Array conversion, and Buffer support.
• Geometry — GeoJSON-compatible geospatial data with 7 subtypes and point shorthand.
• Any — Pass-through type accepting any SurrealDB value — a typed recursive union, not bare TS any.

Arrays

Any field type can be made into an array by appending []:

model User {
  id Record @id
  tags String[]
  scores Int[]
  tokens Uuid[]
  history Duration[]
}

Array fields default to [] on create if not provided. Use the @set decorator for auto-deduplicated, sorted arrays:

model User {
  id Record @id
  tags String[] @set
}

@set generates set<T> in SurrealDB instead of array<T>, and the output type becomes CerialSet<T> (a branded array). Not all types support @set — see the array documentation for restrictions.

User-Defined Types

Beyond the 15 built-in types, fields can use user-defined types:

• Object — Embedded inline types with sub-fields (no id, no relations)
• Tuple — Fixed-length typed arrays with named or positional elements
• Enum — Named sets of string constants
• Literal — Union types combining specific values, broad types, and structured variants

enum Role { Admin, Editor, Viewer }

object Address {
  street String
  city String
}

tuple Color { r Int, g Int, b Int }

literal Priority { "low", "medium", "high" }

model User {
  id Record @id
  role Role
  address Address?
  favoriteColor Color?
  priority Priority @default("medium")
}