Choosing Between Mango Queries and Map/Reduce Views in CouchDB

The Decision: Pick the Query Mechanism That Matches Your Access Pattern

CouchDB offers two fundamentally different ways to query data: the declarative Mango _find API and pre‑computed map/reduce views. The right choice depends on query flexibility, data volume, and consistency requirements. This guide states the decision, compares the options, and shows a concrete validation step you can run today.

Constraints and Assumptions

• CouchDB 3.x (behaviour also applies to 2.x with noted differences).
• You have database‑admin credentials to create design documents and indexes.
• Typical dataset size: tens of thousands to millions of documents.
• Read‑after‑write consistency matters for some endpoints; others can tolerate eventual consistency.

Comparison at a Glance

Aspect	Mango (_find)	Map/Reduce Views
Query style	Declarative JSON selector	Key‑range lookups on emitted keys
Index creation	Explicit JSON index via POST /db/_index	Design document with map (and optional reduce) functions
Ad‑hoc filtering	Supported (operators $eq, $gt, $in, …)	Only if composite keys were emitted beforehand
Sorting	Allowed when sort fields are covered by an index	Natural order of emitted keys; no extra cost
Aggregation	Limited (no server‑side reduce)	Built‑in reduce/rereduce for sums, counts, custom logic
Freshness control	Always reads current index state	stale=ok for fast but possibly stale results
Full‑scan risk	Warning field appears when no matching index	Never – view is pre‑built
Initial build cost	Index builds on creation (background)	Lazy on first query; can be triggered manually

Trade‑offs

When to Use Mango

Choose Mango when:

• Queries are unpredictable or change frequently.
• You need multi‑field filters without pre‑designing composite keys.
• Dataset is moderate (≤ ~500 k docs) or you can afford a dedicated index per query pattern.
• Strong read‑after‑write consistency is required.

Remember: every distinct selector shape should have a matching JSON index; otherwise CouchDB falls back to a full database scan, which degrades sharply as the document count grows.

When to Use Map/Reduce Views

Choose views when:

• Access paths are well‑known and stable (e.g., “all orders by customer + date”).
• You need sorted key‑range scans or server‑side aggregation (counts, sums, custom reduce).
• Write throughput is high and you can tolerate stale=ok for read‑heavy endpoints.
• You want predictable latency because the index is already materialised.

Views cannot filter on arbitrary fields unless those fields are part of the emitted key. Adding a new filter later means a new view or a new design document.

Concrete Validation: Use _explain to Prove Index Usage

The fastest way to verify that a Mango query will not trigger a full scan is to POST the same selector to /_explain. The response tells you exactly which index (if any) the planner will use.

Step‑by‑Step Example

1. Create a JSON index for the fields you plan to filter and sort.

   curl -X POST http://admin:pass@localhost:5984/mydb/_index \
     -H "Content-Type: application/json" \
     -d '{
       "index": {
         "fields": ["type", "status", "createdAt"]
       },
       "name": "type-status-createdAt",
       "type": "json"
     }'
   

   Run this from any machine that can reach the CouchDB HTTP API. The account must have _admin or database‑admin role. The placeholder mydb is your target database name.

2. Explain a representative selector.

   curl -X POST http://admin:pass@localhost:5984/mydb/_explain \
     -H "Content-Type: application/json" \
     -d '{
       "selector": {
         "type": "order",
         "status": { "$in": ["pending", "shipped"] },
         "createdAt": { "$gt": "2026-01-01" }
       },
       "sort": [{"createdAt": "desc"}]
     }'
   

   Inspect the JSON response. Look for a field index that matches the name you created (e.g., "index": "type-status-createdAt"). If you see "index": "_all_docs" or a warning about "no matching index", the query will scan the whole database.

3. Benchmark (optional) – run the same selector against _find and the equivalent view on a staging dataset of ~200 k documents. Compare latency and CPU. This confirms the practical impact of the planner’s choice.

Limitations and Practical Checks

• Version differences: Mango operator support (e.g., $regex) expanded in 3.x. Verify the operator list for your exact release.
• Index build time: JSON indexes build in the background; a query issued immediately after creation may still fall back to a scan. Wait for the _index endpoint to return "result": "created" and then poll /_index until "status": "ready".
• View staleness: Using stale=ok returns results from the last completed index update. After a bulk write, query the view once with stale=false (default) to force an update, then switch back to stale=ok for subsequent reads.
• Memory sorting limit: Mango can sort in‑memory only up to a configurable limit (default 1000 docs). If the result set exceeds that and the sort fields aren’t indexed, the request fails.

Quick Checklist Before Deploying

• ☐ Identify every distinct selector shape used in production.
• ☐ Create a matching JSON index for each shape (or a covering index).
• ☐ Run _explain for each selector; confirm the planner picks the index.
• ☐ For high‑volume, stable queries, implement a map/reduce view and test stale=ok vs. default.
• ☐ Document the index/view naming convention for future maintenance.

Following this decision framework lets you keep query latency predictable while avoiding the hidden cost of full‑database scans.