---
title: Many-to-One
description: Define many-to-one relationships connecting multiple records to a single related record
icon: arrow-left-to-line
---

A many-to-one relationship is what an **`s.toOne` slot paired with an `s.toMany`
slot** spells, read from the singular side. The same pair read from the
collection side is [one-to-many](/docs/schema/relations/one-to-many).

## Basic Example

```ts
import { s } from "viborm";

const post = s.model({
  id: s.string().id().ulid(),
  title: s.string(),
  authorId: s.string(),  // FK field
  author: s.toOne(() => user)
    .fields("authorId")
    .references("id"),
});

const user = s.model({
  id: s.string().id().ulid(),
  email: s.string().unique(),
  posts: s.toMany(() => post),  // Inverse side
});
```

## Characteristics

| Aspect | Value |
|--------|-------|
| Returns | Single object or null |
| FK location | On this model |
| Can be null | When a foreign-key field is `.nullable()` |
| Required by default | Yes |

## Configuration

The singular side of this pair owns the foreign key, so `.fields()` and
`.references()` are required here. See the [relation method
reference](/docs/schema/relations) and [referential
actions](/docs/schema/relations#referential-actions):

```ts
s.toOne(() => user)
  .name("writer")       // Pairing label, matched exactly on both endpoints
  .fields("authorId")   // FK field(s) on this model - required
  .references("id")     // Referenced field(s) on the target - required
  .onDelete("cascade")  // Referential action on delete
  .onUpdate("cascade")  // Referential action on update
```

Composite foreign keys pass multiple fields:

```ts
s.toOne(() => organization)
  .fields("orgId", "teamId")
  .references("id", "teamId")
```

The collection side needs no configuration — but it must exist. A `toOne` whose
target model declares nothing back is refused with `R002`, and an edge whose
endpoints both decline `.fields(...)` is refused with `FK004`.

## The foreign-key index

**You do not declare it.** `push` and `migrate` add an index over the `.fields()`
columns on every database — PostgreSQL, MySQL and SQLite all leave a foreign key
unindexed otherwise, and every `include`, relation filter and nested write reads
this side of the relation through those columns.

What is worth declaring is a **wider** index, when a query needs more than the
foreign key. The usual case is an include that orders and limits:

```ts
const post = s.model({
  id: s.string().id().ulid(),
  title: s.string(),
  createdAt: s.dateTime().now(),
  authorId: s.string(),
  author: s.toOne(() => user).fields("authorId").references("id"),
}).index(["authorId", "createdAt"]);
```

An index whose **leading** columns are the foreign key replaces the automatic
one rather than adding a second index over the same column — so put the foreign
key first. See [composite indexes for ordered
includes](/docs/schema/model#composite-indexes-for-ordered-includes).

One index does not count: a **partial** index (`.index([...], { where })`) holds
only the rows its predicate keeps, so it cannot serve the rows the predicate
excludes. The automatic foreign-key index is still added alongside it.

## Optionality

There is no `.optional()`. **The foreign-key scalar is the optionality**: mark it
`.nullable()` and the relation becomes empty-able, offers `disconnect`, and
accepts `setNull` actions.

```ts
authorId: s.string().nullable(),
author: s.toOne(() => user)
  .fields("authorId")
  .references("id")
```

## Complete Example

```ts
const post = s.model({
  id: s.string().id().ulid(),
  title: s.string(),
  content: s.string(),
  published: s.boolean().default(false),

  // Required author - the FK scalar is required
  authorId: s.string(),
  author: s.toOne(() => user)
    .fields("authorId")
    .references("id")
    .onDelete("cascade"),

  // Optional category - the FK scalar is nullable
  categoryId: s.string().nullable(),
  category: s.toOne(() => category)
    .fields("categoryId")
    .references("id")
    .onDelete("setNull"),
});
```

## Querying Many-to-One

```ts
// Include author when fetching post
const post = await client.post.findUnique({
  where: { id: "post_123" },
  include: { author: true },
});
// post.author: User

// Connect to an existing user on create (or set authorId directly)
const created = await client.post.create({
  data: {
    title: "My Post",
    author: {
      connect: { id: "user_123" }
    }
  }
});
```

See [To-One Relation Filters](/docs/client/filtering/relations-to-one) for filter operators and [Nested Writes](/docs/client/nested-writes) for `create`/`connect`/`connectOrCreate`.

## Self-Referential

The parent/child pattern — an entity pointing at another row of the same model —
is a singular slot paired with a collection slot on the same model:

```ts
// Employees and their manager
const employee = s.model({
  id: s.string().id().ulid(),
  name: s.string(),
  managerId: s.string().nullable(),
  manager: s.toOne(() => employee)
    .fields("managerId")
    .references("id"),
  reports: s.toMany(() => employee),
});

// Threaded comments
const comment = s.model({
  id: s.string().id().ulid(),
  content: s.string(),
  parentId: s.string().nullable(),
  parent: s.toOne(() => comment)
    .fields("parentId")
    .references("id"),
  replies: s.toMany(() => comment),
});
```

Both halves must be declared: a self relation with no partner slot is refused.
When a model carries **two** self relationships, give each pair a matching
`.name()` so the endpoints know which one they belong to.
