A newer version of this documentation is available.

View Latest

Index Availability and Performance

The Index Service ensures availability and performance through replication and partitioning. The consistency of query-results can be controlled per query.

Index Replication

Secondary indexes can be replicated across cluster-nodes. This ensures:

  • Availability: If one Index-Service node is lost, the other continues to provide access to replicated indexes.

  • High Performance: If original and replica copies are available, incoming queries are load-balanced across them.

Index-replicas can be created with the N1QL CREATE INDEX statement. Note that whenever a given number of index-replicas is specified for creation, the number must be less than the number of cluster-nodes currently running the Index Service. If it is not, the index-creation fails. Note also that if, following creation of the maximum number of copies, the number of nodes running the Index Service decreases, Couchbase Server progressively assigns replacement index-replicas to any and all Index-Service nodes subsequently be added to the cluster, until the required number of index-replicas again exists for each replicated index.

Index-replicas can be created as follows:

  • Specifying, by means of the WITH clause, the destination nodes. In the following example, an index with two replicas is created. The active index is on node1, and the replicas are on node2 and node3:

    CREATE INDEX productName_index1 ON bucket_name(productName, ProductID)
        WHERE type="product" USING GSI
        WITH {"nodes":["node1:8091", "node2:8091", "node3:8091"]};
  • Specifying no destination nodes; but specifying instead, by means of the WITH clause and the num_replica attribute, only the number of replicas required. The replicas are automatically distributed across those nodes of the cluster that are running the Index Service: the distribution-pattern is based on a projection of optimal index-availability, given the number and disposition of Index-Service nodes across defined server-groups.

    In the following example, an index is created with two replicas, with no destination-nodes specified:

    CREATE INDEX productName_index1 ON bucket_name(productName, ProductID)
        WHERE type="product" USING GSI
        WITH {"num_replica": 2};

    Note that if nodes and num_replica are both specified in the WITH clause, the specified number of nodes must be one greater than num_replica.

  • Specifying a number of index-replicas to be created by the Index Service whenever CREATE INDEX is invoked. The default is 0. If the default is changed to, say, 2, creation of a single index is henceforth accompanied by the creation of two replicas, which are automatically distributed across the nodes of the cluster running the Index Service. No explicit specification within the CREATE INDEX statement is required.

    With credentials that provide appropriate authorization, this default can be changed; by means of the curl command, as follows:

    curl -u <username>:<password> <host>:9102/settings -d "{\"indexer.settings.num_replica\": <num_replicas>}"

    Note, however, that whenever explicit specification of replica-numbers is made within the CREATE INDEX statement, this explicit specification takes precedence over any established default.

For further information on using N1QL, see N1QL Language Reference.

Index Partitioning

Index Partitioning increases query performance, by dividing and spreading a large index of documents across multiple nodes. This feature is available only in Couchbase Server Enterprise Edition.

The benefits include:

  • The ability to scale out horizontally, as index size increases.

  • Transparency to queries, requiring no change to existing queries.

  • Reduction of query latency for large, aggregated queries; since partitions can be scanned in parallel.

  • Provision of a low-latency range query, while allowing indexes to be scaled out as needed.

For detailed information, see Index Partitioning.

Index Consistency

Whereas Couchbase Server handles data-mutations with full consistency — all mutations to a given key are applied to the same vBucket, and become immediately available — it maintains indexes with degrees of eventual consistency, determined by means of the following query consistency-options, specified per query:

  • not_bounded: Executes the query immediately, without requiring any consistency for the query. If index-maintenance is running behind, out-of-date results may be returned.

  • at_plus: Executes the query, requiring indexes first to be updated to the timestamp of the last update. If index-maintenance is running behind, the query waits for it to catch up.

  • request_plus: Executes the query, requiring the indexes first to be updated to the timestamp of the current query-request. If index-maintenance is running behind, the query waits for it to catch up.

For N1QL, the default consistency is not_bounded.