@field

Specifies which Record field stores the foreign key (FK) for a relation. Used on the PK side (forward relation) to tell Cerial where the FK value is stored.

Syntax

@field(fieldName)

The fieldName must reference a Record, Record?, or Record[] field in the same model.

When to Use

Every forward relation (PK side) requires @field() alongside @model(). It connects the virtual Relation field to the actual Record field that stores the FK value in the database.

model Post {
  id Record @id
  title String
  authorId Record                                  // FK storage field
  author Relation @field(authorId) @model(User)    // Forward relation
}

• @field(authorId) — tells Cerial that the authorId Record field stores the FK value.
• The Relation field itself is virtual — it is not stored in the database. Only the Record field (authorId) is stored.

Reverse Relations Don't Use @field

Reverse relations (non-PK side) use only @model() — no @field:

model User {
  id Record @id
  name String
  posts Relation[] @model(Post)                    // Reverse — no @field
}

Cerial automatically resolves the reverse relation by finding the matching forward relation on the Post model.

1

Example

model Profile {
  id Record @id
  bio String
  userId Record                                    // FK storage
  user Relation @field(userId) @model(User)        // Forward: required 1:1
}

const profile = await client.db.Profile.create({
  data: {
    bio: 'Software engineer',
    user: { connect: userId },
  },
});

1

Example

model Post {
  id Record @id
  title String
  authorId Record                                  // FK storage
  author Relation @field(authorId) @model(User)    // Forward: required
}

const post = await client.db.Post.create({
  data: {
    title: 'Hello World',
    author: { connect: userId },
  },
});

N

Example

In many-to-many relations, both sides use @field because both sides store FK arrays:

model Student {
  id Record @id
  name String
  courseIds Record[]
  courses Relation[] @field(courseIds) @model(Course)
}

model Course {
  id Record @id
  title String
  studentIds Record[]
  students Relation[] @field(studentIds) @model(Student)
}

Allowed On

Rules

• Every @field() must reference a Record, Record?, or Record[] field in the same model.
• Every Relation with @field() must also have @model().
• Reverse relations (Relation[] or Relation? without @field) only need @model().
• If multiple relations exist between the same two models, use @key to disambiguate.
• @nullable on the backing Record field affects relation behavior — disconnect sets NULL instead of NONE, and the default @onDelete action changes to SetNull instead of SetNone.

See Also

• @model — declares the target model of the relation
• @key — disambiguates multiple relations between the same models
• @onDelete — controls cascade behavior when related records are deleted