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.
createPromise.content(data)Parameters
Parameter | Type | Description |
|---|---|---|
data | Values<I> | The record data (excluding id field). |
Returns
`CreatePromise` - Chainable promise
Examples
const user = await db.create(new RecordId('users', 'john'))
.content({
name: 'John Doe',
email: 'john@example.com',
age: 30
});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.
createPromise.patch(operations)Parameters
Parameter | Type | Description |
|---|---|---|
operations | Values<I> | JSON Patch operations to apply. |
Returns
`CreatePromise` - 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.
createPromise.output(fields)Parameters
Parameter | Type | Description |
|---|---|---|
fields | Output | Output specification: "NONE", "BEFORE", "AFTER", "DIFF", or field list. |
Returns
`CreatePromise` - Chainable promise
Examples
const user = await db.create(new Table('users'))
.content(userData)
.output('id', 'name');
// Returns only id and nameconst user = await db.create(new Table('users'))
.content(userData)
.output('AFTER');
// Returns complete created recordawait db.create(new Table('logs'))
.content(logData)
.output('NONE');
// Returns undefined, useful for fire-and-forget .timeout()
Set a timeout for the operation.
createPromise.timeout(duration)Parameters
Parameter | Type | Description |
|---|---|---|
duration | Duration | Maximum time to wait for operation completion. |
Returns
`CreatePromise` - 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).
createPromise.version(timestamp)Parameters
Parameter | Type | Description |
|---|---|---|
timestamp | DateTime | The version timestamp. |
Returns
`CreatePromise` - Chainable promise
Example
const user = await db.create(new Table('users'))
.content(userData)
.version(DateTime.now()); .retry()
Retry the operation with exponential backoff if it fails due to a write conflict. Off by default; passing an options object (or calling with no arguments) opts the operation in.
This overrides the connection-wide default set via the retry option on ConnectOptions.
createPromise.retry(options?)Parameters
Parameter | Type | Description |
|---|---|---|
options | Partial RetryOptions | Retry configuration. If omitted, retry is enabled with the default configuration. |
Returns
`CreatePromise` - Chainable promise
Example
const user = await db.create(new Table('users'))
.content(userData)
.retry({ attempts: 3 }); .json()
Return result as JSON string instead of parsed object.
createPromise.json()Returns
`CreatePromise` - Promise returning JSON string
Example
const jsonString = await db.create(new Table('users'))
.content(userData)
.json(); .compile()
Compile the query into a BoundQuery without executing it.
createPromise.compile()Returns
`BoundQuery` - The compiled query
Example
const query = db.create(new Table('users'))
.content(userData)
.compile(); .stream()
Stream the operation result (useful when creating multiple records).
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');
// Create with specific ID
const user = await db.create(new RecordId('users', 'john'))
.content({
name: 'John Doe',
email: 'john@example.com',
role: 'admin'
});
// Create with auto-generated ID
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
// Only return the ID
const { id } = await db.create(new Table('users'))
.content(userData)
.output('id');
// Return specific fields
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
SurrealQueryable.create() - Method that returns CreatePromise
InsertPromise - Bulk insertion
UpsertPromise - Insert or replace
Query overview - All query builder classes