Live Query — Working with Queries


    Description — Couchbase Lite database data querying concepts — live queries
    Related Content — Predictive Queries | Indexing | QueryBuilder

    Activating a Live Query

    A live query is a query that, once activated, remains active and monitors the database for changes; refreshing the result set whenever a change occurs. As such, it is a great way to build reactive user interfaces — especially table/list views — that keep themselves up to date.

    So, a simple use case may be: A replicator running and pulling new data from a server, whilst a live-query-driven UI automatically updates to show the data without the user having to manually refresh. This helps your app feel quick and responsive.

    To activate a LiveQuery just add a change listener to the query statement. It will be immediately active. When a change is detected the query automatically runs, and posts the new query result to any observers (change listeners).

    Example 1. Starting a Live Query
    • Kotlin

    • Java

    val query = QueryBuilder
        .from(DataSource.database(database)) (1)
    // Adds a query change listener.
    // Changes will be posted on the main queue.
    val token = query.addChangeListener { change ->
        change.results?.let {
            for (result in it) {
                Log.d(TAG, "results: ${result.keys}")
                /* Update UI */
        } (2)
    Query query = QueryBuilder
        .from(DataSource.database(database)); (1)
    // Adds a query change listener.
    // Changes will be posted on the main queue.
    ListenerToken token = query.addChangeListener(change -> { (2)
        for (Result result : change.getResults()) {
            Log.d(TAG, "results: " + result.getKeys());
            /* Update UI */
    1 Build the query statements
    2 Activate the live query by attaching a listener. Save the token in order to detach the listener and stop the query later — se Example 2
    Example 2. Stop a LIve Query
    • Kotlin

    • Java

    query.removeChangeListener(token); (1)
    1 Here we use the change lister token from Example 1 to remove the listener. Doing so stops the live query.

    Using Kotlin Flows and LiveData

    Kotlin developers also have the option of using Flows and Live Data to feed query changes to the UI.

    Define a live query as a Flow returning a LiveData object and activate an Observer in the View onCreate() function.

        var liveQuery: LiveData<List<Any>?>? = null
        fun watchQuery(query: Query): LiveData<List<Any>?> {
            val queryFlow = query.queryChangeFlow()
                .map {
                    val err = it.error
                    if (err != null) {
                        throw err
                    it.results?.allResults()?.flatMap { it.toList() }
            liveQuery = queryFlow
            return queryFlow