Kotlin Legacy→DQL Migration Guide

ditto.store.execute(
    query = "SELECT * FROM cars WHERE color = :color",
    arguments = mapOf("color" to "red")
)

ditto.store.collection("cars")
    .find("color == $0", "red")
    .exec()

ditto.store.execute(
    query = "INSERT INTO cars DOCUMENTS (:car)",
    arguments = mapOf("car" to mapOf("_id" to id, "color" to "blue"))
)

ditto.store.collection("cars")
    .upsert(mapOf("_id" to id, "color" to "blue"))

ditto.store.execute(
    query = "UPDATE cars SET color = :color WHERE _id = :id",
    arguments = mapOf("color" to "green", "id" to id)
)

// Upsert document
ditto.store.collection("cars")
    .upsert(mapOf("_id" to id, "color" to "green"))

// Update with closure
ditto.store.collection("cars")
    .findById(id)
    .update { doc -> doc["color"].set("green") }

ditto.store.execute(
    query = "DELETE FROM cars WHERE _id = :id",
    arguments = mapOf("id" to id)
)

ditto.store.collection("cars").findById(id).remove()

// Evict by ID
ditto.store.execute(
    query = "EVICT FROM cars WHERE _id = :id",
    arguments = mapOf("id" to id)
)

// Evict all matching documents
ditto.store.execute(
    query = "EVICT FROM cars WHERE color = :color",
    arguments = mapOf("color" to "red")
)

// Evict by ID
ditto.store.collection("cars").findById(id).evict()

// Evict all matching documents
ditto.store.collection("cars").findAll().evict()

// store.execute(query, args) returns Unit in v5. Pass a handler to inspect the
// result (auto-closed when the lambda returns), or call store.executeRaw() and
// close the result yourself.
val color: String = ditto.store.execute(
    query = "SELECT color FROM cars WHERE _id = :id",
    arguments = mapOf("id" to id),
) { result ->
    // item.value is DittoCborSerializable.Dictionary. Use typed accessors —
    // e.g. .string / .stringOrNull / .intOrNull — not Kotlin casts.
    result.items.first().value["color"].string
}

val document: DittoDocument = collection.findById(res.id).exec()
val color = document.value["color"] as String

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class Car(val _id: String, val color: String)

private val carJson = Json { ignoreUnknownKeys = true }

// Inside the handler (which auto-closes the result), decode each item to plain
// Kotlin data via item.jsonString(). Do NOT return DittoQueryResultItem out of
// the lambda — its native lifetime ends when the handler returns.
val cars: List<Car> = ditto.store.execute(
    "SELECT * FROM cars",
) { result ->
    result.items.map { carJson.decodeFromString<Car>(it.jsonString()) }
}

fun documentToCar(doc: DittoDocument): Car {
    return Car(
        id = doc.value["_id"] as String,
        color = doc.value["color"] as String
    )
}

import com.ditto.kotlin.DittoStoreObserver
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

// In v5, the differ is internal — the observer owns it. Use the `(result, diff)`
// overload of registerObserver; closing the observer frees the differ.
class MainFragment : Fragment() {
    private var observer: DittoStoreObserver? = null
    private var previousDocumentIds: List<String> = emptyList()

    private fun startLiveQuery() {
        observer?.close()

        observer = ditto.store.registerObserver(
            query = "SELECT * FROM cars WHERE _id.locationId = :locationId",
            arguments = mapOf("locationId" to Constants.locationId),
        ) { result, diff ->
            // Extract IDs as plain Kotlin strings inside the lambda — never store
            // result.items or DittoQueryResultItem instances; they are closed as
            // soon as this lambda returns (use-after-free otherwise).
            val currentDocumentIds = result.items.map { item ->
                val id = item.value["_id"].stringOrNull ?: "unknown"
                item.dematerialize()
                id
            }

            for (index in diff.deletions) {
                previousDocumentIds.getOrNull(index)?.let { deletedId ->
                    println("Deleted car with ID: $deletedId")
                }
            }
            for (index in diff.insertions) {
                currentDocumentIds.getOrNull(index)?.let { insertedId ->
                    println("Inserted car with ID: $insertedId")
                }
            }
            for (index in diff.updates) {
                currentDocumentIds.getOrNull(index)?.let { updatedId ->
                    println("Updated car with ID: $updatedId")
                }
            }

            previousDocumentIds = currentDocumentIds

            // The handler is suspend — use withContext, not runOnUiThread.
            withContext(Dispatchers.Main) {
                // Update your adapter / UI here using `currentDocumentIds` + diff.
            }
        }
    }

