---
title: Nested Writes
description: Create, update, and manage related records in a single operation
icon: layers
---

Nested writes let you create, connect, update, and delete related records in the
same call as their parent. Transaction-capable drivers run the whole operation
atomically, and generated IDs flow automatically from a parent to its children.
Drivers with native atomic batches send a nested write as one atomic batch
whenever no part of it has to hear the database before the next part can be
written. A write that must read between two of its own writes takes one batch
after another: each batch is atomic, the write as a whole is not. D1 documents
that [contract](/docs/drivers/sqlite/d1#relation-bearing-bulk-writes).

:::info
Link selectors — `connect`, `connectOrCreate.where`, `disconnect`, and `set` —
take **unique discriminators only**: a unique scalar or a complete compound
constraint. The extra scalar filters a top-level unique `where` accepts
([Narrowing a Unique Lookup](/docs/client/find-unique#narrowing-a-unique-lookup))
are not available there, a deliberate divergence from Prisma: a nested target is
located against its parent by primary key, and the extra predicate would collide
with that correlation.

To-many nested `update`, `upsert`, and `delete` accept an extended unique
selector: one unique discriminator plus optional scalar or relation filters.
The parent membership remains an additional mandatory correlation. A to-one
nested `update: { where, data }` envelope ([below](#update-nested)) is different
again: a to-one has exactly one related row, so its `where` is an ordinary
non-unique precondition that row must satisfy.
:::

Direct polymorphic relations use the same operation meanings but add a target
`type` and accept exactly one intent per payload. Their inverse slots — singular
`s.toOne` and plural `s.toMany` — use the ordinary singular and collection
shapes. See the
[polymorphic write matrices](/docs/schema/relations/polymorphic#write-the-direct-relation)
for the exact payloads and optionality rules.

To-one create payloads accept at most one active operation. A to-one **update**
payload accepts one composition — an optional vacate, one supplier, an optional
`update` of the supplied row — in either direction; see
[Combining operations on one to-one relation](#combining-operations-on-one-to-one-relation).
An empty ordinary to-one payload is a no-op, and `false` is inactive for boolean
operations. A supplied direct polymorphic payload must contain exactly one typed
intent. To-many payloads may combine operation kinds.

## Create Operations

### create

Create nested records:

```ts
// Create user with profile
const user = await client.user.create({
  data: {
    email: "alice@example.com",
    profile: {
      create: { bio: "Hello!" },
    },
  },
  include: { profile: true },
});

// Create user with multiple posts
const user = await client.user.create({
  data: {
    email: "bob@example.com",
    posts: {
      create: [
        { title: "Post 1" },
        { title: "Post 2" },
      ],
    },
  },
  include: { posts: true },
});
```

Consecutive entries of a one-to-many `create` list that carry no nested write of
their own and spell the same fields are written like nested `createMany`: one
multi-row INSERT per child table, in the order you wrote them, split at the
driver's bind-parameter budget. Each of these is still one statement per entry:
an entry with its own nested writes; a many-to-many `create` list (the junction
row needs each new key); `connectOrCreate` and `upsert` entries; and every entry
inside an array `$transaction([...])` or on drivers without interactive
transactions (such as D1).

### createMany (nested)

Use nested `createMany` on a to-many relation. Scalar-only rows keep the grouped
bulk insert. A row that contains another relation is compiled as an ordinary
fresh record subtree, and those record subtrees run left to right:

```ts
await client.user.create({
  data: {
    email: "alice@example.com",
    posts: {
      createMany: {
        data: [
          {
            title: "First",
            comments: { create: { body: "Nested one level deeper" } },
          },
          {
            title: "Second",
            category: { connect: { slug: "news" } },
          },
        ],
      },
    },
  },
});
```

Any no-transaction driver with native atomic batches also executes this nested
series when VibORM can re-assert the complete parent or relation membership in
every later write batch. A shape without that exact guard is refused before its
containing member writes. If reached inside a progressive root bulk call, earlier
root members can already be committed and are reported.

With `skipDuplicates`, a row that may need root-conflict suppression is one
subtree, and a transaction suppresses it inside a savepoint. A many-to-many row
whose flag is vacuous drops it, and one exact selector can use adopt-and-link.
A batch-only driver has no savepoint, so there a `createMany` with
`skipDuplicates` that is relation-bearing or nested under another write raises
`UnsupportedOperationError` during preparation before writes. Array transactions
also refuse suppression that requires an interactive member savepoint. Root scalar
SQL conflict skipping remains supported.

Explicit `$transaction([...])` arrays remain one indivisible batch. They do not
use this ordered progressive fallback.

On a **many-to-many** relation, each `createMany` member gets its own
`skipDuplicates` outcome in input order; a nameable row and an unnameable sibling
do not force one shared route. When one complete unique selector can name the row
that conflicted, the target insert is skipped and the join row is still written,
so the parent ends up linked to the row that was already there. When it cannot —
the target's key is database-generated and the row spells two independent
uniques, the conflict would fire on an index no `where` can spell, or the only
unique is compound with a `null` member — that member is suppressed whole: no
target, no join row, siblings unaffected, and the pre-existing row neither
rewritten nor linked. Later members observe the records earlier members wrote;
viborm does not pick a row to adopt on your behalf.

A nested write that needs a **database-generated key** to be read back — a child
whose foreign key points at the parent the same call is inserting — uses the
producer statement's exact output. SQLite-family and MySQL batches keep their
statement-local generated-ID lowering. PostgreSQL-family batches, including Neon
HTTP, use `RETURNING`: the key reaches the statements that need it inside the
same batch. A write that has to hear a value between two batches takes one batch
after another; those batches are not one atomic operation, so a later failure can
report partial committed progress. See
[Compatibility](/docs/client/compatibility#generated-keys-and-the-execution-substrate).

### connect

Connect to existing records:

```ts
// Connect existing category
const post = await client.post.create({
  data: {
    title: "My Post",
    category: {
      connect: { id: "cat_123" },
    },
  },
});

// Connect multiple tags
const post = await client.post.create({
  data: {
    title: "Tagged Post",
    tags: {
      connect: [
        { id: "tag_1" },
        { name: "featured" },
      ],
    },
  },
});
```

### connectOrCreate

Connect if exists, create if not:

```ts
const post = await client.post.create({
  data: {
    title: "My Post",
    category: {
      connectOrCreate: {
        where: { name: "Tech" },
        create: { name: "Tech" },
      },
    },
    tags: {
      connectOrCreate: [
        {
          where: { name: "tutorial" },
          create: { name: "tutorial" },
        },
        {
          where: { name: "beginner" },
          create: { name: "beginner" },
        },
      ],
    },
  },
});
```

## Update Operations

### update (nested)

A to-one nested update targets the currently related row. If there's no related row yet, the operation throws and nothing is written:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    profile: {
      update: { bio: "Updated bio" },
    },
  },
});
```

A to-one nested update also accepts a `{ where, data }` envelope. Unlike the
to-many form below, this `where` is an ordinary (non-unique) filter — a to-one
has exactly one related row, so the filter is a **precondition on that row**
rather than a way to pick between candidates. If the related row exists but
fails the filter, the whole operation is rejected and nothing is written:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    profile: {
      update: {
        where: { verified: true },
        data: { bio: "Updated bio" },
      },
    },
  },
});
```

The filter may reach through relations (`where: { badges: { some: { active: true } } }`)
and use `AND` / `OR` / `NOT`.

:::warning
The two spellings are told apart structurally: an object with a `data` key
  whose value is an object is the envelope; anything else is bare update data.

  If your related model owns a field literally named `data` — a JSON column
  being the usual case — that shape means two different things, and they write
  different columns: `update: { data: { label: "x" } }` could set the related
  row's `label`, or store `{ label: "x" }` in its `data`. Rather than pick one,
  viborm **refuses** it. Say which you meant by spelling the envelope out; an
  empty `where` constrains nothing:

  ```ts
  update: { where: {}, data: { label: "x" } }        // set the label column
  update: { where: {}, data: { data: { label: "x" } } } // store the document
  ```

  Only that one shape is affected. A non-object payload (`update: { data: 5 }`,
  a `Date`, a fixed-decimal `Decimal`, a `JsonNull` sentinel) is unambiguous and
  stays bare data, and a payload that doesn't mention `data` at all was never in
  question. The same applies to a field named `where`: reach it through the
  envelope's `data`.
:::

A fixed-decimal field takes a bare `Decimal | string` or an object with
exactly one of `set`, `increment`, `decrement`, `multiply`, or `divide`. Nested
writes use the same schema: an empty or multi-operation decimal bag is refused
before the relation write starts.

A to-many nested update targets a specific related row. The `where` must identify a row that belongs to the parent you're updating — targeting another record's row is rejected:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      update: {
        where: { id: "post_123" },
        data: { published: true },
      },
    },
  },
});
```

The to-many form also accepts an array of targeted updates:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      update: [
        {
          where: { id: "post_123" },
          data: { published: true },
        },
        {
          where: { slug: "draft-notes" },
          data: { archived: true },
        },
      ],
    },
  },
});
```

