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

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

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 [#relations-in-the-database]

### Relational databases [#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]

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 [#relations-in-prisma-client]

### Create records with nested relations [#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 [#retrieve-records-with-related-data]

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

### Connect existing records [#connect-existing-records]

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

## Types of relations [#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](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/one-to-one-relations) (also called 1-1 relations)
* [One-to-many](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/one-to-many-relations) (also called 1-n relations)
* [Many-to-many](https://www.prisma.io/docs/orm/v7/prisma-schema/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](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models) but has all [scalar fields](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models#scalar-fields) removed (except for the required [relation scalar fields](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations#relation-fields)) so you can focus on the [relation fields](#relation-fields).

> [!NOTE]
> This example uses [implicit many-to-many relations](https://www.prisma.io/docs/orm/v7/prisma-schema/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](https://www.prisma.io/docs/orm/v7/prisma-schema/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:

![The sample schema as an entity relationship diagram](https://www.prisma.io/img/orm/prisma-schema/data-model/relations/sample-schema.png)

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 [#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](https://www.prisma.io/docs/orm/v7/prisma-schema/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](https://www.prisma.io/docs/orm/v7/prisma-schema/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](https://www.prisma.io/docs/orm/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](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/introduction) simpler (because, for example, you have one fewer level of nesting inside of [nested writes](https://www.prisma.io/docs/orm/v7/prisma-client/queries/relation-queries#nested-writes)).

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

## Relation fields [#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 [#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](https://www.prisma.io/docs/orm/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]

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](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/self-relations)
* Defining many-to-many relations for MongoDB

> [!NOTE]
> [Implicit many-to-many relations](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/many-to-many-relations#implicit-many-to-many-relations) in relational databases do not require `@relation`.

## Disambiguating relations [#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`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/database-mapping): Learn how to map model and field names to database tables and columns
- [`External tables`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/externally-managed-tables): How to declare and use externally managed tables in Prisma ORM
- [`Indexes`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/indexes): How to configure index functionality and add full text indexes
- [`Models`](https://www.prisma.io/docs/orm/v7/prisma-schema/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`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/multi-schema): How to use Prisma ORM with multiple database schemas