Couchbase Server Manual 2.0 - Chapter 9. Views and Indexes - 9.2.4. Index Updates and the stale Parameter

9.2.4. Index Updates and the `stale` Parameter
Prev	9.2. View Operation	Next

9.2.4. Index Updates and the `stale` Parameter

Indexes are created by Couchbase Server based on the view definition, but updating of these indexes can be controlled at the point of data querying, rather than each time data is inserted. Whether the index is updated when queried can be controlled through the stale parameter.

Note

Irrespective of the stale parameter, documents can only be indexed by the system once the document has been persisted to disk. If the document has not been persisted to disk, use of the stale will not force this process. You can use the observe operation to monitor when documents are persisted to disk and/or updated in the index.

Note

Views can also be updated automatically according to a document change, or interval count. See Section 9.2.5, “Automated Index Updates”.

Three values for stale are supported:

stale=ok
The index is not updated. If an index exists for the given view, then the information in the current index is used as the basis for the query and the results are returned accordingly.
Figure 9.3. Views — Index Updates — Stale OK

This setting results in the fastest response times to a given query, since the existing index will be used without being updated. However, this risks returning incomplete information if changes have been made to the database and these documents would otherwise be included in the given view.
stale=false
The index is updated before the query is executed. This ensures that any documents updated (and persisted to disk) are included in the view. The client will wait until the index has been updated before the query has executed, and therefore the response will be delayed until the updated index is available.
Figure 9.4. Views — Index Updates — Update Before
stale=update_after
This is the default setting if no stale parameter is specified. The existing index is used as the basis of the query, but the index is marked for updating once the results have been returned to the client.
Figure 9.5. Views — Index Updates — Update After

Warning

The indexing engine is an asynchronous process; this means querying an index may produce results you may 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. This is because the document updates have not yet been committed to disk, which is the point when the updates are indexed.

This also means that deleted documents may still appear in the index even after deletion because the deleted document has not yet been removed from the index.

For both scenarios, you should use an observe command from a client with the persistto argument to verify the persistent state for the document, then force an update of the view using stale=false. This will ensure that the document is correctly updated in the view index. For more information, see Couchbase Developer Guide, Using Observe.

When you have multiple clients accessing an index, the index update process and results returned to clients depend on the parameters passed by each client and the sequence that the clients interact with the server.

Situation 1
1. Client 1 queries view with stale=false
2. Client 1 waits until server updates the index
3. Client 2 queries view with stale=false while re-indexing from Client 1 still in progress
4. Client 2 will wait until existing index process triggered by Client 1 completes. Client 2 gets updated index.
Situation 2
1. Client 1 queries view with stale=false
2. Client 1 waits until server updates the index
3. Client 2 queries view with stale=ok while re-indexing from Client 1 in progress
4. Client 2 will get the existing index
Situation 3
1. Client 1 queries view with stale=false
2. Client 1 waits until server updates the index
3. Client 2 queries view with stale=update_after
4. If re-indexing from Client 1 not done, Client 2 gets the existing index. If re-indexing from Client 1 done, Client 2 gets this updated index and triggers re-indexing.

Note

Index updates may be stacked if multiple clients request that the view is updated before the information is returned (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 stale=update_after queries, no stacking is performed, since all updates occur after the query has been accessed.

Sequential accesses

Client 1 queries view with stale=ok
Client 2 queries view with stale=false
View gets updated
Client 1 queries a second time view with stale=ok
Client 1 gets the updated view version

The above scenario can cause problems when paginating over a number of records as the record sequence may change between individual queries.

Prev	Up	Next
9.2.3. View Performance	Home	9.2.5. Automated Index Updates