### updateMany (nested)

Nested `updateMany` is supported for to-many relations only. It combines the child filter with parent correlation. Matching zero rows is allowed and does not throw:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      updateMany: {
        where: { published: false },
        data: { archived: true },
      },
    },
  },
});
```

`updateMany` applies to to-many relations only. Scalar-only `data` stays on the
set-based bulk path. When `data` contains a relation, VibORM captures the
matching related rows once, sorts their complete primary keys, and runs the same
selected-record update compiler once per captured row:

```ts
await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      updateMany: {
        where: { published: false },
        data: {
          archived: true,
          auditEntries: { create: { action: "archive" } },
        },
      },
    },
  },
});
```

Matching zero rows remains a successful no-op. If more than one row is
captured, VibORM refuses a deeper child-held operation that would move the same
named target to several updated rows; one target row can store only one parent
membership.

A no-transaction driver with native atomic batches also executes this nested
series when VibORM can re-assert the complete parent or relation membership in
every later write batch. A shape without that exact guard is refused before its
containing member writes. If that member belongs to a progressive root bulk
call, earlier root members can already be committed; the error reports that
prefix.

### upsert (nested)

A to-one nested upsert updates the currently related row when one exists; otherwise it creates and connects a new related row:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    profile: {
      upsert: {
        create: { bio: "New bio" },
        update: { bio: "Updated bio" },
      },
    },
  },
});
```

