CouchDB Indexes

A database index is a data structure that improves the speed of data retrieval operations on a database table at the cost of additional writes and storage space to maintain the index data structure.

Why are indexes important? Indexes allow a database to be queried without having to examine each row against each query, making them run faster and more efficiently. Normally, indexes are built for frequently occurring query criteria, allowing data to be queried more efficiently. To leverage the major benefit of CouchDB—an ability to perform rich queries against JSON data—indexes are not required, but they are strongly recommended for performance. In addition, if sorting is required in a query, CouchDB requires an index of the sorted fields.

Rich queries that do not have an index will work, but may throw a warning in the CouchDB log that the index was not found. However, if a rich query includes a sort specification, then an index on that field is required. Otherwise, the query will fail, and an error will be thrown.

Referring to the Object asset described in the previous section, an example of a simple indexOwner index for a field owner is shown below:

{
  "index": {
    "fields": [
      "owner"
    ]
  },
   "ddoc": "indexOwnerDoc",
   "name": "indexOwner",
   "type": "json"
}

The ddoc design document attribute can be optionally specified on the index definition. A design document is a CouchDB construct designed to contain indexes, which can be grouped into design documents for efficiency. However, it is recommended to use a single index per design document.

When defining an index, it is a good practice to include the ddoc attribute and value along with the index name. It is important to include this attribute to ensure that you can update the index later, if needed. Furthermore, it provides an ability to explicitly specify which index to use in a query. This can be done via the use_index attribute in the query string. You can see an example below:

{
  "selector": {
    "owner": "Alice",
  },
  "use_index": [
    "_design/indexOwnerDoc",
    "indexOwner"
  ]
}

Though specifying an index name in a query is optional, it is a good practice to explicitly include an index name in a query using the use_index keyword. If not specified, and an index already exists for the fields being queried, the existing index will be automatically used. However, under such a scenario, CouchDB may pick a less optimal index for your query without your knowledge. Only with higher volumes, you may face slow performance, because CouchDB is not using the appropriate index.

For more information on indexes, please consult the CouchDB index documentation.