# Relations (Prisma ORM v7) (/docs/orm/v7/prisma-schema/data-model/relations)

A relation is a connection between two models in the Prisma schema. This page explains how you can define one-to-one, one-to-many and many-to-many relations in Prisma

Location: ORM > v7 > Prisma Schema > Data Model > Relations

A relation is a _connection_ between two models in the Prisma schema. For example, there is a one-to-many relation between `User` and `Post` because one user can have many blog posts:

```prisma
model User {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  author   User @relation(fields: [authorId], references: [id])
  authorId Int  // Foreign key connecting Post to User
  title    String
}
```

At a Prisma ORM level, the `User` / `Post` relation consists of:

- **Relation fields** (`author` and `posts`): Define connections at Prisma ORM level, do not exist in the database
- **Relation scalar field** (`authorId`): The foreign key that exists in the database

## Relations in the database

### Relational databases

In SQL, you use a _foreign key_ to create a relation between two tables:

- A foreign key column (`authorId`) in `Post` references the primary key (`id`) in `User`

```prisma
author     User        @relation(fields: [authorId], references: [id])
```

> \[!NOTE]
> Relations in the Prisma schema represent relationships that exist between tables in the database.

### MongoDB

MongoDB uses a normalized data model design where documents reference each other by ID:

```json
// User document
{ "_id": { "$oid": "60d5922d00581b8f0062e3a8" }, "name": "Ella" }

// Post documents referencing the user
{ "_id": "...", "title": "How to make sushi", "authorId": { "$oid": "60d5922d00581b8f0062e3a8" } }
```

If using `ObjectId`, add `@db.ObjectId` to both the model ID and relation scalar field:

```prisma
model Post {
  id       String @id @default(auto()) @map("_id") @db.ObjectId
  author   User   @relation(fields: [authorId], references: [id])
  authorId String @db.ObjectId
}
```

## Relations in Prisma Client

### Create records with nested relations

```ts
const userAndPosts = await prisma.user.create({
  data: {
    posts: {
      create: [{ title: "Prisma Day 2020" }, { title: "How to write a Prisma schema" }],
    },
  },
});
```

### Retrieve records with related data

```ts
const getAuthor = await prisma.user.findUnique({
  where: { id: "20" },
  include: { posts: true },
});
```

### Connect existing records

```ts
await prisma.user.update({
  where: { id: 20 },
  data: {
    posts: { connect: { id: 4 } },
  },
});
```

## Types of relations

