Sign In

JS SDK Version

API Reference
Query Builders
UpdatePromise

UpdatePromise<T, I, J>

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

ParameterTypeDescription
data Values<I>Complete replacement data (excluding id field).

Returns

UpdatePromise<T, I, J> - 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

ParameterTypeDescription
data Partial<Values<I>>Partial data to merge (only specified fields are updated).

Returns

UpdatePromise<T, I, J> - 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

ParameterTypeDescription
data Values<I>Fields to replace.

Returns

UpdatePromise<T, I, J> - 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

ParameterTypeDescription
operations PatchOperation[]JSON Patch operations to apply.

Returns

UpdatePromise<T, I, J> - 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(condition)

Parameters

ParameterTypeDescription
condition ExprLikeThe condition expression (string or Expression object).

Returns

UpdatePromise<T, I, J> - 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

ParameterTypeDescription
fields Output"NONE", "BEFORE", "AFTER", "DIFF", or field list.

Returns

UpdatePromise<T, I, J> - 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

ParameterTypeDescription
duration DurationMaximum time to wait.

Returns

UpdatePromise<T, I, J> - Chainable promise

.version()

Update at a specific version (for versioned storage engines).

Method Syntax

updatePromise.version(timestamp)

Parameters

ParameterTypeDescription
timestamp DateTimeThe version timestamp.

Returns

UpdatePromise<T, I, J> - Chainable promise

.json()

Return result as JSON string.

Method Syntax

updatePromise.json()

Returns

UpdatePromise<T, I, true> - Promise returning JSON string

.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

Edit pageReport an issue

Previous

CreatePromise

Next

InsertPromise