A to-many nested upsert requires `where`, `create`, and `update`. If `where` matches a row already correlated to the parent, VibORM updates that row. If `where` matches no row, VibORM creates a new row correlated to the parent. If `where` matches a row owned by another parent, VibORM rejects instead of mutating it or creating a duplicate:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      upsert: {
        where: { slug: "launch-plan" },
        update: { title: "Launch plan v2" },
        create: {
          slug: "launch-plan",
          title: "Launch plan",
        },
      },
    },
  },
});
```

The to-many form also accepts an array of `{ where, create, update }` envelopes.

When a nested update or found-upsert re-enters the exact parent selected by an
enclosing upsert arm, VibORM keeps addressing that selected row. It does not
re-run the public selector. If the enclosing update changes the parent's primary
key, relation placement chooses the captured key before the root write or the
final complete key after it, so later work still follows the same row.

Two focused boundaries remain. Deleting or globally adopting the exact incoming
parent is not a selected update continuation. A re-entry that itself changes that
parent's primary key would have to publish a second final key back to the enclosing
compiler. VibORM refuses both cases instead of choosing a row or assignment order.

## Connection Management

### disconnect

Disconnect related records:

```ts
// Disconnect specific tags
const post = await client.post.update({
  where: { id: "post_123" },
  data: {
    tags: {
      disconnect: [{ id: "tag_1" }],
    },
  },
});

// Disconnect to-one (clear its stored membership)
const post = await client.post.update({
  where: { id: "post_123" },
  data: {
    category: { disconnect: true },
  },
});
```

An ordinary child-held relation exposes `disconnect` only when its physical
child membership can be cleared. A required child foreign key therefore omits
the key from its input. Junction relations always expose it because they remove
a join row instead of clearing child storage.

### set

Replace all connections:

```ts
// Replace all tags
const post = await client.post.update({
  where: { id: "post_123" },
  data: {
    tags: {
      set: [{ id: "tag_2" }, { id: "tag_3" }],
    },
  },
});

