CreatePromise<T, I, J>
The CreatePromise class provides a chainable interface for configuring CREATE operations before execution. It extends Promise, allowing you to await it directly or chain configuration methods.
Returned by: SurrealQueryable.create()
Source: query/create.ts
Type Parameters
T - The result typeI - The input type for record dataJ - Boolean indicating if result is JSON (default: false)
Configuration Methods
.content()
Set the complete content for the new record.
Method Syntax
createPromise.content(data)
Parameters
| Parameter | Type | Description |
|---|
data required | Values<I> | The record data (excluding id field). |
Returns
CreatePromise<T, I, J> - Chainable promise
Examples
Create with Specific ID
const user = await db.create(new RecordId('users', 'john'))
.content({
name: 'John Doe',
email: 'john@example.com',
age: 30
});
Create with Auto-Generated ID
const user = await db.create(new Table('users'))
.content({
name: 'Jane Doe',
email: 'jane@example.com',
age: 28
});
.patch()
Apply JSON Patch operations to set record data.
Method Syntax
createPromise.patch(operations)
Parameters
| Parameter | Type | Description |
|---|
operations required | Values<I> | JSON Patch operations to apply. |
Returns
CreatePromise<T, I, J> - Chainable promise
Example
const user = await db.create(new Table('users'))
.patch([
{ op: 'add', path: '/name', value: 'John' },
{ op: 'add', path: '/email', value: 'john@example.com' }
]);
.output()
Specify which fields to return in the response.
Method Syntax
createPromise.output(fields)
Parameters
| Parameter | Type | Description |
|---|
fields required | Output | Output specification: “NONE”, “BEFORE”, “AFTER”, “DIFF”, or field list. |
Returns
CreatePromise<T, I, J> - Chainable promise
Examples
Return Specific Fields
const user = await db.create(new Table('users'))
.content(userData)
.output('id', 'name');
Return Full Record
const user = await db.create(new Table('users'))
.content(userData)
.output('AFTER');
Return Nothing
await db.create(new Table('logs'))
.content(logData)
.output('NONE');
.timeout()
Set a timeout for the operation.
Method Syntax
createPromise.timeout(duration)
Parameters
| Parameter | Type | Description |
|---|
duration required | Duration | Maximum time to wait for operation completion. |
Returns
CreatePromise<T, I, J> - Chainable promise
Example
const user = await db.create(new Table('users'))
.content(userData)
.timeout(Duration.parse('5s'));
.version()
Create the record at a specific version (for versioned storage engines).
Method Syntax
createPromise.version(timestamp)
Parameters
| Parameter | Type | Description |
|---|
timestamp required | DateTime | The version timestamp. |
Returns
CreatePromise<T, I, J> - Chainable promise
Example
const user = await db.create(new Table('users'))
.content(userData)
.version(DateTime.now());
.json()
Return result as JSON string instead of parsed object.
Method Syntax
createPromise.json()
Returns
CreatePromise<T, I, true> - Promise returning JSON string
Example
const jsonString = await db.create(new Table('users'))
.content(userData)
.json();
.stream()
Stream the operation result (useful when creating multiple records).
Method Syntax
createPromise.stream()
Returns
AsyncIterableIterator - Async iterator
Example
const results = db.create(new Table('users'))
.content(multipleUsers);
for await (const user of results.stream()) {
console.log('Created:', user);
}
Complete Examples
Basic Creation
import { Surreal, RecordId, Table } from 'surrealdb';
const db = new Surreal();
await db.connect('ws://localhost:8000');
const user = await db.create(new RecordId('users', 'john'))
.content({
name: 'John Doe',
email: 'john@example.com',
role: 'admin'
});
const post = await db.create(new Table('posts'))
.content({
title: 'Hello World',
content: 'My first post',
author: new RecordId('users', 'john')
});
Creation with Output Control
const { id } = await db.create(new Table('users'))
.content(userData)
.output('id');
const summary = await db.create(new Table('users'))
.content(userData)
.output('id', 'name', 'created_at');
Bulk Creation with Streaming
const users = [
{ name: 'Alice', email: 'alice@example.com' },
{ name: 'Bob', email: 'bob@example.com' },
{ name: 'Carol', email: 'carol@example.com' }
];
for await (const user of db.create(new Table('users')).content(users).stream()) {
console.log(`Created user: ${user.name} with ID: ${user.id}`);
}
With Relationships
const post = await db.create(new Table('posts'))
.content({
title: 'New Post',
content: 'Post content here',
author: new RecordId('users', 'john'),
tags: [
new RecordId('tags', 'javascript'),
new RecordId('tags', 'tutorial')
],
created_at: DateTime.now()
});
Error Handling
try {
const user = await db.create(new RecordId('users', 'existing'))
.content(userData);
} catch (error) {
if (error instanceof ResponseError) {
console.error('User already exists:', error.message);
}
}
With Timeout
const user = await db.create(new Table('users'))
.content(complexUserData)
.timeout(Duration.parse('10s'));
Chaining Pattern
All configuration methods return a new CreatePromise, allowing method chaining:
const result = await db.create(new Table('users'))
.content(userData)
.output('id', 'name', 'email')
.timeout(Duration.parse('5s'));
See Also
