SurrealClient

The SurrealClient class is the main entry point for connecting to and interacting with a SurrealDB instance from Kotlin.

The SurrealClient class is the main entry point for the Kotlin SDK. It connects to a SurrealDB instance, authenticates, queries, and manages data. It extends SurrealSession and implements AutoCloseable. Almost every networked method is a suspend function and has a ...Result companion that returns a Result instead of throwing.

Source: surrealdb.kotlin

Import

import com.surrealdb.kotlin.SurrealClient
import com.surrealdb.kotlin.SurrealClientConfig

Connection methods

`SurrealClient(config)`

Creates a new client from a SurrealClientConfig. With autoConnect = true (the default) the client connects lazily on the first request.

Method Syntax

SurrealClient(config)

Parameter	Type	Description
`config`	`SurrealClientConfig`	The client configuration, including the connection `url`.

Returns: SurrealClient

Example

val client = SurrealClient(SurrealClientConfig(url = "ws://localhost:8000"))

`.connect()`

Establishes the connection explicitly. Rarely needed when autoConnect is enabled.

Method Syntax

client.connect()

Returns: Unit

Example

client.connect()

`.close()`

Closes the active connection and releases all associated resources.

Method Syntax

client.close()

Returns: Unit

Example

client.close()

`.use(namespace, database)`

Selects the namespace and database for subsequent operations.

Method Syntax

client.use(namespace, database)

Parameter	Type	Description
`namespace`	`String`	The namespace to select.
`database`	`String`	The database to select.

Returns: JsonElement

Example

client.use("surrealdb", "docs")

`.ping()`

Pings the server to verify connectivity.

Method Syntax

client.ping()

Returns: JsonElement

`.version()`

Returns the version of the connected SurrealDB server.

Method Syntax

client.version()

Returns: JsonElement

Example

val version = client.version()

`.supports(feature)`

Returns whether the current transport supports the given SurrealFeature.

Method Syntax

client.supports(feature)

Parameter	Type	Description
`feature`	`SurrealFeature`	The feature to check.

Returns: Boolean

Example

if (client.supports(SurrealFeature.LiveQueries)) { /* ... */ }

Authentication methods

`.signup(params)`

Signs up against a record access method and returns a token.

Method Syntax

client.signup(params)

Parameter	Type	Description
`params`	`JsonObject`	The sign-up parameters (namespace, database, access, and any record variables).

Returns: JsonElement

`.signin(params)`

Signs in with the given credentials and returns a token.

Method Syntax

client.signin(params)

Parameter	Type	Description
`params`	`JsonObject`	The sign-in credentials.

Returns: JsonElement

Example

client.signin(buildJsonObject {
    put("user", "root")
    put("pass", "root")
})

`.authenticate(token)`

Authenticates the session with an existing token.

Method Syntax

client.authenticate(token)

Parameter	Type	Description
`token`	`String`	A JWT previously issued by SurrealDB.

Returns: JsonElement

`.auth()`

Returns the record of the currently authenticated user.

Method Syntax

client.auth()

Returns: JsonElement

`.invalidate()`

Invalidates the current authentication for the session.

Method Syntax

client.invalidate()

Returns: JsonElement

`.reset()`

Resets the session to its initial, unauthenticated state.

Method Syntax

client.reset()

Returns: JsonElement

Query methods

`.query(sql, vars)`

Runs a raw SurrealQL statement with optional bound parameters.

Method Syntax

client.query(sql, vars)

Parameter	Type	Description
`sql`	`String`	The SurrealQL to execute.
`vars`	`JsonObject?`	Optional parameters bound as `$name` in the query.

Returns: JsonElement

Example

val result = client.query(
    "SELECT * FROM person WHERE age > \$min",
    buildJsonObject { put("min", 18) },
)

There is also an overload that accepts a BoundQuery built with the surql DSL.

`.queryAs<T>(sql, vars)`

Runs SurrealQL and decodes the result into T using kotlinx.serialization.

Method Syntax

client.queryAs<T>(sql, vars)

Returns: T

Example

val people: List<Person> = client.queryAs("SELECT * FROM person")

`.decode<T>(element)`

Decodes a JsonElement into T using the client's configured Json instance.

Method Syntax

client.decode<T>(element)

Returns: T

`.let(key, value)`

Defines a session parameter referenced as $key in subsequent queries.

Method Syntax

client.let(key, value)

Parameter	Type	Description
`key`	`String`	The parameter name.
`value`	`JsonElement`	The parameter value.

Returns: JsonElement

`.unset(key)`

Removes a previously defined session parameter.

Method Syntax

client.unset(key)

Returns: JsonElement

