Query Builders

Query builder classes are promise-like objects returned by query methods on SurrealQueryable. They provide chainable configuration methods before executing the query.

All query builders implement a promise-like interface, allowing you to await them directly or chain configuration methods before execution.

Common Pattern

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

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

Query Builder Classes

Core Query Execution

Query - Execute raw SurrealQL with streaming and batch processing support
- Returned by: SurrealQueryable.query()
- Key methods: .collect(), .stream(), .responses(), .json()

Record Operations

SelectPromise - Configure SELECT queries with filtering, pagination, and field selection
- Returned by: SurrealQueryable.select()
- Key methods: .fields(), .value(), .where(), .fetch(), .start(), .limit()
CreatePromise - Configure CREATE operations for new records
- Returned by: SurrealQueryable.create()
- Key methods: .content(), .patch(), .output()
InsertPromise - Configure INSERT operations for bulk record insertion
- Returned by: SurrealQueryable.insert()
- Key methods: .relation(), .ignore(), .output()
UpdatePromise - Configure UPDATE operations with various update strategies
- Returned by: SurrealQueryable.update()
- Key methods: .content(), .merge(), .replace(), .patch(), .where(), .output()
UpsertPromise - Configure UPSERT operations (insert or replace)
- Returned by: SurrealQueryable.upsert()
- Key methods: .content(), .merge(), .patch(), .output()
DeletePromise - Configure DELETE operations
- Returned by: SurrealQueryable.delete()
- Key methods: .output(), .timeout()

Graph Operations

RelatePromise - Configure RELATE operations for creating graph relationships
- Returned by: SurrealQueryable.relate()
- Key methods: .unique(), .output(), .timeout()

Real-time & Advanced

LivePromise - Subscribe to live query updates for real-time data changes
- Variants: ManagedLivePromise, UnmanagedLivePromise
- Returned by: SurrealQueryable.live(), SurrealQueryable.liveOf()
- Key methods: .diff(), .fields(), .where(), .fetch()
RunPromise - Execute SurrealDB functions and SurrealML models
- Returned by: SurrealQueryable.run()
- Key methods: .json()
ApiPromise - Execute user-defined API endpoint calls
- Returned by: Methods on SurrealApi
- Key methods: .value(), .header(), .json()

Common Configuration Options

Most query builders support these common configuration methods:

`.json()`

Return results as JSON strings instead of parsed objects.

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

`.timeout(duration)`

Set a timeout for the query operation.

await db.select(new Table('users'))
    .timeout(new Duration('5s'));

`.version(timestamp)`

Query records at a specific version/timestamp (time-travel queries).

await db.select(new Table('users'))
    .version(new DateTime('2024-01-01T00:00:00Z'));

Type Parameters

Query builders use generic type parameters for type safety:

T - The base type of the record
I - The input type for operations
J - The JSON string type when using .json()
R - The result type (for Query class)