Sign In

JS SDK Version

API Reference
Query Builders
DeletePromise

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

ParameterTypeDescription
fields Output"NONE", "BEFORE", or specific field list.

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

ParameterTypeDescription
duration DurationMaximum time to wait.

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

ParameterTypeDescription
timestamp DateTimeThe version timestamp.

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

Chaining Pattern

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

See Also

Edit pageReport an issue

Previous

UpsertPromise

Next

RelatePromise