Data manipulation

The Kotlin SDK provides fluent builders for the common CRUD operations. Each builder method (such as [`.select()`](/docs/reference/kotlin/api/core/surreal-client#select) or [`.create()`](/docs/reference/kotlin/api/core/surreal-client#create)) returns a [query builder](/docs/reference/kotlin/api/core/query-builder) that you refine and then terminate with `await()` (raw [`JsonElement`](/docs/reference/kotlin/concepts/value-types)) or the typed [`awaitAs()`](/docs/reference/kotlin/api/core/query-builder#await-as) extension. Under the hood these compile to [SurrealQL](/docs/reference/query-language) and dispatch through [`.query()`](/docs/reference/kotlin/concepts/executing-queries), mirroring the [JavaScript SDK](/docs/languages/javascript).

API references

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`](/docs/reference/kotlin/concepts/value-types) and finish with the typed [`awaitAs()`](/docs/reference/kotlin/api/core/query-builder#await-as).

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