• Start
Sign In

Languages

/

JavaScript

/

API Reference

/

Query builders

DeletePromise

DeletePromise provides chainable methods for configuring DELETE operations.

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

Returned by: SurrealQueryable.delete()

Source: query/delete.ts

Type parameters

  • T - The result type (deleted record data)

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

Configuration methods

.output()

Specify what to return from the delete operation.

Method Syntax
deletePromise.output(fields)

Parameters

Parameter

Type

Description

fieldsOutput"NONE"

,

"BEFORE"

, or specific field list.

Returns

`DeletePromise` - Chainable promise

Examples

Return Deleted Record
const deleted = await db.delete(new RecordId('users', 'john'))
    .output('BEFORE');
// Returns the record before deletion
Return Specific Fields
const deleted = await db.delete(new RecordId('users', 'john'))
    .output('id', 'name', 'email');
// Returns only specified fields of deleted record
Return Nothing
await db.delete(new RecordId('logs', '123'))
    .output('NONE');
// Faster when you don't need the data

.timeout()

Set a timeout for the operation.

Method Syntax
deletePromise.timeout(duration)

Parameters

Parameter

Type

Description

duration

Duration

Maximum time to wait.

Returns

`DeletePromise` - Chainable promise

Example

const deleted = await db.delete(new Table('users'))
    .timeout(Duration.parse('10s'));

.version()

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

Method Syntax
deletePromise.version(timestamp)

Parameters

Parameter

Type

Description

timestamp

DateTime

The version timestamp.

Returns

`DeletePromise` - 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
deletePromise.retry(options?)

Parameters

Parameter

Type

Description

options

Partial

RetryOptions

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

Returns

`DeletePromise` - Chainable promise

Example

await db.delete(new RecordId('users', 'john')).retry();

.json()

Return result as JSON string.

Method Syntax
deletePromise.json()

Returns

`DeletePromise` - Promise returning JSON string

.compile()

Compile the query into a BoundQuery without executing it.

Method Syntax
deletePromise.compile()

Returns

`BoundQuery` - The compiled query

Example

const query = db.delete(new Table('temp_data'))
    .compile();

.stream()

Stream deleted records as they are removed.

Method Syntax
deletePromise.stream()

Returns

AsyncIterableIterator - Async iterator

Complete examples

Basic deletion

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

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

// Delete single record
const deleted = await db.delete(new RecordId('users', 'john'));
console.log('Deleted user:', deleted);

// Delete by range
const deleted = await db.delete(
    new RecordIdRange('users', 'a', 'f')
);
console.log(`Deleted ${deleted.length} users`);

// Delete entire table
const deleted = await db.delete(new Table('temp_data'));
console.log(`Deleted ${deleted.length} records`);

Capture deleted data

// Store deleted data before removing
const user = await db.delete(new RecordId('users', 'john'))
    .output('BEFORE');

// Archive the deleted user
await db.create(new RecordId('archived_users', user.id))
    .content({
        ...user,
        deleted_at: DateTime.now()
    });

Conditional deletion

// Note: WHERE clauses are not directly supported on delete promises
// Use query() for conditional deletes
const result = await db.query(
    surql`DELETE FROM users WHERE inactive = true`
).collect();

console.log(`Deleted ${result[0].result.length} inactive users`);

Bulk deletion with streaming

const deletedRecords = db.delete(new Table('old_logs'));

let count = 0;
for await (const record of deletedRecords.stream()) {
    count++;
    if (count % 100 === 0) {
        console.log(`Deleted ${count} records`);
    }
}

Soft delete pattern

// Instead of deleting, mark as deleted
const user = await db.update(new RecordId('users', 'john'))
    .merge({
        deleted: true,
        deleted_at: DateTime.now()
    });

// Actual delete with backup
const user = await db.delete(new RecordId('users', 'john'))
    .output('BEFORE');

if (user) {
    await db.create(new RecordId('deleted_users', user.id))
        .content(user);
}

Delete with error handling

try {
    const deleted = await db.delete(new RecordId('users', 'john'));
    
    if (!deleted) {
        console.log('User not found');
    } else {
        console.log('User deleted successfully');
    }
} catch (error) {
    if (error instanceof ResponseError) {
        console.error('Delete failed:', error.message);
    }
}

Performance optimization

// Don't wait for deleted data if not needed
await db.delete(new Table('temp_cache'))
    .output('NONE');
// Faster execution

Delete with timeout

// For large deletions
const deleted = await db.delete(new Table('old_logs'))
    .timeout(Duration.parse('30s'));

Cascading deletes

// Delete user and all related data
const userId = new RecordId('users', 'john');

// Delete user
const user = await db.delete(userId);

// Delete related posts
await db.query(
    surql`DELETE FROM posts WHERE author = ${userId}`
).collect();

// Delete related comments
await db.query(
    surql`DELETE FROM comments WHERE author = ${userId}`
).collect();

console.log('User and related data deleted');

Batch deletion

const idsToDelete = ['user1', 'user2', 'user3'];

for (const id of idsToDelete) {
    await db.delete(new RecordId('users', id));
}

// Or using query for better performance
const result = await db.query(
    surql`DELETE FROM users WHERE id IN ${idsToDelete.map(id => new RecordId('users', id))}`
).collect();

Archive before delete

async function archiveAndDelete(recordId: RecordId) {
    // Get the record
    const record = await db.select(recordId);
    
    if (!record) {
        throw new Error('Record not found');
    }
    
    // Archive it
    await db.create(new RecordId('archive', record.id))
        .content({
            ...record,
            archived_at: DateTime.now()
        });
    
    // Delete original
    await db.delete(recordId).output('NONE');
    
    return record;
}

await archiveAndDelete(new RecordId('users', 'john'));

Important notes

Warning

DELETE operations are permanent and cannot be undone. Always ensure you have backups or use the .output('BEFORE') method to capture data before deletion.

!NOTE: Tip
For conditional deletions, use db.query() with a DELETE statement including a WHERE clause.

Chaining pattern

const result = await db.delete(new Table('users'))
    .output('BEFORE')
    .timeout(Duration.parse('10s'));

See also

Was this page helpful?

Previous

UpsertPromise

Next

RelatePromise