SurrealQueryable

The SurrealQueryable class is an abstract base class that provides all query execution methods for interacting with SurrealDB. It is the foundation for executing database operations and is extended by SurrealSession and SurrealTransaction.

Extended by: SurrealSession, SurrealTransaction

Source: api/queryable.ts

Methods

.api()

Create a SurrealApi instance for invoking user-defined API endpoints. You can provide type definitions for type-safe API calls and an optional path prefix.

db.api<TPaths>(prefix?)

Parameters

Returns

[`SurrealApi`](/docs/reference/javascript/api/core/surreal-api) - An API instance for invoking custom database APIs

Examples

const api = db.api();
const result = await api.get('/users');

type MyPaths = {
    "/users": { get: [void, User[]] };
    [K: `/users/${number}`]: { get: [void, User] };
};

const api = db.api<MyPaths>();
const users = await api.get("/users"); // Type: User[]

const usersApi = db.api<MyPaths>("/users");
const user = await usersApi.get("123"); // GET /users/123

Query methods

.query()

Execute raw SurrealQL statements against the database.

db.query<R>(query, bindings?)
db.query<R>(boundQuery)

Parameters

Type parameters

• •

  R extends unknown[] - Array of result types for each query statement

Returns

[`Query`](/docs/reference/javascript/api/queries/query) - A query instance that can be configured and executed

Examples

const result = await db.query('SELECT * FROM users').collect();
console.log(result); // [{ success: true, result: [...] }]

const result = await db.query(
    'SELECT * FROM users WHERE age > $age',
    { age: 18 }
).collect();

const results = await db.query<[User[], Post[]]>(`
    SELECT * FROM users;
    SELECT * FROM posts;
`).collect();

const [users, posts] = results.map(r => r.result);

import { surql } from 'surrealdb';

const query = surql`SELECT * FROM users WHERE age > ${18}`;
const result = await db.query(query).collect();

.select()

Select records from the database by record ID, record ID range, or table.

db.select<T>(recordId)
db.select<T>(range)
db.select<T>(table)

Parameters

Returns

• •

  For `RecordId`: [`SelectPromise`](/docs/reference/javascript/api/queries/select-promise) - A promise resolving to a single record or `undefined`

• •

  For `Table` or `RecordIdRange`: [`SelectPromise`](/docs/reference/javascript/api/queries/select-promise) - A promise resolving to an array of records

Examples

const user = await db.select(new RecordId('users', 'john'));

const users = await db.select(new Table('users'));

const users = await db.select(new Table('users'))
    .where('age > 18')
    .limit(10)
    .start(0);

.create()

Create new records in the database.

db.create<T>(recordId)
db.create<T>(table)

Parameters

Returns

[`CreatePromise, T>`](/docs/reference/javascript/api/queries/create-promise) - A promise with chainable configuration methods

Examples

const user = await db.create(new RecordId('users', 'john'))
    .content({ name: 'John Doe', email: 'john@example.com' });

const user = await db.create(new Table('users'))
    .content({ name: 'Jane Doe', email: 'jane@example.com' });

.insert()

Insert one or multiple records into the database.

db.insert<T>(data)
db.insert<T>(table, data)

Parameters

Returns

[`InsertPromise`](/docs/reference/javascript/api/queries/insert-promise) - A promise with chainable configuration methods

Examples

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' }
]);

const users = await db.insert(new Table('users'), [
    { name: 'Dave' },
    { name: 'Eve' }
]);

.update()

Update existing records in the database.

db.update<T>(recordId)
db.update<T>(range)
db.update<T>(table)

Parameters

Returns

[`UpdatePromise`](/docs/reference/javascript/api/queries/update-promise) - A promise with chainable configuration methods

Examples

const user = await db.update(new RecordId('users', 'john'))
    .content({ name: 'John Smith', email: 'john@example.com' });

const user = await db.update(new RecordId('users', 'john'))
    .merge({ email: 'newemail@example.com' });

const users = await db.update(new Table('users'))
    .merge({ verified: true })
    .where('age > 18');

.upsert()

Upsert records (insert if they don't exist, replace if they do).

db.upsert<T>(recordId)
db.upsert<T>(range)
db.upsert<T>(table)

Parameters

Returns

[`UpsertPromise`](/docs/reference/javascript/api/queries/upsert-promise) - A promise with chainable configuration methods

Example

const user = await db.upsert(new RecordId('users', 'john'))
    .content({ name: 'John Doe', email: 'john@example.com' });

.delete()

Delete records from the database.

db.delete<T>(recordId)
db.delete<T>(range)
db.delete<T>(table)

Parameters

Returns

[`DeletePromise`](/docs/reference/javascript/api/queries/delete-promise) - A promise with chainable configuration methods

Examples

const deleted = await db.delete(new RecordId('users', 'john'));

const deleted = await db.delete(new Table('users'));

.relate()

Create graph relationships (edges) between records.

db.relate<T>(from, edge, to, data?)
db.relate<T>(from[], edge, to[], data?)

Parameters

Returns

[`RelatePromise`](/docs/reference/javascript/api/queries/relate-promise) - A promise for the relationship operation

Examples

const edge = await db.relate(
    new RecordId('users', 'john'),
    new Table('likes'),
    new RecordId('posts', '1'),
    { timestamp: new Date() }
);

const edges = await db.relate(
    [new RecordId('users', 'john'), new RecordId('users', 'jane')],
    new Table('follows'),
    [new RecordId('users', 'alice'), new RecordId('users', 'bob')]
);

.live()

Create a live query subscription to receive real-time updates when records change.

db.live<T>(what)

Parameters

Returns

[`ManagedLivePromise`](/docs/reference/javascript/api/queries/live-promise) - A managed live query subscription

Example

const subscription = await db.live(new Table('users'));

for await (const update of subscription) {
    console.log('Update:', update.action, update.result);
}

.liveOf()

Subscribe to an existing live query using its ID.

db.liveOf<T>(id)

Parameters

Returns

[`UnmanagedLivePromise`](/docs/reference/javascript/api/queries/live-promise) - An unmanaged live query subscription

Example

const liveQueryId = await db.query('LIVE SELECT * FROM users').collect();
const subscription = db.liveOf(liveQueryId);

.run()

Execute a SurrealDB function or SurrealML model.

db.run<T>(name, args?)
db.run<T>(name, version, args?)

Parameters

Returns

[`RunPromise`](/docs/reference/javascript/api/queries/run-promise) - A promise for the function result

Examples

const result = await db.run('fn::calculate', [10, 20]);

const prediction = await db.run('ml::predict', '1.0.0', [inputData]);

.auth()

Get the currently authenticated record user by selecting the $auth parameter.

db.auth<T>()

Returns

`AuthPromise` - A promise for the authenticated user record, or `undefined` if not authenticated

Example

const user = await db.auth();
console.log('Current user:', user);

See also

• •

  SurrealSession - Session management extending this class

• •

  SurrealTransaction - Transaction support extending this class

• •

  Query builders - Detailed query builder documentation

• •

  SelectPromise - SELECT query configuration

• •

  CreatePromise - CREATE query configuration