InsertPromise<T, J>
The InsertPromise class provides a chainable interface for configuring INSERT operations for bulk record insertion. It extends Promise, allowing you to await it directly or chain configuration methods.
Returned by: SurrealQueryable.insert()
Source: query/insert.ts
Type Parameters
T - The result typeJ - Boolean indicating if result is JSON (default: false)
Configuration Methods
.relation()
Configure the insert to work with relation (edge) records instead of regular records.
Method Syntax
insertPromise.relation()
Returns
InsertPromise<T, J> - Chainable promise
Example
const edges = await db.insert([
{
id: new RecordId('likes', '1'),
in: new RecordId('users', 'john'),
out: new RecordId('posts', '1')
}
]).relation();
.ignore()
Ignore records that already exist (skip duplicates without error).
Method Syntax
insertPromise.ignore()
Returns
InsertPromise<T, J> - Chainable promise
Example
const users = await db.insert([
{ id: new RecordId('users', 'john'), name: 'John' },
{ id: new RecordId('users', 'jane'), name: 'Jane' }
]).ignore();
.output()
Specify which fields to return in the response.
Method Syntax
insertPromise.output(fields)
Parameters
| Parameter | Type | Description |
|---|
fields required | Output | ”NONE”, “AFTER”, or specific field list. |
Returns
InsertPromise<T, J> - Chainable promise
Examples
Return Specific Fields
const users = await db.insert(userData)
.output('id', 'name');
Return Nothing
await db.insert(logData)
.output('NONE');
.timeout()
Set a timeout for the operation.
Method Syntax
insertPromise.timeout(duration)
Parameters
| Parameter | Type | Description |
|---|
duration required | Duration | Maximum time to wait. |
Returns
InsertPromise<T, J> - Chainable promise
.version()
Insert at a specific version (for versioned storage engines).
Method Syntax
insertPromise.version(timestamp)
Parameters
| Parameter | Type | Description |
|---|
timestamp required | DateTime | The version timestamp. |
Returns
InsertPromise<T, J> - Chainable promise
.json()
Return result as JSON string.
Method Syntax
insertPromise.json()
Returns
InsertPromise<T, true> - Promise returning JSON string
.stream()
Stream results as records are inserted.
Method Syntax
insertPromise.stream()
Returns
AsyncIterableIterator - Async iterator
Complete Examples
Basic Insertion
import { Surreal, RecordId } from 'surrealdb';
const db = new Surreal();
await db.connect('ws://localhost:8000');
const user = await db.insert({
id: new RecordId('users', 'alice'),
name: 'Alice',
email: 'alice@example.com'
});
const users = await db.insert([
{ id: new RecordId('users', 'bob'), name: 'Bob' },
{ id: new RecordId('users', 'carol'), name: 'Carol' }
]);
Insert into Table
const users = await db.insert(new Table('users'), [
{ name: 'Dave', email: 'dave@example.com' },
{ name: 'Eve', email: 'eve@example.com' }
]);
Ignore Duplicates
const users = await db.insert([
{ id: new RecordId('users', 'john'), name: 'John' },
{ id: new RecordId('users', 'jane'), name: 'Jane' }
]).ignore();
console.log(`Inserted ${users.length} new users`);
Bulk Insert with Streaming
const largeDataset = generateThousandsOfRecords();
let count = 0;
for await (const record of db.insert(largeDataset).stream()) {
count++;
if (count % 100 === 0) {
console.log(`Inserted ${count} records`);
}
}
Insert Relations (Edges)
const likes = await db.insert([
{
id: new RecordId('likes', '1'),
in: new RecordId('users', 'john'),
out: new RecordId('posts', '1'),
created_at: DateTime.now()
},
{
id: new RecordId('likes', '2'),
in: new RecordId('users', 'jane'),
out: new RecordId('posts', '1'),
created_at: DateTime.now()
}
]).relation();
Optimized Insertion
await db.insert(logEntries)
.output('NONE');
Insert with Timeout
const users = await db.insert(largeDataset)
.timeout(Duration.parse('30s'));
Error Handling
try {
const users = await db.insert([
{ id: new RecordId('users', 'existing'), name: 'Test' }
]);
} catch (error) {
if (error instanceof ResponseError) {
console.error('Duplicate key error:', error.message);
const users = await db.insert([
{ id: new RecordId('users', 'existing'), name: 'Test' }
]).ignore();
}
}
Batch Processing
const BATCH_SIZE = 100;
const allUsers = [...];
for (let i = 0; i < allUsers.length; i += BATCH_SIZE) {
const batch = allUsers.slice(i, i + BATCH_SIZE);
await db.insert(batch);
console.log(`Inserted batch ${i / BATCH_SIZE + 1}`);
}
vs CREATE
When to use INSERT vs CREATE
const user = await db.create(new RecordId('users', 'john'))
.content(userData);
const users = await db.insert([
{ id: new RecordId('users', 'alice'), ...data1 },
{ id: new RecordId('users', 'bob'), ...data2 },
{ id: new RecordId('users', 'carol'), ...data3 }
]);
Chaining Pattern
const result = await db.insert(records)
.ignore()
.output('id', 'name')
.timeout(Duration.parse('10s'));
See Also
