DeletePromise<T, J>

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

Returns

DeletePromise<T, J> - 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

Returns

DeletePromise<T, J> - 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

Returns

DeletePromise<T, J> - Chainable promise

.json()

Return result as JSON string.

Method Syntax
deletePromise.json()

Returns

DeletePromise<T, true> - Promise returning JSON string

.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.

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

• SurrealQueryable.delete() - Method that returns DeletePromise
• UpdatePromise - Update records
• Query - Raw SurrealQL for conditional deletes
• Query Overview - All query builder classes