Query builders

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.

Raw queries

run()

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

$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.

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

select()

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

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

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

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

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

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

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

$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.

See also

• •

  Executing queries for the guide

• •

  Core classes for the Surreal entry point

• •

  Utilities for BoundQuery and the Output enum