With Couchbase Server 4.x, customers used to create Equivalent Indexes to satisfy the twin requirements of keeping the indexes highly available and to load balance the N1QL queries. What this meant was that the exact same index definition was used to create indexes with different names. What’s in a name you might ask… a rose is a rose is a rose ;)

N1QL queries could hit either of the two indexes based on the load seen by each of these indexes; and also, if either of the indexes were to go down, the other index would continue to serve the query traffic. There were a few challenges with equivalent indexes, namely:

  1. You had to manually create indexes with different names
  2. There was no simplified scheme for distributing the indexes across the chosen index nodes. When index nodes were added or removed, it was a manual operation to create such index copies again.
  3. Queries using the USE Index hint or Prepared Statements used to fall apart if the index  node was lost, due to the close affinity with the multiple index names.

With Couchbase Server 5.0, you can transition from using Equivalent Indexes to Index Replicas. With Index Replicas, you need to fire the index definition only once, but state either the number of replicas you want or the nodes on which they have to be placed, and thereafter, Couchbase takes care of all the work of apportioning the query traffic and also rebalancing suitably when nodes are added or removed. When enough replicas remain in the system(i.e, if not all nodes containing the index replicas are down), Index Service ensures that the indexes remains online even during system failures. If an index scan fails in one of the replicas, then the scan will be tried in another replica. As soon as any of the replicas are created, the index service starts sending the query traffic.

IF you use the num_replica parameter while creating the index, the index service creates additional replicas as mentioned in the parameter. So, if the num_replica were 2, then there are 3(num_replica + 1) copies of the index(i.e, 2 extra copies). Do note:

  • if there are lesser nodes compared to the num_replica, then the create_index fails with a readable message stating that indexer node count is not enough to create the index with the replica count specified. Hence, it is advisable that number of indexer nodes be greater than the num_replica specified in the create index statement.
  • Couchbase picks the nodes that have fewest indexes; and does not place more than one copy of the index(i.e, replica) on the same node.
  • If index nodes are spread into server groups(Rack Zone Awareness), then Couchbase spreads out the replicas to as many server groups as possible. If the replica count is more than the number of server groups, then some of the server groups will have more replicas than the rest.

If you want to manually specify the nodes on which to create the indexes, then it is possible by replacing the num_replica parameter with the ‘nodes’ parameter.

It is advisable that while using this syntax with the ‘nodes’ parameter specified, you choose the nodes that are on multiple server groups; this syntax gives the flexibility of choosing the nodes, but unlike the syntax wherein num_replica is used, Couchbase Index Service does not override the supplied node settings by the user.

All the replicas continue to receive the query traffic; that is, there is no concept of a master-slave in index replicas and all the index replicas are active. This helps in load balancing.

Moving Index Replicas

If the index(along with its replicas) is spread out on the nodes : “”, “”, “” And if you want to manually move a replica (say to a different node, the following REST call (to be fired on any of the indexing nodes) gets the job done:

Couchbase knows that only the replica on “″ needs to be moved to “″ and does not touch the replicas on “″ and “″; and hence only one replica is moved.

Move index does not change(increase or decrease) the count of replicas; the number of nodes to be mentioned in the ‘nodes’ parameter in this REST call has to match with the number of nodes on which the replicas are already spread out.

Drop Index

Drop index statement drops all replicas. Till all the replicas are dropped, the Index remains online. 

How to transition/move from equivalent indexes to index replicas? Read more here.

Index Replicas are supported for both MOI and GSI(Plasma) in Couchbase Server 5.0. The challenges that were cited earlier with equivalent indexes do not exist with Index Replicas. Click here to download Couchbase Server 5.0 and play around with Index Replicas. You can leave your comments at our Forum.


Posted by Venkat Subramanian, Product Manager

Venkat dabbles in product development and product management and has been developing data/analytics platforms & products. Significant chunk of his experience has been with Oracle, where he transitioned from being an Engineer in Oracle’s Enterprise Manager team to Product Manager for Oracle's BI/Analytics suite of products. He has worked in startups in the past helping develop machine-learning/NLP products and distributed decisioning systems. He lurks around at @venkasub.

One Comment

  1. “Index Replicas are supported for both MOI and GSI(Plasma) in Couchbase Server 5.0”

    Does that mean they are not supported for GSI(ForestDB) indexes (i.e. Community Edition indexes)?

Leave a reply