@default

Sets a default value for a field when no value is provided on create. The value is stored in the database and persists across updates — it only applies when the field is absent during record creation.

Syntax

@default(value)

Supported Value Types

Basic Usage

model Task {
  id Record @id
  status String @default("pending")
  retryCount Int @default(0)
  priority Float @default(1.5)
  isActive Bool @default(true)
  timeout Duration @default(30m)
}

const task = await client.db.Task.create({
  data: {},
  // status: "pending", retryCount: 0, priority: 1.5,
  // isActive: true, timeout: CerialDuration('30m')
});

// Override defaults by providing explicit values
const urgent = await client.db.Task.create({
  data: { status: 'urgent', priority: 10 },
});

Fields with @default become optional in CreateInput — the database fills in the value when you omit them. They remain present in UpdateInput, WhereInput, and output types.

The @default(null) Pattern

@default(null) changes how omitted values are handled for nullable fields. Instead of the field being absent (NONE), it defaults to null:

Without @default(null):

model User {
  id Record @id
  bio String? @nullable       // optional and nullable, no default
}

// Omitting bio → NONE (field absent, not stored)
await client.db.User.create({ data: {} });

With @default(null):

model User {
  id Record @id
  bio String? @nullable @default(null)
}

// Omitting bio → null (field stored as null)
await client.db.User.create({ data: {} });
// bio is stored as null, queryable with { bio: { isNull: true } }

This distinction matters because SurrealDB treats NONE (field absent) and null (field present with null value) differently. See Optional Fields for details on NONE vs null semantics.

Object Fields

@default can be applied to fields within object definitions. The default value is applied at the database level via DEFINE FIELD ... DEFAULT.

object ContactInfo {
  email Email
  city String @default("Unknown")
}

model User {
  id Record @id
  contact ContactInfo
}

When an object has @default fields, Cerial generates a ContactInfoCreateInput type where those fields are optional:

// city defaults to "Unknown" when omitted
const user = await client.db.User.create({
  data: {
    contact: { email: 'alice@example.com' },
    // city will be "Unknown"
  },
});

Tuple Elements

@default can also be applied to individual tuple elements:

tuple Config {
  retries Int @default(3),
  timeout Float @default(30.0)
}

model Service {
  id Record @id
  config Config
}

When tuple elements have @default, they become optional in the create input — the database fills them in when absent.

Allowed On

Mutual Exclusions

@default cannot be combined with any of these decorators on the same field — each field gets one default/auto-generation strategy:

• @defaultAlways — use one or the other
• @createdAt, @updatedAt, @now — timestamp decorators each set their own default
• @uuid, @uuid4, @uuid7 — UUID auto-generation decorators set their own default

Summary