SurrealClient

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

SurrealClient(config)

Returns: SurrealClient

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

.connect()

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

client.connect()

Returns: Unit

client.connect()

.close()

Closes the active connection and releases all associated resources.

client.close()

Returns: Unit

client.close()

.use(namespace, database)

Selects the namespace and database for subsequent operations.

client.use(namespace, database)

Returns: JsonElement

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

.ping()

Pings the server to verify connectivity.

client.ping()

Returns: JsonElement

.version()

Returns the version of the connected SurrealDB server.

client.version()

Returns: JsonElement

val version = client.version()

.supports(feature)

Returns whether the current transport supports the given SurrealFeature.

client.supports(feature)

Returns: Boolean

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

Authentication methods

.signup(params)

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

client.signup(params)

Returns: JsonElement

.signin(params)

Signs in with the given credentials and returns a token.

client.signin(params)

Returns: JsonElement

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

.authenticate(token)

Authenticates the session with an existing token.

client.authenticate(token)

Returns: JsonElement

.auth()

Returns the record of the currently authenticated user.

client.auth()

Returns: JsonElement

.invalidate()

Invalidates the current authentication for the session.

client.invalidate()

Returns: JsonElement

.reset()

Resets the session to its initial, unauthenticated state.

client.reset()

Returns: JsonElement

Query methods

.query(sql, vars)

Runs a raw SurrealQL statement with optional bound parameters.

client.query(sql, vars)

Returns: JsonElement

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.

client.queryAs<T>(sql, vars)

Returns: T

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

.decode<T>(element)

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

client.decode<T>(element)

Returns: T

.let(key, value)

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

client.let(key, value)

Returns: JsonElement

.unset(key)

Removes a previously defined session parameter.

client.unset(key)

Returns: JsonElement

CRUD methods

These methods return a [query builder](/docs/reference/kotlin/api/core/query-builder) that you refine and terminate with `await()` or [`awaitAs()`](/docs/reference/kotlin/api/core/query-builder#await-as). The `what` argument accepts a [`Table`](/docs/reference/kotlin/api/values/table), [`RecordId`](/docs/reference/kotlin/api/values/record-id), or [`RecordIdRange`](/docs/reference/kotlin/api/values/record-id-range).

.select(what)

Returns a SelectQuery for reading records.

client.select(what)

Returns: SelectQuery

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

.create(what)

Returns a CreateQuery for inserting a record.

client.create(what)

Returns: CreateQuery

.update(what)

Returns an UpdateQuery for replacing record content.

client.update(what)

Returns: UpdateQuery

.upsert(what)

Returns an UpsertQuery for creating or updating records.

client.upsert(what)

Returns: UpsertQuery

.merge(what, data)

Returns a MergeQuery that merges data into the matched records.

client.merge(what, data)

Returns: MergeQuery

.patch(what, patches, diff)

Returns a PatchQuery that applies JSON Patch operations.

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

Returns: PatchQuery

.delete(what)

Returns a DeleteQuery for removing records.

client.delete(what)

Returns: DeleteQuery

.relate(in, relation, out)

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

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

Returns: RelateQuery

.insert(into, data)

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

client.insert(into, data)

Returns: InsertQuery

.insertRelation(into, data)

Returns an InsertRelationQuery that inserts relation records into a Table.

client.insertRelation(into, data)

Returns: InsertRelationQuery

.run(function)

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

client.run(function)

Returns: RunQuery

Live query methods

.live(table, diff)

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

client.live(table, diff = null)

Returns: LiveQuerySubscription

.kill(liveQueryId)

Kills a live query by its ID. WebSocket only.

client.kill(liveQueryId)

Returns: JsonElement

Sessions

.newSession()

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

client.newSession()

Returns: SurrealSession

.closeSession(session)

Closes a session previously created with .newSession().

client.closeSession(session)

Returns: Unit

Properties

Learn more

• •

  Client configuration

• •

  Session

• •

  Query builder

• •

  Features and events

• •

  Errors