View consistency

View consistency

By default, views in Couchbase Server are eventually consistent. However, an application can alter this behavior using the stale parameter.

The stale parameter can be set to one of the following values:
false
This value specifies that the view engine must update the index before executing the view query. This ensures that all updated documents are included in the view. In this case, the response to the client may be delayed because the views engine must first update the index and then execute the query after the updated index is available.
Figure 1. Stale parameter set to "false"

update_after
This is the default value used when the stale parameter is not specified. The views engine uses the existing index as the basis of the query and marks the index to be updated after the results are returned to the client.
Figure 2. Stale parameter set to "update_after"

The indexing engine is an asynchronous process; this means querying an index may produce results you did not expect. For example, if you update a document and then immediately run a query on that document, you may not get the new information in the emitted view data.

For both scenarios, you can use an observe command from a client with the persistto argument to verify the persistent state for the document and then force an update of the view using stale=false. This ensures that the document is correctly updated in the view index.

ok
This value specifies that the view engine can use the existing index "as is" and does not need to update the index. As a result, this setting provides the fastest response times for a given query. However, if only stale=ok is used, the query will return incomplete information until the number of mutations trigger an index update.
Figure 3. Stale parameter set to "ok"

Important
Note: When an application sends a view request with stale=false, the result contains all the recent changes made to the documents at the time the query was made, including the changes that haven’t yet been persisted to disk. This means that you no longer need to use durability requirements such as observe to block for persistence in application code before issuing the stale=false query.
Best practice
Note: For better scalability and throughput, consider setting the stale parameter to " ok". Typically, even with stale set to ok, the data returned is closer to the key-value data, although it may not include all of it.

Multiple clients and index update

When multiple clients access an index, the index update process and results returned to the clients depends on the parameters passed by each client and the sequence in which the clients interact with the server. Consider the following scenarios.

Scenario 1
  • Client 1 queries view with stale=false.
  • Client 1 waits until server updates the index.
  • Client 2 queries view with stale=false while re-indexing from Client 1 is still in progress.
  • Client 2 waits until existing index process triggered by Client 1 completes. Client 2 gets an updated index.
Scenario 2
  • Client 1 queries view with stale=false.
  • Client 1 waits until server updates the index.
  • Client 2 queries view with stale=ok while re-indexing from Client 1 is still in progress.
  • Client 2 gets the existing index.
Scenario 3
  • Client 1 queries view with stale=false.
  • Client 1 waits until server updates the index.
  • Client 2 queries view with stale=update_after.
  • If re-indexing from Client 1 is not complete, Client 2 gets the existing index. If re-indexing from Client 1 has completed, Client 2 gets this updated index. It then triggers re-indexing.
Scenario 4: Sequential access
  • Client 1 queries view with stale=ok.
  • Client 2 queries view with stale=false.
  • Views are updated.
  • Client 1 queries a second time with stale=ok.
  • Client 1 gets the updated view.
Warning: This scenario can cause problems when paginating over a number of records as the record sequence may change between individual queries or if the number of mutations triggers an index update during pagination.

Index updates are stacked when multiple clients request the view to be updated before executing the query and returning the information(stale=false). This ensures that multiple clients updating and querying the index data get the updated document and version of the view each time. For queries with stale=update_after, the server does not perform stacking because all updates occur after the query has been executed.