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 typeI - The input type for record dataJ - 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 |
|---|
data required | 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
});
.merge()
Merge partial updates into the existing record.
Method Syntax
updatePromise.merge(data)
Parameters
| Parameter | Type | Description |
|---|
data required | 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' });
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 |
|---|
data required | 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
| Parameter | Type | Description |
|---|
operations required | 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
| Parameter | Type | Description |
|---|
condition required | ExprLike | The 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
| Parameter | Type | Description |
|---|
fields required | 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');
Return Only Changed Fields
const diff = await db.update(new RecordId('users', 'john'))
.merge({ email: 'new@example.com' })
.output('DIFF');
Return Original Record
const original = await db.update(new RecordId('users', 'john'))
.merge({ email: 'new@example.com' })
.output('BEFORE');
.timeout()
Set a timeout for the operation.
Method Syntax
updatePromise.timeout(duration)
Parameters
| Parameter | Type | Description |
|---|
duration required | Duration | Maximum 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
| Parameter | Type | Description |
|---|
timestamp required | DateTime | The 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');
const user = await db.update(new RecordId('users', 'john'))
.merge({ email: 'john.new@example.com' });
const user = await db.update(new RecordId('users', 'john'))
.content({
name: 'John Doe',
email: 'john@example.com',
age: 30,
role: 'admin'
});
Bulk Updates
const updated = await db.update(new Table('users'))
.merge({ verified: true })
.where('email_confirmed = true');
console.log(`Updated ${updated.length} users`);
Conditional Updates
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);
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()
await db.update(recordId).content({
name: 'John',
email: 'john@example.com'
});
await db.update(recordId).merge({
email: 'john@example.com'
});
await db.update(recordId).replace({
email: 'john@example.com'
});
Chaining Pattern
const result = await db.update(new Table('users'))
.merge({ status: 'active' })
.where('verified = true')
.output('AFTER')
.timeout(Duration.parse('5s'));
See Also
