Query builders

Reference for the fluent query builders in version 2 of the PHP SDK, including select, create, update, delete, insert, and relate.

The fluent builders compile a statement and run it through the connection. Each builder method on Surreal returns a builder object you configure with chained calls, then run with execute() or inspect with compile().

All builders extend QueryBuilder in the SurrealDB\SDK\Query namespace.

Shared methods

Every builder provides these methods.

Method	Returns	Description
`execute()`	`mixed`	Run the statement and return the first statement's result
`compile()`	`BoundQuery`	Compile to SurrealQL and bindings without running
`json(bool $json = true)`	`static`	Request JSON-compatible results

Raw queries

`run()`

Execute raw SurrealQL with optional bindings. Returns one result per statement.

Syntax

$db->run(string $surql, array $bindings = []): array

[$people] = $db->run('SELECT * FROM person WHERE age > $min', ['min' => 18]);

`query()`

Execute a pre-built BoundQuery. Returns one result per statement.

Syntax

$db->query(BoundQuery $query): array

`select()`

Start a SELECT. Accepts a RecordId, Table, or string target.

Methods

->fields(string ...$fields)   // SELECT specific fields
->value(string $field)        // SELECT VALUE for one field
->where(string|BoundQuery $cond)
->start(int $start)
->limit(int $limit)
->fetch(string ...$fields)    // resolve record links
->timeout(string $duration)   // e.g. "5s"
->version(string $datetime)   // historical read

$people = $db->select(new Table('person'))
    ->fields('name', 'age')
    ->where('age >= 18')
    ->limit(10)
    ->execute();

`create()`

Start a CREATE. Accepts a RecordId, Table, or string target.

Methods

->content(array|object $data)       // CONTENT
->patch(array $patches)             // PATCH
->output(Output $output)            // RETURN clause
->timeout(string $duration)
->version(string $datetime)

$person = $db->create(new RecordId('person', 'tobie'))
    ->content(['name' => 'Tobie'])
    ->execute();

`update()` and `upsert()`

Start an UPDATE or UPSERT. update() modifies existing records; upsert() creates the record if it does not exist.

Methods

->content(array|object $data)   // replace the record
->merge(array|object $data)     // merge fields
->replace(array|object $data)   // REPLACE
->patch(array $patches)         // JSON Patch
->where(string|BoundQuery $cond)
->output(Output $output)
->timeout(string $duration)

$db->update(new RecordId('person', 'tobie'))
    ->merge(['age' => 33])
    ->execute();

$db->upsert(new RecordId('person', 'tobie'))
    ->content(['name' => 'Tobie', 'age' => 33])
    ->execute();

`delete()`

Start a DELETE. It defaults to RETURN BEFORE, so deleted records are returned.

Methods

->output(Output $output)
->timeout(string $duration)
->version(string $datetime)

$db->delete(new RecordId('person', 'tobie'))->execute();

`insert()`

Start an INSERT. Pass a target table and records, or records alone when each carries its own ID.

Methods

->relation()   // INSERT RELATION
->ignore()     // INSERT IGNORE
->output(Output $output)
->timeout(string $duration)
->version(string $datetime)

$db->insert(new Table('person'), [
    ['name' => 'Alice'],
    ['name' => 'Bob'],
])->execute();

`relate()`

Start a RELATE, creating one or more graph edges.

Methods

->content(array|object $data)   // store data on the edge
->unique()
->output(Output $output)
->timeout(string $duration)
->version(string $datetime)

$db->relate(
    new RecordId('person', 'tobie'),
    new Table('likes'),
    new RecordId('post', 'surrealdb'),
)->content(['since' => 2024])->execute();

`call()`

Invoke a SurrealQL or SurrealML function by name. run() already handles raw SurrealQL, so function invocation has its own method.

Syntax

$db->call(string $name, ?string $version = null, array $args = []): RunQuery

$greeting = $db->call('fn::greet', null, ['Tobie'])->execute();

`auth()`

Compile to SELECT * FROM ONLY $auth, returning the authenticated record user.

$me = $db->auth()->execute();

Modifiers

Output

output() accepts the SurrealDB\SDK\Enum\Output enum: NONE, NULL_, DIFF, BEFORE, AFTER.

use SurrealDB\SDK\Enum\Output;

$db->update(new RecordId('person', 'tobie'))
    ->merge(['age' => 33])
    ->output(Output::AFTER)
    ->execute();

Where

where() accepts a SurrealQL string or a BoundQuery fragment. Use a BoundQuery to keep dynamic values parameterised.

Timeout

timeout() accepts a SurrealQL duration string such as 5s or 1m30s.

Shared methods

Raw queries

run()

query()

select()

create()

update() and upsert()

delete()

insert()

relate()

call()

auth()

Modifiers

Output

Where

Timeout

See also

`run()`

`query()`

`select()`

`create()`

`update()` and `upsert()`

`delete()`

`insert()`

`relate()`

`call()`

`auth()`