Data manipulation | SurrealDB

Create, read, update, and delete records with the fluent builders in the SurrealDB Kotlin SDK.

The Kotlin SDK provides fluent builders for the common CRUD operations. Each builder method (such as .select() or .create()) returns a query builder that you refine and then terminate with await() (raw JsonElement) or the typed awaitAs<T>() extension. Under the hood these compile to SurrealQL and dispatch through .query(), mirroring the JavaScript SDK.

API references

Method	Description
`client.select(what)`	Selects records from a table or record
`client.create(what)`	Creates a record
`client.update(what)`	Replaces the content of records
`client.upsert(what)`	Creates or updates records
`client.merge(what, data)`	Merges data into records
`client.patch(what, patches)`	Applies JSON patches to records
`client.delete(what)`	Deletes records
`client.relate(in, relation, out)`	Creates a graph edge between records
`client.insert(into, data)`	Inserts one or more records

The what argument accepts a Table to target every record in a table, a RecordId to target a single record, or a RecordIdRange to target a range.

Creating records

Build content with buildJsonObject and finish with the typed awaitAs<T>().

import com.surrealdb.kotlin.query.RecordId
import com.surrealdb.kotlin.query.awaitAs
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

@Serializable
data class Person(val name: String, val age: Int)

val ada: Person = client
    .create(RecordId("person", "ada"))
    .content(buildJsonObject {
        put("name", "Ada")
        put("age", 36)
    })
    .awaitAs()

Selecting records

Refine a select with .where(), .limit(), .start(), .fetch(), and others, using the expression helpers.

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

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

Updating and merging

Use .update() to replace record content, .merge() to merge data, or .upsert() to create or update. Control the returned payload with .returnMode().

import com.surrealdb.kotlin.query.RecordId
import com.surrealdb.kotlin.query.ReturnMode
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

client
    .merge(RecordId("person", "ada"), buildJsonObject { put("age", 37) })
    .returnMode(ReturnMode.After)
    .await()

Deleting records

import com.surrealdb.kotlin.query.RecordId

client.delete(RecordId("person", "ada")).await()

Relating records

Create a graph edge between two records with .relate().

import com.surrealdb.kotlin.query.RecordId
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

client
    .relate(RecordId("person", "ada"), RecordId("wrote", "w1"), RecordId("article", "a1"))
    .content(buildJsonObject { put("year", 1843) })
    .await()

Learn more

Query builder reference for every builder method and expression helper
Executing queries for raw SurrealQL
Value types for Table, RecordId, and the JSON model
Serialization for decoding into your own types