Query builders | SurrealDB

The fluent query builders, expression helpers, and surql DSL of the SurrealDB Kotlin SDK.

The CRUD methods on [`SurrealClient`](/docs/reference/kotlin/api/core/surreal-client) return fluent builders that compile to [SurrealQL](/docs/reference/query-language). Each builder is refined with chainable methods and terminated with [`await()`](#await) (raw [`JsonElement`](/docs/reference/kotlin/api/values/value)) or the typed [`awaitAs()`](#await-as) extension.

Source: surrealdb.kotlin

Import

import com.surrealdb.kotlin.query.awaitAs
import com.surrealdb.kotlin.query.field
import com.surrealdb.kotlin.query.gte

Terminal methods

`.await()`

Executes the builder and returns the unwrapped result of the first statement as a JsonElement.

Method Syntax

builder.await()

Returns: JsonElement

`.awaitRaw()`

Executes the builder and returns the raw [{ status, result, time, type }] response envelope.

Method Syntax

builder.awaitRaw()

Returns: JsonElement

`.awaitAs<T>()`

An inline extension that executes the builder and decodes the result into T using kotlinx.serialization. Available on every builder.

Method Syntax

builder.awaitAs<T>()

Returns: T

Example

val people: List<Person> = client.select(Table("person")).awaitAs()

`.compile()`

Compiles the builder to a BoundQuery without executing it — useful for inspection or composing with .query().

Method Syntax

builder.compile()

Returns: BoundQuery

`SelectQuery`

Returned by .select(what).

Method	Description
`.fields(vararg names)`	Selects specific fields.
`.value(field)`	Selects a single field's value.
`.where(expr)`	Filters with an expression .
`.start(n)`	Skips the first `n` records.
`.limit(n)`	Limits the number of records.
`.fetch(vararg fields)`	Fetches related records.
`.timeout(seconds)`	Sets a query timeout.
`.version(literal)`	Reads at a specific version.

Example

val adults: List<Person> = client
    .select(Table("person"))
    .where(field("age") gte 18)
    .limit(50)
    .awaitAs()

Content builders

CreateQuery, UpdateQuery, UpsertQuery, and RelateQuery accept content and a return mode.

Method	Description
`.content(data)`	Sets the record content (a `JsonElement` ).
`.where(expr)`	Filters affected records (update, upsert, merge, patch, delete).
`.returnMode(mode)`	Controls the returned payload (see ReturnMode ).

Method

Description

.content(data)

Sets the record content (a

JsonElement

.where(expr)

Filters affected records (update, upsert, merge, patch, delete).

.returnMode(mode)

Controls the returned payload (see

ReturnMode

`ReturnMode`

Import

import com.surrealdb.kotlin.query.ReturnMode

Value	Description
`ReturnMode.None`	Returns nothing.
`ReturnMode.Before`	Returns records as they were before the change.
`ReturnMode.After`	Returns records after the change.
`ReturnMode.Diff`	Returns a JSON Patch diff.
`ReturnMode.Fields(names)`	Returns only the named fields.

`RunQuery`

Returned by .run(function).

Method	Description
`.args(vararg args)`	Sets the function arguments.
`.version(version)`	Selects a function version.

Expression helpers

Build WHERE expressions with the helper functions and infix operators from com.surrealdb.kotlin.query.

Import

import com.surrealdb.kotlin.query.field
import com.surrealdb.kotlin.query.value
import com.surrealdb.kotlin.query.gte
import com.surrealdb.kotlin.query.and

Helper	SurrealQL
`field(name)`	A validated field reference.
`value(any)`	A literal value.
`raw(boundQuery)`	A raw fragment.
`a eq b`	`=`
`a neq b`	`!=`
`a lt b`	`<`
`a lte b`	`<=`
`a gt b`	`>`
`a gte b`	`>=`
`a contains b`	`CONTAINS`
`a inside b`	`IN`
`a and b`	`AND`
`a or b`	`OR`
`not(expr)`	`!`

Note

Inequality is neq (not ne) and membership is inside (not in, which is a reserved Kotlin keyword).

Example

import com.surrealdb.kotlin.query.field
import com.surrealdb.kotlin.query.gte
import com.surrealdb.kotlin.query.eq
import com.surrealdb.kotlin.query.and

val expr = (field("age") gte 18) and (field("active") eq true)
val results = client.select(Table("person")).where(expr).awaitAs<List<Person>>()

`surql` DSL

The surql helpers build a parameterised BoundQuery with automatic, injection-safe binding of values and record identifiers.

Import

import com.surrealdb.kotlin.query.surql

Example

// Vararg bindings
val a = surql("SELECT * FROM person WHERE age > \$min", "min" to 25)

// Builder block
val b = surql {
    +"SELECT * FROM person WHERE age > "
    param("min", 25)
}

val result = client.query(a)

Learn more

SurrealClient API reference for the CRUD methods
Data manipulation for the concepts
Serialization for awaitAs