Speeding Up Read‑Heavy CouchDB Workloads with Mango JSON Indexes

The problem: ad‑hoc map/reduce slowing down reads

In a read‑heavy workload, applications often issue ad‑hoc queries that CouchDB serves by running temporary map/reduce views. As the dataset grows, each query scans more documents, causing higher latency and increased CPU usage. This pattern becomes a bottleneck when the same filter (for example, selecting all documents where type equals order) is executed many times per second.

Introducing Mango JSON indexes

CouchDB 3.0+ includes Mango, a declarative query engine that can use JSON indexes. A Mango index is defined with a simple JSON structure and is kept up‑to‑date automatically whenever documents are inserted, updated, or deleted. When a query’s selector matches an indexed field, CouchDB can satisfy the request directly from the index, avoiding a full scan.

Worked example: indexing the type field

1. Verify the server version – run this command on any machine that can reach the CouchDB node (you need only read access to the /_node endpoint):
   

   curl -s http://localhost:5984/_node/_local/_couchdb | jq .version

   The response should contain a version string like "3.2.1". If the version is lower than 3.0, Mango indexes are not available.
2. Create the index – assuming a database named orders, send a POST to /_index. You must have the _admin or _design role on the database:
   

   curl -X POST http://localhost:5984/orders/_index \ -H "Content-Type: application/json" \ -d '{"index":{"fields":[{"type":"asc"}]},"name":"type-index","type":"json"}'

   A successful response includes "result":"created" and the design document ID (e.g., "_design/index-name").
3. Run a query that uses the index – with read (_reader) access you can execute a Mango find:
   

   curl -X POST http://localhost:5984/orders/_find \ -H "Content-Type: application/json" \ -d '{"selector":{"type":"order"},"limit":100}'

   If the index is being used, the query returns only documents whose type field equals order and the response time should be noticeably lower than the equivalent ad‑hoc map/reduce view.
4. Validate that the index is active – check the index size and status via the /_index endpoint or look at active tasks:
   

   curl -s http://localhost:5984/orders/_index/type-index | jq .

   You should see fields such as "def" (the index definition) and "searchable": true. Additionally, /_active_tasks will list an indexer task that completes quickly after the initial build.

Trade‑offs and limitations

• Index rebuild cost – creating or changing an index triggers a background rebuild that reads every document in the database. On a heavily updated system this can cause temporary latency spikes and increase disk usage until the build finishes.
• Storage overhead – each index consumes additional disk space proportional to the number of indexed fields and the cardinality of their values. Monitor /_node/_local/_couchdb/db-name size or use /_stats to watch growth.
• Definition errors – a malformed JSON index (wrong field name, missing type, unsupported operator) will cause the index creation to fail or, worse, produce an index that returns incomplete results. Always validate the definition with a small test set before applying it to production.
• Version requirement – Mango indexes require CouchDB 3.0 or newer. Older clusters must be upgraded or continue using traditional views.

Actionable closing

To decide whether a Mango index is right for your read‑heavy pattern:

1. Confirm you are running CouchDB 3.0+.
2. Identify the fields that appear frequently in selectors (e.g., type, status, created_at).
3. Create a test index on a staging database, run representative queries, and compare latency against the existing map/reduce approach.
4. Watch /_active_tasks and disk usage during the initial build; schedule the index creation during a low‑traffic window if necessary.
5. Once validated, promote the index to production and keep an eye on the index size via /_stats or /_node/_local/_couchdb/db-name.

When the index is in place, queries that filter on the indexed fields will be served directly from the index, reducing scan‑related latency and freeing CPU for other work. Remember to revisit the index definition if your query patterns evolve, and to test any changes in a non‑environment first.