# Data manipulation

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()`](/docs/reference/kotlin/api/core/surreal-client.md#select) or [`.create()`](/docs/reference/kotlin/api/core/surreal-client.md#create)) returns a [query builder](/docs/reference/kotlin/api/core/query-builder.md) that you refine and then terminate with `await()` (raw [`JsonElement`](/docs/reference/kotlin/concepts/value-types.md)) or the typed [`awaitAs<T>()`](/docs/reference/kotlin/api/core/query-builder.md#await-as) extension. Under the hood these compile to [SurrealQL](/docs/reference/query-language.md) and dispatch through [`.query()`](/docs/reference/kotlin/concepts/executing-queries.md), mirroring the [JavaScript SDK](/docs/languages/javascript.md).

## API references

<table>
	<thead>
		<tr>
			<th scope="col">Method</th>
			<th scope="col">Description</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#select"><code>client.select(what)</code></a></td>
			<td scope="row" data-label="Description">Selects records from a table or record</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#create"><code>client.create(what)</code></a></td>
			<td scope="row" data-label="Description">Creates a record</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#update"><code>client.update(what)</code></a></td>
			<td scope="row" data-label="Description">Replaces the content of records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#upsert"><code>client.upsert(what)</code></a></td>
			<td scope="row" data-label="Description">Creates or updates records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#merge"><code>client.merge(what, data)</code></a></td>
			<td scope="row" data-label="Description">Merges data into records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#patch"><code>client.patch(what, patches)</code></a></td>
			<td scope="row" data-label="Description">Applies JSON patches to records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#delete"><code>client.delete(what)</code></a></td>
			<td scope="row" data-label="Description">Deletes records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#relate"><code>client.relate(in, relation, out)</code></a></td>
			<td scope="row" data-label="Description">Creates a graph edge between records</td>
		</tr>
		<tr>
			<td scope="row" data-label="Method"><a href="/docs/reference/kotlin/api/core/surreal-client.md#insert"><code>client.insert(into, data)</code></a></td>
			<td scope="row" data-label="Description">Inserts one or more records</td>
		</tr>
	</tbody>
</table>

The `what` argument accepts a [`Table`](/docs/reference/kotlin/api/values/table.md) to target every record in a table, a [`RecordId`](/docs/reference/kotlin/api/values/record-id.md) to target a single record, or a [`RecordIdRange`](/docs/reference/kotlin/api/values/record-id-range.md) to target a range.

## Creating records

Build content with [`buildJsonObject`](/docs/reference/kotlin/concepts/value-types.md) and finish with the typed [`awaitAs<T>()`](/docs/reference/kotlin/api/core/query-builder.md#await-as).

```kotlin
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`](/docs/reference/kotlin/api/core/query-builder.md#select-query) with [`.where()`](/docs/reference/kotlin/api/core/query-builder.md), [`.limit()`](/docs/reference/kotlin/api/core/query-builder.md), [`.start()`](/docs/reference/kotlin/api/core/query-builder.md), [`.fetch()`](/docs/reference/kotlin/api/core/query-builder.md), and others, using the [expression helpers](/docs/reference/kotlin/api/core/query-builder.md#expressions).

```kotlin
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()`](/docs/reference/kotlin/api/core/surreal-client.md#update) to replace record content, [`.merge()`](/docs/reference/kotlin/api/core/surreal-client.md#merge) to merge data, or [`.upsert()`](/docs/reference/kotlin/api/core/surreal-client.md#upsert) to create or update. Control the returned payload with [`.returnMode()`](/docs/reference/kotlin/api/core/query-builder.md#return-mode-type).

```kotlin
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

```kotlin
import com.surrealdb.kotlin.query.RecordId

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

## Relating records

Create a graph edge between two records with [`.relate()`](/docs/reference/kotlin/api/core/surreal-client.md#relate).

```kotlin
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](/docs/reference/kotlin/api/core/query-builder.md) for every builder method and expression helper
- [Executing queries](/docs/reference/kotlin/concepts/executing-queries.md) for raw SurrealQL
- [Value types](/docs/reference/kotlin/concepts/value-types.md) for `Table`, `RecordId`, and the JSON model
- [Serialisation](/docs/reference/kotlin/concepts/serialization.md) for decoding into your own types