Drizzle ORM · Function

one

r.one.<table> defines a relation that returns one related object instead of an array. Configure its source and target columns, and optionally control requiredness, aliases, and conditional matching.

How it works

Use r.one.<table> inside defineRelations when a relation should resolve to one related record instead of an array. Specify the source and target columns, then use options such as optional, alias, or where to describe requiredness, naming, or conditional matching.

Syntax

r.one.<table>({ from, to, optional?, alias?, where? })

Parameters

Name	Type	Description
`from`	`relation column`	Source table and column for the relation.
`to`	`relation column`	Target table and column for the relation.
`optional`	`boolean`	Whether the related property is optional in the inferred type.
`alias`	`string`	Custom relation name used to distinguish relations.
`where`	`object`	Condition used to select matching related records.

Returns

A relation definition in which the named property resolves to one related object rather than an array.

Key points

Use r.one.<table> to model a relation whose result is one related object instead of a collection.
The from option names the source table and column where the relation begins.
Setting optional to false changes the inferred relation property to required.
Use alias to distinguish relations that would otherwise have the same target.
The where option supports conditional relation matching, including polymorphic relationships.

Common mistakes

Set optional: false only when the related entity is guaranteed to exist; it makes the relation property required in the inferred type.
A where condition changes which related record is selected and is useful for polymorphic relations.

Example: Define a required relation

const relations = defineRelations({ users, posts }, (r) => ({
  posts: {
    author: r.one.users({
      from: r.posts.ownerId,
      to: r.users.id,
      optional: false,
    }),
  },
}));

Defines a required one-to-one-style relation from each post to its author.

When to use it

Many-to-one relation

A post belongs to one author and the query result should expose one author object.

Disambiguate relations

Several relations point to the same target table and need distinct names.

Conditional or polymorphic relation

A relation should match only records satisfying a discriminator or status condition.

Interview questions

QWhat does r.one.users represent?

r.one.users declares that the relation returns one user object rather than an array. The from field identifies the source column, while to identifies the referenced column.

Follow-up: How can the relation be constrained to a subset of users? Add a where condition, such as a verified flag, to filter the related records.

QWhat is the purpose of optional: false?

optional: false makes the relation property required at the type level. Use it only when the related entity is guaranteed to exist.

Follow-up: What should be changed when the related entity may be absent? Omit the non-optional setting or configure the relation as optional so the type can represent absence.

QWhen would you use alias?

alias provides a custom name for the relation when defining relations. This helps distinguish relations when multiple relations target the same table.

Follow-up: How can relation selection be made conditional? Supply a where object to define the matching condition for the relation.

defineRelations
r.many
relational queries
alias
where

Source: Drizzle Relations. Checked 2026-10-16.

one