There are three different types (or [cardinalities](https://en.wikipedia.org/wiki/Cardinality_\(data_modeling\)\)) of relations in Prisma ORM:

- [One-to-one](/guides/prisma-schema-v7-data-model-relations-one-to-one-relations) (also called 1-1 relations)
- [One-to-many](/guides/prisma-schema-v7-data-model-relations-one-to-many-relations) (also called 1-n relations)
- [Many-to-many](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations) (also called m-n relations)

The following Prisma schema includes every type of relation:

- one-to-one: `User` ↔ `Profile`
- one-to-many: `User` ↔ `Post`
- many-to-many: `Post` ↔ `Category`

#### Relational databases

```prisma
model User {
  id      Int      @id @default(autoincrement())
  posts   Post[]
  profile Profile?
}

model Profile {
  id     Int  @id @default(autoincrement())
  user   User @relation(fields: [userId], references: [id])
  userId Int  @unique // relation scalar field (used in the `@relation` attribute above)
}

model Post {
  id         Int        @id @default(autoincrement())
  author     User       @relation(fields: [authorId], references: [id])
  authorId   Int // relation scalar field  (used in the `@relation` attribute above)
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[]
}
```

#### MongoDB

```prisma
model User {
  id      String   @id @default(auto()) @map("_id") @db.ObjectId
  posts   Post[]
  profile Profile?
}

model Profile {
  id     String @id @default(auto()) @map("_id") @db.ObjectId
  user   User   @relation(fields: [userId], references: [id])
  userId String @unique @db.ObjectId // relation scalar field (used in the `@relation` attribute above)
}

model Post {
  id          String     @id @default(auto()) @map("_id") @db.ObjectId
  author      User       @relation(fields: [authorId], references: [id])
  authorId    String     @db.ObjectId // relation scalar field  (used in the `@relation` attribute above)
  categories  Category[] @relation(fields: [categoryIds], references: [id])
  categoryIds String[]   @db.ObjectId
}

model Category {
  id      String   @id @default(auto()) @map("_id") @db.ObjectId
  posts   Post[]   @relation(fields: [postIds], references: [id])
  postIds String[] @db.ObjectId
}
```

> \[!NOTE]
> This schema is the same as the [example data model](/guides/prisma-schema-v7-data-model-models) but has all [scalar fields](/guides/prisma-schema-v7-data-model-models#scalar-fields) removed (except for the required [relation scalar fields](/guides/prisma-schema-v7-data-model-relations#relation-fields)) so you can focus on the [relation fields](#relation-fields).

> \[!NOTE]
> This example uses [implicit many-to-many relations](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations#implicit-many-to-many-relations). These relations do not require the `@relation` attribute unless you need to [disambiguate relations](#disambiguating-relations).

Notice that the syntax is slightly different between relational databases and MongoDB - particularly for [many-to-many relations](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations).

For relational databases, the following entity relationship diagram represents the database that corresponds to the sample Prisma schema:

<img src="https://www.prisma.io/img/orm/prisma-schema/data-model/relations/sample-schema.png" alt="The sample schema as an entity relationship diagram">

For MongoDB, Prisma ORM uses a [normalized data model design](https://www.mongodb.com/docs/manual/data-modeling/), which means that documents reference each other by ID in a similar way to relational databases. See [the MongoDB section](#mongodb) for more details.

### Implicit and explicit many-to-many relations

Many-to-many relations in relational databases can be modelled in two ways:

- [explicit many-to-many relations](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations#explicit-many-to-many-relations), where the relation table is represented as an explicit model in your Prisma schema
- [implicit many-to-many relations](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations#implicit-many-to-many-relations), where Prisma ORM manages the relation table and it does not appear in the Prisma schema.

Implicit many-to-many relations require both models to have a single `@id`. Be aware of the following:

- You cannot use a [multi-field ID](/guides/reference-6-v7-reference-prisma-schema-reference)
- You cannot use a `@unique` in place of an `@id`

To use either of these features, you must set up an explicit many-to-many instead.

The implicit many-to-many relation still manifests in a relation table in the underlying database. However, Prisma ORM manages this relation table.

If you use an implicit many-to-many relation instead of an explicit one, it makes the [Prisma Client API](/guides/prisma-client-v7-setup-and-configuration-introduction) simpler (because, for example, you have one fewer level of nesting inside of [nested writes](/guides/prisma-client-v7-queries-relation-queries#nested-writes)).

If you're not using Prisma Migrate but obtain your data model from [introspection](/guides/prisma-schema-v7-introspection), you can still make use of implicit many-to-many relations by following Prisma ORM's [conventions for relation tables](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations#relation-table-conventions).

## Relation fields

Relation fields are fields on a Prisma model whose type is another model (not a scalar type). Every relation needs exactly two relation fields, one on each model.

```prisma
model User {
  id    Int    @id @default(autoincrement())
  posts Post[] // relation field
}

model Post {
  id       Int    @id @default(autoincrement())
  author   User   @relation(fields: [authorId], references: [id]) // annotated relation field
  authorId Int    // relation scalar field (foreign key)
}
```

**Key concepts:**

- `posts` and `author` are relation fields (exist at Prisma ORM level only)
- `authorId` is the relation scalar field (exists in the database as foreign key)

### Annotated relation fields

Relations annotated with `@relation` attribute (one-to-one, one-to-many, and many-to-many for MongoDB) represent the side that stores the foreign key:

```prisma
author     User    @relation(fields: [authorId], references: [id])
authorId   Int     // relation scalar field
```

The `references` argument names the field on the other model that the relation scalar field points to. In the example above, `authorId` on `Post` holds the value of `id` on `User`, so `fields` lists the field on this model and `references` lists the field it points to on the related model.

Both arguments are lists because a relation can span more than one field. When the related model has a composite ID or a composite unique constraint, `fields` and `references` each list the same number of fields in the same order, for example `@relation(fields: [firstName, lastName], references: [firstName, lastName])`. The fields in `references` must be the related model's `@id` or a `@unique` field, or together form its `@@id` or `@@unique`. MongoDB does not support `@@id`, so on MongoDB the referenced fields are an `@id`, a `@unique`, or a `@@unique`. See the [`@relation` reference](/guides/reference-6-v7-reference-prisma-schema-reference#relation) for every argument the attribute accepts.

**Naming convention:** Relation scalar fields typically use the pattern `fieldName` + `Id` (e.g., `author` → `authorId`).

## The `@relation` attribute

The `@relation` attribute is required when:

- Defining one-to-one or one-to-many relations
- Disambiguating multiple relations between the same models
- Defining [self-relations](/guides/prisma-schema-v7-data-model-relations-self-relations)
- Defining many-to-many relations for MongoDB

> \[!NOTE]
> [Implicit many-to-many relations](/guides/prisma-schema-v7-data-model-relations-many-to-many-relations#implicit-many-to-many-relations) in relational databases do not require `@relation`.

## Disambiguating relations

When you have two relations between the same models, use the `name` argument in `@relation` to disambiguate:

```prisma
model User {
  id           Int     @id @default(autoincrement())
  writtenPosts Post[]  @relation("WrittenPosts")
  pinnedPost   Post?   @relation("PinnedPost")
}

model Post {
  id         Int     @id @default(autoincrement())
  author     User    @relation("WrittenPosts", fields: [authorId], references: [id])
  authorId   Int
  pinnedBy   User?   @relation("PinnedPost", fields: [pinnedById], references: [id])
  pinnedById Int?    @unique
}
```

The `name` must be the same on both sides of the relation.

## Related pages

- [`Database mapping`](/guides/prisma-schema-v7-data-model-database-mapping): Learn how to map model and field names to database tables and columns
- [`External tables`](/guides/prisma-schema-v7-data-model-externally-managed-tables): How to declare and use externally managed tables in Prisma ORM
- [`Indexes`](/guides/prisma-schema-v7-data-model-indexes): How to configure index functionality and add full text indexes
- [`Models`](/guides/prisma-schema-v7-data-model-models): Learn about the concepts for building your data model with Prisma: Models, scalar types, enums, attributes, functions, IDs, default values and more
- [`Multi-schema`](/guides/prisma-schema-v7-data-model-multi-schema): How to use Prisma ORM with multiple database schemas

## Related pages

- [Authentication & Tools](./authentication-tools-index.md)
- [Build](./build-index.md)
- [Changelog](../changelog.md)
- [Concepts](./concepts-index.md)
- [Console commands](./console-commands-index.md)
- [Contract Authoring](./contract-authoring-index.md)
- [Core Concepts](./core-concepts-index.md)
- [Data Modeling](./data-modeling-index.md)
- [Database](./database-index.md)
- [DB commands](./db-commands-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.