`UpsertPromise<T, I, J>`

The UpsertPromise class provides a chainable interface for configuring UPSERT operations (insert if not exists, replace if exists). It extends Promise, allowing you to await it directly or chain configuration methods.

Warning

UPSERT replaces the entire record if it exists. Use update().merge() for partial updates.

Returned by: SurrealQueryable.upsert()

Source: query/upsert.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()`

Set the complete content for the record (insert or replace).

Method Syntax

upsertPromise.content(data)

Parameters

Parameter	Type	Description
`data`	`Values<I>`	Complete record data (excluding id field).

Returns

UpsertPromise<T, I, J> - Chainable promise

Example

const user = await db.upsert(new RecordId('users', 'john'))
    .content({
        name: 'John Doe',
        email: 'john@example.com',
        age: 30
    });
// Inserts if not exists, replaces entirely if exists

`.merge()`

Merge data into the record (insert if not exists, merge if exists).

Method Syntax

upsertPromise.merge(data)

Parameters

Parameter	Type	Description
`data`	`Partial<Values<I>>`	Partial data to merge.

Returns

UpsertPromise<T, I, J> - Chainable promise

Example

const user = await db.upsert(new RecordId('users', 'john'))
    .merge({
        name: 'John Doe',
        last_login: DateTime.now()
    });
// If exists: merges fields; if not: creates with these fields

`.replace()`

Replace specific fields.

Method Syntax

upsertPromise.replace(data)

Parameters

Parameter	Type	Description
`data`	`Values<I>`	Fields to replace.

Returns

UpsertPromise<T, I, J> - Chainable promise

`.patch()`

Apply JSON Patch operations.

Method Syntax

upsertPromise.patch(operations)

Parameters

Parameter	Type	Description
`operations`	`PatchOperation[]`	JSON Patch operations.

Returns

UpsertPromise<T, I, J> - Chainable promise

`.where()`

Add a WHERE clause for conditional upsert.

Method Syntax

upsertPromise.where(condition)

Parameters

Parameter	Type	Description
`condition`	`ExprLike`	The condition expression (string or Expression object).

Returns

UpsertPromise<T, I, J> - Chainable promise

`.output()`

Specify what to return.

Method Syntax

upsertPromise.output(fields)

Parameters

Parameter	Type	Description
`fields`	`Output`	`"NONE"`, `"BEFORE"`, `"AFTER"`, `"DIFF"`, or field list.

Returns

UpsertPromise<T, I, J> - Chainable promise

`.timeout()`

Set operation timeout.

Method Syntax

upsertPromise.timeout(duration)

Returns

UpsertPromise<T, I, J> - Chainable promise

`.version()`, `.json()`, `.stream()`

See other query builders for these common methods.

Complete Examples

Basic Upsert

import { Surreal, RecordId } from 'surrealdb';

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

// Upsert: insert if not exists, replace if exists
const user = await db.upsert(new RecordId('users', 'john'))
    .content({
        name: 'John Doe',
        email: 'john@example.com',
        role: 'user'
    });

Upsert with Merge

// Safer: merge instead of replace
const user = await db.upsert(new RecordId('users', 'john'))
    .merge({
        last_login: DateTime.now(),
        login_count: 1
    });
// If user exists: only updates these fields
// If not: creates user with these fields

Bulk Upsert

const users = await db.upsert(new Table('users'))
    .content(userDataArray);

Track Changes

const result = await db.upsert(new RecordId('users', 'john'))
    .content(userData)
    .output('DIFF');

if (result) {
    console.log('Created or updated:', result);
}

Conditional Upsert

const user = await db.upsert(new RecordId('users', 'john'))
    .merge({ status: 'active' })
    .where('verified = true');

UPSERT vs CREATE vs UPDATE

// CREATE: Fails if record exists
try {
    await db.create(recordId).content(data);
} catch (error) {
    // Error if exists
}

// UPDATE: Fails if record doesn't exist
try {
    await db.update(recordId).merge(data);
} catch (error) {
    // Error if not found
}

// UPSERT: Works in both cases
await db.upsert(recordId).content(data);
// Always succeeds

Use Cases

Session Management

// Update session or create new one
async function updateSession(sessionId: string, data: SessionData) {
    return db.upsert(new RecordId('sessions', sessionId))
        .merge({
            ...data,
            last_activity: DateTime.now()
        });
}

Cache Pattern

// Write-through cache
async function cacheSet(key: string, value: unknown) {
    return db.upsert(new RecordId('cache', key))
        .content({
            value,
            expires_at: DateTime.now().plus(Duration.parse('1h'))
        });
}

Counter Pattern

// Increment counter or initialize
const counter = await db.upsert(new RecordId('counters', 'page_views'))
    .merge({
        count: 1,
        last_increment: DateTime.now()
    });

Chaining Pattern

const result = await db.upsert(new RecordId('users', 'john'))
    .content(userData)
    .output('AFTER')
    .timeout(Duration.parse('5s'));

UpsertPromise<T, I, J>

Warning

Type Parameters

Configuration Methods

.content()

Parameters

Returns

Example

.merge()

Parameters

Returns

Example

.replace()

Parameters

Returns

.patch()

Parameters

Returns

.where()

Parameters

Returns

.output()

Parameters

Returns

.timeout()

Returns

.version(), .json(), .stream()

Complete Examples

Basic Upsert

Upsert with Merge

Bulk Upsert

Track Changes

Conditional Upsert

UPSERT vs CREATE vs UPDATE

Use Cases

Session Management

Cache Pattern

Counter Pattern

Chaining Pattern

See Also

`UpsertPromise<T, I, J>`

`.content()`

`.merge()`

`.replace()`

`.patch()`

`.where()`

`.output()`

`.timeout()`

`.version()`, `.json()`, `.stream()`