CRUD methods

These methods return a query builder that you refine and terminate with await() or awaitAs<T>(). The what argument accepts a Table, RecordId, or RecordIdRange.

`.select(what)`

Returns a SelectQuery for reading records.

Method Syntax

client.select(what)

Returns: SelectQuery

Example

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

`.create(what)`

Returns a CreateQuery for inserting a record.

Method Syntax

client.create(what)

Returns: CreateQuery

`.update(what)`

Returns an UpdateQuery for replacing record content.

Method Syntax

client.update(what)

Returns: UpdateQuery

`.upsert(what)`

Returns an UpsertQuery for creating or updating records.

Method Syntax

client.upsert(what)

Returns: UpsertQuery

`.merge(what, data)`

Returns a MergeQuery that merges data into the matched records.

Method Syntax

client.merge(what, data)

Returns: MergeQuery

`.patch(what, patches, diff)`

Returns a PatchQuery that applies JSON Patch operations.

Method Syntax

client.patch(what, patches, diff = false)

Returns: PatchQuery

`.delete(what)`

Returns a DeleteQuery for removing records.

Method Syntax

client.delete(what)

Returns: DeleteQuery

`.relate(in, relation, out)`

Returns a RelateQuery that creates a graph edge between two records.

Method Syntax

client.relate(`in`, relation, out)

Returns: RelateQuery

`.insert(into, data)`

Returns an InsertQuery that inserts one or more records into a Table.

Method Syntax

client.insert(into, data)

Returns: InsertQuery

`.insertRelation(into, data)`

Returns an InsertRelationQuery that inserts relation records into a Table.

Method Syntax

client.insertRelation(into, data)

Returns: InsertRelationQuery

`.run(function)`

Returns a RunQuery that invokes a built-in or custom function.

Method Syntax

client.run(function)

Returns: RunQuery

Live query methods

`.live(table, diff)`

Starts a live query and returns a LiveQuerySubscription. WebSocket only.

Method Syntax

client.live(table, diff = null)

Parameter	Type	Description
`table`	`String`	The table to watch.
`diff`	`Boolean?`	When `true`, emit JSON Patch diffs instead of full records.

Returns: LiveQuerySubscription

`.kill(liveQueryId)`

Kills a live query by its ID. WebSocket only.

Method Syntax

client.kill(liveQueryId)

Returns: JsonElement

Sessions

`.newSession()`

Creates a new isolated SurrealSession over the same connection. WebSocket only.

Method Syntax

client.newSession()

Returns: SurrealSession

`.closeSession(session)`

Closes a session previously created with .newSession().

Method Syntax

client.closeSession(session)

Returns: Unit

Properties

Property	Type	Description
`config`	`SurrealClientConfig`	The configuration the client was created with.
`features`	`Set<SurrealFeature>`	The features supported by the active transport.
`connectionEvents`	`SharedFlow<SurrealConnectionEvent>`	A flow of connection lifecycle events.
`json`	`Json`	The `kotlinx.serialization` instance used for encoding and decoding.

Connection methods

SurrealClient(config)

.connect()

.close()

.use(namespace, database)

.ping()

.version()

.supports(feature)

Authentication methods

.signup(params)

.signin(params)

.authenticate(token)

.auth()

.invalidate()

.reset()

Query methods

.query(sql, vars)

.queryAs<T>(sql, vars)

.decode<T>(element)

.let(key, value)

.unset(key)

CRUD methods

.select(what)

.create(what)

.update(what)

.upsert(what)

.merge(what, data)

.patch(what, patches, diff)

.delete(what)

.relate(in, relation, out)

.insert(into, data)

.insertRelation(into, data)

.run(function)

Live query methods

.live(table, diff)

.kill(liveQueryId)

Sessions

.newSession()

.closeSession(session)

Properties

Learn more

`SurrealClient(config)`

`.connect()`

`.close()`

`.use(namespace, database)`

`.ping()`

`.version()`

`.supports(feature)`

`.signup(params)`

`.signin(params)`

`.authenticate(token)`

`.auth()`

`.invalidate()`

`.reset()`

`.query(sql, vars)`

`.queryAs<T>(sql, vars)`

`.decode<T>(element)`

`.let(key, value)`

`.unset(key)`

`.select(what)`

`.create(what)`

`.update(what)`

`.upsert(what)`

`.merge(what, data)`

`.patch(what, patches, diff)`

`.delete(what)`

`.relate(in, relation, out)`

`.insert(into, data)`

`.insertRelation(into, data)`

`.run(function)`

`.live(table, diff)`

`.kill(liveQueryId)`

`.newSession()`

`.closeSession(session)`