Building an index

Building an index

To retrieve the information you want, you query a view and receive a result set from Couchbase Server. There are two possible types of views which influence when Couchbase Server will actually build an index based on that view:

  • Development : when you query a view that is still in development, by default Couchbase Server will create an index using a subset of all entries. A view that is still under development is known as a development view and will always be stored with the naming convention _design/dev_viewname where _design is a directory containing all views and the prefix dev_ indicates it is a development view. These views are editable in Couchbase Admin Console

  • Production : these views are known as production views and are available to all processes that have access/credentials to Couchbase Server; they are the views you make available to a live production application built on Couchbase Server. Couchbase Server will create an index based on entries that are stored on disk. The naming convention for production views is _design/viewname where _design is the directory containing all views. Production views are not editable in Couchbase Admin Console.

When you are almost done with design and testing of a view, you can query the development view and have Couchbase Server index based on the entire set of entries. This becomes a matter of best practice that you create an index based on all entries shortly before you put a view into production. Generating an index may take several hours over a large database, and you will want a fairly complete index to already be available as soon as you put the view into production.

When Couchbase Server creates an index based on a view, it sorts results based on the keys. The server puts keys in order based on factors such as:

  • alphabetical order
  • numeric order
  • object type or value.

The real-time nature of Couchbase Server means that an index can become outdated fairly quickly when new entries and updates occur. Couchbase Server generates the index when it is queried, but in the meantime more data can be added to the server and this information will not yet be part of the index. To resolve this, Couchbase SDKs and the REST API provide a stale parameter you use when you query a view. With this parameter you can indicate you will accept the most current index as it is, you want to trigger a refresh of the index and retrieve these results, or you want to retrieve the existing index as is but also trigger a refresh of the index. For instance, to query a view with the stale parameter using the Ruby SDK:

doc.recent_posts(:body => {:stale => :ok}) 

In this case, we query a view named recent_posts in a design document named doc . In the query we pass the parameter :stale set to the value :ok to indicate that Couchbase Server can return the most current index as it exists. For more detailed information about the stale parameter, consult the Language Reference for your SDK.