Sign In

JS SDK Version

API Reference
Query Builders
CreatePromise

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 type

  • I - The input type for record data

  • J - 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

ParameterTypeDescription
data 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

ParameterTypeDescription
operations 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

ParameterTypeDescription
fields OutputOutput 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');
// Returns only id and name

Return Full Record

const user = await db.create(new Table('users'))
    .content(userData)
    .output('AFTER');
// Returns complete created record

Return Nothing

await db.create(new Table('logs'))
    .content(logData)
    .output('NONE');
// Returns undefined, useful for fire-and-forget

.timeout()

Set a timeout for the operation.

Method Syntax

createPromise.timeout(duration)

Parameters

ParameterTypeDescription
duration DurationMaximum 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

ParameterTypeDescription
timestamp DateTimeThe 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');

// 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

Edit pageReport an issue

Previous

SelectPromise

Next

UpdatePromise