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
| Parameter | Type | Description |
|---|
fields required | 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');
Return Specific Fields
const deleted = await db.delete(new RecordId('users', 'john'))
.output('id', 'name', 'email');
Return Nothing
await db.delete(new RecordId('logs', '123'))
.output('NONE');
.timeout()
Set a timeout for the operation.
Method Syntax
deletePromise.timeout(duration)
Parameters
| Parameter | Type | Description |
|---|
duration required | Duration | Maximum 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
| Parameter | Type | Description |
|---|
timestamp required | DateTime | The 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');
const deleted = await db.delete(new RecordId('users', 'john'));
console.log('Deleted user:', deleted);
const deleted = await db.delete(
new RecordIdRange('users', 'a', 'f')
);
console.log(`Deleted ${deleted.length} users`);
const deleted = await db.delete(new Table('temp_data'));
console.log(`Deleted ${deleted.length} records`);
Capture Deleted Data
const user = await db.delete(new RecordId('users', 'john'))
.output('BEFORE');
await db.create(new RecordId('archived_users', user.id))
.content({
...user,
deleted_at: DateTime.now()
});
Conditional Deletion
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
const user = await db.update(new RecordId('users', 'john'))
.merge({
deleted: true,
deleted_at: DateTime.now()
});
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);
}
}
await db.delete(new Table('temp_cache'))
.output('NONE');
Delete with Timeout
const deleted = await db.delete(new Table('old_logs'))
.timeout(Duration.parse('30s'));
Cascading Deletes
const userId = new RecordId('users', 'john');
const user = await db.delete(userId);
await db.query(
surql`DELETE FROM posts WHERE author = ${userId}`
).collect();
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));
}
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) {
const record = await db.select(recordId);
if (!record) {
throw new Error('Record not found');
}
await db.create(new RecordId('archive', record.id))
.content({
...record,
archived_at: DateTime.now()
});
await db.delete(recordId).output('NONE');
return record;
}
await archiveAndDelete(new RecordId('users', 'john'));
Important Notes
DELETE operations are permanent and cannot be undone. Always ensure you have backups or use the .output('BEFORE') method to capture data before deletion.
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
