• Start
Sign In

Languages

/

JavaScript

/

API Reference

/

Query builders

UpdatePromise

UpdatePromise provides chainable methods for configuring UPDATE operations.

The UpdatePromise class provides a chainable interface for configuring UPDATE operations before execution. It extends Promise, allowing you to await it directly or chain configuration methods.

Returned by: SurrealQueryable.update()

Source: query/update.ts

Type parameters

  • T - The result type

  • I - The input type for record data

  • J - Boolean indicating if result is JSON (default: false)

Configuration methods

.content()

Replace the entire record content with new data.

Method Syntax
updatePromise.content(data)

Parameters

Parameter

Type

Description

dataValues<I>

Complete replacement data (excluding id field).

Returns

`UpdatePromise` - Chainable promise

Example

const user = await db.update(new RecordId('users', 'john'))
    .content({
        name: 'John Smith',
        email: 'john.smith@example.com',
        age: 31
    });
// Replaces all fields

.merge()

Merge partial updates into the existing record.

Method Syntax
updatePromise.merge(data)

Parameters

Parameter

Type

Description

dataValues<I>

Partial data to merge (only specified fields are updated).

Returns

`UpdatePromise` - Chainable promise

Examples

Update Single Field
const user = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'newemail@example.com' });
// Only updates email, other fields unchanged
Update Multiple Fields
const user = await db.update(new RecordId('users', 'john'))
    .merge({
        email: 'new@example.com',
        age: 31,
        updated_at: DateTime.now()
    });

.replace()

Replace specific fields while keeping others unchanged.

Method Syntax
updatePromise.replace(data)

Parameters

Parameter

Type

Description

dataValues<I>

Fields to replace.

Returns

`UpdatePromise` - Chainable promise

Example

const user = await db.update(new RecordId('users', 'john'))
    .replace({ status: 'inactive' });

.patch()

Apply JSON Patch operations to update the record.

Method Syntax
updatePromise.patch(operations)

Parameters

Parameter

Type

Description

operationsValues<I>

JSON Patch operations to apply.

Returns

`UpdatePromise` - Chainable promise

Example

const user = await db.update(new RecordId('users', 'john'))
    .patch([
        { op: 'replace', path: '/email', value: 'new@example.com' },
        { op: 'add', path: '/tags/-', value: 'premium' }
    ]);

.where()

Add a WHERE clause to conditionally update records.

Method Syntax
updatePromise.where(expr)

Parameters

Parameter

Type

Description

exprExprLike

The condition expression (string or

Expression

object).

Returns

`UpdatePromise` - Chainable promise

Examples

Conditional Update
const users = await db.update(new Table('users'))
    .merge({ verified: true })
    .where('email_confirmed = true');
With Expression Builder
import { expr } from 'surrealdb';

const users = await db.update(new Table('users'))
    .merge({ status: 'inactive' })
    .where(expr(({ lt, field }) => 
        lt(field('last_login'), DateTime.parse('2024-01-01'))
    ));

.output()

Specify what to return from the update operation.

Method Syntax
updatePromise.output(fields)

Parameters

Parameter

Type

Description

fieldsOutput"NONE"

,

"BEFORE"

,

"AFTER"

,

"DIFF"

, or field list.

Returns

`UpdatePromise` - Chainable promise

Examples

Return Updated Record
const user = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'new@example.com' })
    .output('AFTER');
// Returns the record after update
Return Only Changed Fields
const diff = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'new@example.com' })
    .output('DIFF');
// Returns only the changed fields
Return Original Record
const original = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'new@example.com' })
    .output('BEFORE');
// Returns the record before update

.timeout()

Set a timeout for the operation.

Method Syntax
updatePromise.timeout(duration)

Parameters

Parameter

Type

Description

duration

Duration

Maximum time to wait.

Returns

`UpdatePromise` - Chainable promise

.retry()

Retry the operation with exponential backoff if it fails due to a write conflict. Off by default; passing an options object (or calling with no arguments) opts the operation in.

This overrides the connection-wide default set via the retry option on ConnectOptions.

Method Syntax
updatePromise.retry(options?)

Parameters

Parameter

Type

Description

options

Partial

RetryOptions

Retry configuration. If omitted, retry is enabled with the default configuration.

Returns

`UpdatePromise` - Chainable promise

Example

await db.update(new RecordId('counter', 'c'))
    .merge({ n: 1 })
    .retry({ attempts: 3 });

.json()

Return result as JSON string.

Method Syntax
updatePromise.json()

Returns

`UpdatePromise` - Promise returning JSON string

.compile()

Compile the query into a BoundQuery without executing it.

Method Syntax
updatePromise.compile()

Returns

`BoundQuery` - The compiled query

Example

const query = db.update(new Table('users'))
    .merge({ status: 'active' })
    .where('verified = true')
    .compile();

.stream()

Stream results as they arrive.

Method Syntax
updatePromise.stream()

Returns

AsyncIterableIterator - Async iterator

Complete examples

Basic updates

import { Surreal, RecordId, Table } from 'surrealdb';

const db = new Surreal();
await db.connect('ws://localhost:8000');

// Update single record with merge
const user = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'john.new@example.com' });

// Replace entire record content
const user = await db.update(new RecordId('users', 'john'))
    .content({
        name: 'John Doe',
        email: 'john@example.com',
        age: 30,
        role: 'admin'
    });

Bulk updates

// Update all users matching condition
const updated = await db.update(new Table('users'))
    .merge({ verified: true })
    .where('email_confirmed = true');

console.log(`Updated ${updated.length} users`);

Conditional updates

// Update only if condition is met
const users = await db.update(new Table('users'))
    .merge({ status: 'inactive' })
    .where('last_login < $date', { 
        date: DateTime.parse('2024-01-01') 
    });

Complex merge

const user = await db.update(new RecordId('users', 'john'))
    .merge({
        profile: {
            bio: 'Updated bio',
            avatar: 'new-avatar.jpg'
        },
        settings: {
            notifications: true,
            theme: 'dark'
        },
        updated_at: DateTime.now()
    });

Tracking changes

const diff = await db.update(new RecordId('users', 'john'))
    .merge({ 
        email: 'new@example.com',
        age: 31 
    })
    .output('DIFF');

console.log('Changed fields:', diff);
// { email: 'new@example.com', age: 31 }

Batch update with stream

const updates = db.update(new Table('users'))
    .merge({ last_check: DateTime.now() })
    .where('active = true');

for await (const user of updates.stream()) {
    console.log(`Updated user: ${user.id}`);
}

Difference between methods

.content() vs .merge() vs .replace()

// CONTENT: Replaces entire record
await db.update(recordId).content({
    name: 'John',
    email: 'john@example.com'
});
// Result: ONLY name and email exist, all other fields removed

// MERGE: Updates specified fields only
await db.update(recordId).merge({
    email: 'john@example.com'
});
// Result: Only email updated, all other fields preserved

// REPLACE: Similar to merge but with different semantics
await db.update(recordId).replace({
    email: 'john@example.com'
});
// Result: Replaces specified fields

Chaining pattern

const result = await db.update(new Table('users'))
    .merge({ status: 'active' })
    .where('verified = true')
    .output('AFTER')
    .timeout(Duration.parse('5s'));

See also

Was this page helpful?

Previous

CreatePromise

Next

InsertPromise