A newer version of this documentation is available.

Live Queries

March 23, 2025

+ 12

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.

Example 1. Starting a LIve Query

objc
Copy
CBLQuery *query = [CBLQueryBuilder select:@[[CBLQuerySelectResult all]]
                                     from:[CBLQueryDataSource database:database]];

// Adds a query change listener.
// Changes will be posted on the main queue.
id<CBLListenerToken> token = [query addChangeListener:^(CBLQueryChange * _Nonnull change) // <.>{
    for (CBLQueryResultSet *result in [change results]) {
        NSLog(@"%@", result);
        /* Update UI */
    }
}];

// Start live query.
[query execute: &error]; (1)

1	Build the query statements using the QuerybUilder
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
3	Start the query This will immediately execute the live query and post the result to the change listener. When a change is detected the query automatically runs, and posts the new query result to any observers (change listeners).

Example 2. Stop a LIve Query

objc
Copy
[query removeChangeListenerWithToken:token]; (1)

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