Live Queries

Description — Couchbase mobile database live query concepts

Overview

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

/*
static void query_change_listener(void* context, CBLQuery* query, CBLListenerToken* token) {
    CBLError err = {};
    CBLResultSet* results = CBLQuery_CopyCurrentResults(query, token, &err);
    while(CBLResultSet_Next(results)) {
        // Update UI
    }
}
*/

// NOTE: No error handling, for brevity (see getting started)

CBLError err = {};
CBLQuery* query = CBLDatabase_CreateQuery(database, kCBLN1QLLanguage,
    FLSTR("SELECT * FROM _"), NULL, &err); (1)

CBLListenerToken* token = CBLQuery_AddChangeListener(query, query_change_listener, NULL); (2)

// NOTE: No error handling, for brevity (see getting started)
cbl::Query query(database, kCBLN1QLLanguage, "SELECT * FROM _"); (1)

// The listener is invoked with the current results whenever they change
auto token = query.addChangeListener([](cbl::Query::Change change) { (2)
    for (cbl::Result result : change.results()) {
        // Update UI
    }
});

1 Build the query statements

Activate the live query by attaching a listener. Save the token to detach the listener and stop the query later — see Example 2

C++

Unresolved include directive in modules/c/pages/query-live.adoc - include::c:example$code_snippets/cbl_cpp.cpp[]

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 — see Example 2

Example 2. Stop a Live Query

C

CBLListener_Remove(token); // The token received from AddChangeListener
CBLQuery_Release(query);

C++

token.remove(); // The token received from addChangeListener

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

C++

Unresolved include directive in modules/c/pages/query-live.adoc - include::c:example$code_snippets/cbl_cpp.cpp[]

1	Here we use the change listener token from Example 1 to remove the listener. Doing so stops the live query.