Decision Guide: Couchbase Global Secondary Index vs MapReduce View for N1QL Queries

Decision and constraints

Choose a Couchbase Global Secondary Index (GSI) when you need low‑latency, ad‑hoc N1QL queries and your working set fits in memory. Choose a MapReduce View when you require built‑in reduce functions, are running on Couchbase Server <5.5 (where GSI is not available), or prefer a lower memory footprint at the cost of higher query latency.

Constraints to consider:

• GSI memory consumption grows with the number of indexed fields and replica count.
• View indexes are stored on disk and rebuilt incrementally, which reduces RAM usage but can increase latency when stale data is present.
• Both index types benefit from setting numReplicas ≥ 1 for high availability; ensure the cluster has enough nodes to host replicas.

Comparison table

Dimension	Global Secondary Index (GSI)	MapReduce View
Typical query latency	Sub‑millisecond to a few milliseconds (parallel scan)	Higher latency due to on‑demand rebuild; typically tens of milliseconds
Throughput	High for point lookups and range scans; limited by index builder CPU	Moderate; limited by disk I/O during view compaction
Storage overhead	In‑memory plus disk; proportional to indexed fields × replicas	Disk‑only; smaller memory footprint
Operational complexity	Monitor index builder threads, hot‑spot CPU, and memory pressure	Schedule view compaction, manage fragmented disk space
Version support	Available from Couchbase Server 5.5 onward	Available in all versions
Best‑fit use case	Ad‑hoc N1QL, covering indexes, low‑latency OLTP	Incremental aggregations, legacy apps, environments <5.5

Trade‑offs

• GSI advantages: parallel index scans, support for a wide range of N1QL predicates, ability to create covering indexes that eliminate fetch from data.
• GSI disadvantages: higher RAM and CPU usage during index maintenance; creating many indexes can cause hot‑spot CPU on the index builder threads.
• View advantages: built‑in reduce functions (_sum, _count, _stats), durable on‑disk storage with lower memory consumption.
• View disadvantages: stale‑until‑updated semantics (require stale=false for fresh results), slower ad‑hoc queries, need manual or scheduled compaction to reclaim space.

Concrete implementation and validation

The following steps show how to create a GSI and a View on the same field, verify index usage, and check replica durability. Run each command in the indicated location with the noted permissions.

1. Prepare a test bucket

Admin UI or CLI: create a bucket named travel-sample (or use the existing sample bucket). Ensure you have the Cluster Admin role.

2. Create a GSI on the age field

Run in the cbq shell (requires Query Admin or Cluster Admin):

cbq -u Administrator -p password -s \
  "CREATE INDEX idx_age ON \`travel-sample\`(age);"

Expected check: the command returns Success. No output is invented; verify via the Admin UI under Indexes.

3. Confirm GSI usage with EXPLAIN

Still in cbq:

EXPLAIN SELECT * FROM \`travel-sample\` WHERE age > 30;

Look for a line similar to "index": "idx_age" in the plan output. This indicates the planner chose the GSI.

4. Create a MapReduce View emitting age

Use the REST API (requires Admin credentials) from a terminal:

curl -u Administrator:password -X PUT \
  http://localhost:8092/travel-sample/_design/age_view \
  -H "Content-Type: application/json" \
  -d '{
    "views": {
      "by_age": {
        "map": "function (doc) { if (doc.age) { emit(doc.age, null); } }"
      }
    }
  }'

Expected check: HTTP 200 OK with JSON containing "ok":true. Verify the view appears under the bucket’s Views tab.

5. Query the View with fresh results

In a terminal:

curl -u Administrator:password \
  "http://localhost:8093/travel-sample/_design/age_view/_view/by_age?stale=false&limit=5"

Expected check: JSON response includes "rows" array. Note the response time; it will typically be higher than the GSI query.

6. Validate replica durability

Set one replica for both indexes (default when creating with numReplicas=1). Then fail over a node via the Admin UI or cbfailover. After failover:

• Run cbstats localhost:11210 all | grep idx_age to see replica_count.
• Repeat the GSI EXPLAIN and View query; both should still return results without error.

Expected check: replica count shows 1 and queries succeed. No data loss is assumed; this step only confirms that the index service continues to serve requests.

Limitations and practical verification

GSI: monitor index_builder threads via cbstats; high CPU may indicate over‑indexing. Mitigate by creating only necessary covering indexes. Views: ensure auto‑compaction is enabled (Settings → Auto‑Compaction) to prevent disk fragmentation. Verify compaction runs by checking the views log for compaction entries. By following the steps above you can objectively compare latency, resource usage, and operational effort for GSI versus View indexes in your specific workload.