// Clear all tags
const post = await client.post.update({
  where: { id: "post_123" },
  data: {
    tags: { set: [] },
  },
});
```

For a junction relation, every selector supplies the complete target key,
including every member of a compound primary key. `set` and `connect` capture
and validate target membership and can perform work per target; a list does not
promise a single INSERT or one statement-trigger invocation. Each physical
statement respects the driver's bind-parameter budget. The transaction and
batch guarantees described above apply to the complete operation.

## Delete Operations

### delete (nested)

Delete related records. A nested `delete` throws when the target isn't found, including when it matches a row that belongs to another parent:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      delete: { id: "post_123" },
    },
  },
});

// Delete multiple
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      delete: [{ id: "post_1" }, { id: "post_2" }],
    },
  },
});
```

For a to-one relation, use `delete: true`. Deleting the related row needs an
empty slot to be valid, but it does not require clearable membership storage:
the child is removed rather than preserved. This is why a non-owning optional
one-to-one can allow `delete` while refusing `disconnect`.

### deleteMany (nested)

Nested `deleteMany` is supported for to-many relations only. It combines the filter with parent correlation. Matching zero rows is allowed and does not throw:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      deleteMany: {
        published: false,
        createdAt: { lt: new Date("2023-01-01") },
      },
    },
  },
});
```

The to-many form also accepts an array of filters:

```ts
const user = await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      deleteMany: [
        { published: false },
        { archived: true },
      ],
    },
  },
});
```

`deleteMany` applies to to-many relations only. For a to-one relation, use `delete: true`.

`deleteMany: {}` removes every related row. A filter that would remove every
related row only because its members are `undefined`
(`deleteMany: { id: postId }` with `postId` undefined) is refused with a
`ValidationError`, and so is the same `where` on a nested `updateMany`.

## Combining operations on one to-one relation

A to-one slot holds exactly one row, so a payload for it is read as one
composition rather than as a set of independent operations:

```text
{ vacate?, supplier, modify? }
```

- **vacate** — `disconnect: true` or `delete: true`
- **supplier** — `connect`, `connectOrCreate`, or `create`
- **modify** — `update`, applied to the row the supplier just supplied

The parts always run in that order, whatever order you spell them in, and the
whole thing is one atomic composition rather than three payloads that happen to
be applied in sequence:

```ts
// Replace the badge, and edit the incoming one — one call
await client.hub.update({
  where: { id: "h1" },
  data: {
    badge: {
      disconnect: true,
      connect: { id: "badge_new" },
      update: { tag: "primary" },
    },
  },
});
```

```ts
// Parent-held: the vacate and the supplier fold into ONE foreign-key value
await client.hub.update({
  where: { id: "h1" },
  data: { owner: { delete: true, create: { id: "o9", name: "fresh" } } },
});
```

That parent-held example is worth a note: the old row is deleted and the new one
written, but no transient `NULL` is ever assigned to the foreign key. The final
value is computed and written once, in the record's own `UPDATE`.

**Which compositions run.** Five replacement pairs are spellable on both
directions — `disconnect + connect`, `disconnect + connectOrCreate`,
`disconnect + create`, `delete + connect`, `delete + create`. `delete` beside
`connectOrCreate` is not an accepted pair, deliberately rather than by
omission. Any supplier may additionally carry an `update`, with or without a
vacate before it:

```ts
// Mint the badge, then edit THAT badge — one call, in this order
await client.hub.update({
  where: { id: "h1" },
  data: {
    badge: {
      create: { id: "badge_new", tag: "fresh", rank: 2 },
      update: { rank: { increment: 3 } }, // sees rank 2, writes 5
    },
  },
});
```

The modify always applies to the row the supplier supplied, and it applies
**after** that supplier has run — so a relative update counts from the value the
supplier wrote, and a `connectOrCreate` that finds an existing row edits the row
it adopted rather than one it minted. The update is an ordinary update: it can
carry relations of its own, nested `createMany` / `updateMany`, and another
supplier-plus-modify one level deeper.

When the supplier is a `create` — or a `connectOrCreate` that ends up creating —
the row does not exist while the call is being planned, so the engine locates it
after the fact, by the membership the supplier just established. That costs an
extra round trip on this relation only where the engine cannot tell from the
call itself whether the row answers the update's filter, and it needs a driver
that can either run an interactive transaction or submit native atomic batches. A
driver with neither capability declines before the supplier writes.

:::warning
One combination is spellable but declined before any write: parent-held
  `delete + connect`. `delete: true` names the row the parent's key reaches,
  and the `connect` gives that same key another row: the row to delete and the
  row to connect are not told apart. Split it into two calls. Parent-held
  `delete + create` is fine — nothing has to read the outgoing row, and neither
  does a producing supplier's `update`, which is why `delete + create + update`
  runs. On a child-held relation, `delete` beside a `connect` and an `update`
  runs too.

  On a parent-held relation, `create` or `connectOrCreate` beside an `update`
  is rejected at the type level, and stays so.
:::

Everything else stays refused at the type and validation boundary: two
suppliers, `upsert` beside another target intent, a vacate with an `update` and
no supplier, two vacates, and every ambiguous three-intent combination. A
relation that cannot spell a key simply does not offer it — a required to-one
has no `disconnect`, and a create root has no `update` — so those compositions
are not merely rejected there, they are unspellable.

## Combining operations on one to-many relation

A to-many payload may combine any of its verbs. They run in one fixed order,
clearing before adding, whatever order you spell them in:

1. `disconnect`, `delete`, `set`, `updateMany`, `deleteMany`
2. `update`, `upsert`
3. `connectOrCreate`, `connect`, `create`, `createMany`

Entries inside one verb run in the order you list them.

```ts
// Same result as { disconnect, connect }: t1 leaves, t2 joins
await client.post.update({
  where: { id: "p1" },
  data: { tags: { connect: [{ id: "t2" }], disconnect: [{ id: "t1" }] } },
});