    override fun onDestroyView() {
        super.onDestroyView()
        observer?.close()
    }
}

liveQuery = CarsApplication.carsCollection?.find("_id.locationId == '${Constants.locationId}'")?.observeLocal { docs, event ->
    println("Live query handler called. Event: $event Docs count: ${docs.count()}")
    when (event) {
        is DittoLiveQueryEvent.Update -> {
            requireActivity().runOnUiThread {
                val adapter = (viewAdapter as CarsAdapter)
                adapter.set(docs)
                adapter.delete(event.deletions)
                adapter.insert(event.insertions)
                adapter.update(event.updates)
            }
        }
        is DittoLiveQueryEvent.Initial -> {
            requireActivity().runOnUiThread {
                val carTotal = (viewAdapter as CarsAdapter).setInitialCars(docs)
                if (carTotal > 0) {
                    recyclerView.scrollToPosition(carTotal - 1)
                }
            }
        }
    }
}

val subscription = ditto.sync.registerSubscription(
    query = "SELECT * FROM cars WHERE color = :color",
    arguments = mapOf("color" to "red")
)

val subscription = ditto.store.collection("cars")
    .find("color == $0", "red")
    .subscribe()

val subscription = ditto.sync.registerSubscription(
    query = "SELECT * FROM cars WHERE _id.locationId = :locationId",
    arguments = mapOf("locationId" to Constants.locationId)
)

val subscription = ditto.store.collection("cars")
    .find("_id.locationId == '${Constants.locationId}'")
    .subscribe()

val subscriptions = mutableListOf<DittoSyncSubscription>()
subscriptions.add(
    ditto.sync.registerSubscription(
        query = "SELECT * FROM cars WHERE color = :color",
        arguments = mapOf("color" to "red")
    )
)
subscriptions.add(
    ditto.sync.registerSubscription(
        query = "SELECT * FROM cars WHERE year > :year",
        arguments = mapOf("year" to 2020)
    )
)

val subscriptions = mutableListOf<DittoSubscription>()
subscriptions.add(
    ditto.store.collection("cars")
        .find("color == 'red'")
        .subscribe()
)
subscriptions.add(
    ditto.store.collection("cars")
        .find("year > 2020")
        .subscribe()
)

subscription.cancel()

subscription.cancel()

val subscription = ditto.sync.registerSubscription(
    "SELECT * FROM cars"
)

val subscription = ditto.store.collection("cars")
    .findAll()
    .subscribe()

ditto.store.execute(
    query = "UPDATE cars APPLY numUpdates PN_INCREMENT BY :increment WHERE _id = :id",
    arguments = mapOf("increment" to 1, "id" to id)
)

ditto.store.collection("cars")
    .findById(id)
    .update { doc ->
        doc["numUpdates"].counter?.increment(amount = 1.0)
    }

ditto.store.execute(
    query = "UPDATE cars APPLY viewCount PN_INCREMENT BY :decrement WHERE _id = :id",
    arguments = mapOf("decrement" to -1, "id" to id)
)

ditto.store.collection("cars")
    .findById(id)
    .update { doc ->
        doc["viewCount"].counter?.increment(amount = -1.0)
    }

// Counter fields are automatically created on first PN_INCREMENT use
ditto.store.execute(
    query = "INSERT INTO cars DOCUMENTS (:car)",
    arguments = mapOf("car" to mapOf(
        "_id" to id,
        "color" to "blue"
        // Do NOT initialize counter fields - they are created on first PN_INCREMENT
    ))
)

// Then use PN_INCREMENT with APPLY clause to create and increment the counter
ditto.store.execute(
    query = "UPDATE cars APPLY numUpdates PN_INCREMENT BY 1 WHERE _id = :id",
    arguments = mapOf("id" to id)
)

val carData = mapOf(
    "_id" to id,
    "color" to "blue",
    "numUpdates" to DittoCounter()
)
ditto.store.collection("cars").upsert(carData)

ditto.store.execute(
    """UPDATE cars
       APPLY likes PN_INCREMENT BY :likeIncrement,
             dislikes PN_INCREMENT BY :dislikeDecrement,
             views PN_INCREMENT BY :viewIncrement
       WHERE _id = :id""",
    mapOf(
        "likeIncrement" to 1,
        "dislikeDecrement" to -1,
        "viewIncrement" to 1,
        "id" to id
    )
)

ditto.store.collection("cars")
    .findById(id)
    .update { doc ->
        doc["likes"].counter?.increment(amount = 1.0)
        doc["dislikes"].counter?.increment(amount = -1.0)
        doc["views"].counter?.increment(amount = 1.0)
    }