Update a single record by unique field — with flexible return options, unset, and nested relations.

Updates a single record identified by a unique field. Provides flexible return options to control what the method gives back.

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'New Name' },
});
// user: User | null

Options

Option	Type	Required	Description
`where`	`UserUniqueWhereInput`	Yes	Must contain a unique field; may include additional conditions
`data`	`UserUpdateInput`	Yes	The fields and values to update
`unset`	`UserUnsetInput`	No	Fields to remove (set to NONE) in bulk
`select`	`UserSelect`	No	Narrow returned fields (not available with `return: 'before'`)
`include`	`UserInclude`	No	Include relations (not available with `return: 'before'`)
`return`	`undefined \| 'after' \| true \| 'before'`	No	Controls the return value

Return Options

`return` Value	Return Type	Description
`undefined` (default)	`User \| null`	The updated record, or `null` if not found
`'after'`	`User \| null`	Same as default — the post-update state
`true`	`boolean`	`true` if the record was found and updated, `false` if not
`'before'`	`User \| null`	The pre-update state of the record

Basic Usage

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'New Name' },
});
// user: User | null

By Unique Field

Any field decorated with @unique can be used in the where clause:

const user = await client.db.User.updateUnique({
  where: { email: 'john@example.com' },
  data: { name: 'John Doe' },
});
// user: User | null

With Select

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'John' },
  select: { id: true, name: true },
});
// user: { id: CerialId; name: string } | null

With Include

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'John' },
  include: { profile: true },
});
// user: (User & { profile: Profile }) | null

Boolean Return

When you only need to know whether the update succeeded:

const updated = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'John' },
  return: true,
});
// updated: boolean — true if found and updated, false if not

Get State Before Update

Retrieve the record as it was before the update was applied:

const oldUser = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'New Name' },
  return: 'before',
});
// oldUser: User | null (state before the update)

select and include are not available when using return: 'before'. The full model type is always returned. TypeScript will raise a compile-time error if you attempt to combine them.

Additional Where Conditions

You can include additional filter conditions alongside the unique field. The update only proceeds if all conditions are satisfied:

const user = await client.db.User.updateUnique({
  where: { id: '123', isActive: true },
  data: { name: 'Active User' },
});
// Only updates if BOTH id matches AND isActive is true
// Returns null if the record exists but isActive is false

Unsetting Fields

The unset parameter removes optional fields in bulk. The behavior is identical to updateMany — Unsetting Fields:

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: { name: 'Updated' },
  unset: { bio: true, address: { zip: true } },
});
// Updates name, removes bio and address.zip

Nested Relation Operations

Like updateMany, you can use connect, disconnect, and create on relation fields:

const user = await client.db.User.updateUnique({
  where: { id: '123' },
  data: {
    profile: { create: { bio: 'Hello world' } },
    tags: { connect: ['tag:typescript', 'tag:surreal'] },
  },
});

All the update features from updateMany — scalar updates, array operations, object merging, null vs NONE — work identically in updateUnique. The only difference is updateUnique targets a single record by a unique field and supports return and include options.

Return Value

Depends on the return option — see the return options table above.

`return`	Result
Default / `'after'`	`User \| null` (updated record or null if not found)
`true`	`boolean` (found and updated?)
`'before'`	`User \| null` (pre-update state)

updateUnique

On this page