Overview

Tuples are fixed-length typed arrays defined with the tuple {} keyword in Cerial schemas. Unlike models, tuples have no id field and cannot participate in relations. Unlike objects, tuples produce array output — element order and count are fixed at schema time.

A User with a location Coordinate field stores the coordinate data as a typed array [40.7, -74.0] within the user record, not in a separate table.

tuple Coordinate {
  lat Float,
  lng Float
}

model User {
  id Record @id
  name String
  location Coordinate
}

const user = await client.db.User.create({
  data: {
    name: 'Jane Doe',
    location: [40.7128, -74.006],
  },
});

console.log(user.location);    // [40.7128, -74.006]
console.log(user.location[0]); // 40.7128 (lat)
console.log(user.location[1]); // -74.006 (lng)

Key Rules

1. No id field — Tuples have no identity. They exist only as part of their parent model.
2. Elements are comma-separated — Each element is separated by a comma within the tuple {} block.
3. Elements can be named or unnamed — Names are for input convenience only. Output is always a positional array.
4. Output is ALWAYS an array — [40.7, -74.0], never { lat: 40.7, lng: -74.0 }.
5. Input accepts both array and object form — When elements are named, you can use { lat: 40.7, lng: -74.0 } or [40.7, -74.0] as input.
6. Support a subset of decorators on elements — @nullable, @default, @defaultAlways, @createdAt, and @updatedAt are allowed. See Defining Tuples for the full list.
7. No OrderBy on tuple fields — Mixed element types make ordering ambiguous, so tuples are excluded from OrderBy types.
8. Per-element update via object form — Update individual elements without replacing the entire tuple.
9. Sub-field select only for tuples with object elements — TupleSelect is generated only when the tuple contains object elements at any depth.

Generated Types

Each tuple definition generates a set of TypeScript types:

Tuples do not generate OrderBy, Create, Include, or GetPayload types — those are exclusive to models.

Sections

• Defining Tuples — Schema syntax for declaring tuple types
• Tuple Fields on Models — Using tuples as required, optional, or array fields
• Select — Sub-field selection on tuple elements
• Where Filtering — Filtering by tuple element values
• Updating Tuples — Per-element updates and array operations