// A spread payload follows the same order: `set` clears, then `connect` adds t1
await client.post.update({
  where: { id: "p1" },
  data: { tags: { ...{ connect: [{ id: "t1" }] }, set: [] } },
});
```

A target named by both a clearing verb and an adding verb meets the clearing
verb first. `{ connect: [{ id: "t1" }], disconnect: [{ id: "t1" }] }` leaves
`t1` connected. To remove a row, do not add it in the same call.

## What's not allowed

### Required relations

When membership storage is required, it cannot be cleared while preserving the
related record. `disconnect` is absent from that relation input:

```ts
// post.authorId is required, so the author cannot be disconnected.
await client.post.update({
  where: { id: "post_123" },
  data: {
    author: {
      disconnect: true,
    },
  },
});
```

This call fails input validation before query-engine compilation.

```ts
// post.authorId is required. set is valid only when every current post remains.
await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      set: [],
    },
  },
});
```

The second call reaches the set owner, but a departing-member guard rejects it
when the relation currently contains a post. A required `set` may retain all
current members and adopt new ones; `set: []` succeeds only when the relation is
already empty.

```ts
// Required foreign keys cannot be nulled through nested updateMany data.
await client.user.update({
  where: { id: "user_123" },
  data: {
    posts: {
      updateMany: {
        where: { archived: false },
        data: { authorId: null },
      },
    },
  },
});
```

### Update and delete inside a create

You can't update or delete related records inside a `create` (or the create branch of an `upsert`) — there's no existing related record yet:

```ts
await client.user.create({
  data: {
    email: "new@example.com",
    profile: {
      update: { bio: "No existing profile under a new user" },
    },
  },
});
```

```ts
await client.user.upsert({
  where: { email: "new@example.com" },
  create: {
    email: "new@example.com",
    posts: {
      deleteMany: { archived: true },
    },
  },
  update: {
    name: "Existing user",
  },
});
```

## Examples

### Complete User Registration

```ts
async function registerUser(data: {
  email: string;
  name: string;
  bio?: string;
  defaultTags?: string[];
}) {
  return client.user.create({
    data: {
      email: data.email,
      name: data.name,
      profile: {
        create: { bio: data.bio || "" },
      },
      settings: {
        create: {
          theme: "system",
          notifications: true,
        },
      },
      ...(data.defaultTags && {
        followedTags: {
          connectOrCreate: data.defaultTags.map(name => ({
            where: { name },
            create: { name },
          })),
        },
      }),
    },
    include: {
      profile: true,
      settings: true,
      followedTags: true,
    },
  });
}
```

### Update Post with Tags

```ts
async function updatePostTags(postId: string, tagNames: string[]) {
  return client.post.update({
    where: { id: postId },
    data: {
      tags: {
        set: [],  // Clear existing
        connectOrCreate: tagNames.map(name => ({
          where: { name },
          create: { name },
        })),
      },
    },
    include: { tags: true },
  });
}
```
