Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Partitioned Indexes

    • Sync Gateway 3.3
      +

      Partitioning a large index across multiple nodes
      Explains how to use partitioned indexes in Sync Gateway

      Related Deploy topics: Deployment | REST API Access | Legacy Pre-3.0 Configuration

      Overview

      Partitioned indexes in Sync Gateway offer horizontal scalability for large deployments by sharding indexes across multiple nodes. This can decrease performance, as each partition is queried separately and results are aggregated. Only allDocs and channels indexes can be partitioned.

      When to Use Partitioned Indexes

      Partitioned indexes are an optimization in Sync Gateway intended only for deployments using Memory-Optimized Indexes (MOI) on Couchbase Server, and only when those MOI indexes have grown too large to fit on a single index node.

      Recommendation

      Partitioned indexes should not be used for experimentation or general performance tuning. Partitioning should be configured only after careful evaluation. It increases resource usage (CPU and memory) on Query nodes, and may introduce performance degradation.

      Appropriate Use Case

      • You are using MOI.

      • Your current GSI index size exceeds the memory capacity of a single index node.

      • You cannot further split your data (for example, by collections or database sharding) to reduce index size.

      In this case, partitioning can help by horizontally scaling the index across multiple nodes to keep it in memory.

      When Not to Use Partitioned Indexes

      • You’re not using MOI; that is, your indexes are disk-based.

      • Your dataset is small or moderate in size, even if you have high concurrency.

      • You have a high number of connections or clients, but not many documents.

      • Your index size could be reduced by splitting data into multiple collections, which is the preferred approach.

      What Impacts Index Size?

      The size of Sync Gateway’s indexes is correlated to:

      • The number of documents in a collection.

      • The number of channels each document is assigned to.

      If index size is a concern, your first approach should be to split documents across multiple collections.

      Query performance is sensitive to channel design. Systems with many small channels tend to perform worse than those using fewer, larger channels. For better scalability and efficiency, prefer broader channel groupings over fine-grained ones.

      Only if these strategies are exhausted, and you’re using MOI with oversized indexes, should partitioned indexes be considered.

      Migrate to Partitioned Indexes

      Before switching from non-partitioned to partitioned indexes, it’s important to understand the operational trade-offs and cluster implications. Here are two migration options, designed to accommodate different use cases and resource tolerances.

      Option 1: Zero Downtime (Recommended for Production)

      This option is ideal for production environments where uptime is critical. It requires temporary over-provisioning of index nodes (2× size) while partitioned indexes are created. The advantage is no downtime; the disadvantage is temporarily higher resource usage.

      Procedure

      1. Spin up a new Sync Gateway instance.

      2. Run POST /{db}/_index_init on the new instance with num_partitions set to the required number of partitions.

      3. Wait for completion via GET /{db}/_index_init.

      4. Run POST /{db}/_config with index.num_partitions updated in the configuration to use new indexes.

      5. Run POST /_post_upgrade to remove old indexes.

      6. Optionally, rebalance index nodes using Couchbase Server. For details, see Index Redistribution in the Couchbase Server documentation.

      If you are using configuration groups running on a different index configuration, calling POST /_post_upgrade can delete indexes out from under a running database. Please ensure that all configuration groups have consistent index configuration. For details, see Configuration Group Considerations.

      Option 2: With Downtime

      This option requires no extra resources, but involves planned downtime. It involves lower intermittent hardware requirements.

      Procedure

      1. Take the database offline via POST /{db}/_config with offline set to true.

      2. Manually delete old Sync Gateway indexes.

      3. Bring the database online using POST /{db}/_config with index.num_partitions set to the required number of partitions.

      4. Run integration and performance testing.

      Manual index deletion can cause data loss or leave the system in an unstable state. Incorrect deletion of internal indexes can lead to system instability and requires full index rebuilds. We strongly advise using the standard procedure with zero downtime, unless you are fully aware of the implications.

      Guardrails

      To prevent misconfiguration or accidental misuse, follow these best practices:

      • Never change the number of partitions without a plan. Indexes are not deletable from Couchbase Server once creation starts. Reverting requires downtime and manual deletion. Make sure only advanced users (typically Architects or Admins) modify partitioning settings.

      • Monitor memory and disk usage on index nodes during and after creation to catch unexpected bloat.

      • Optionally set feature flags or config validation, if available, to restrict low-risk deployments from using this feature.

      Changing the number of partitions "just to test it" may permanently increase index footprint, cause cluster performance issues, and trigger long rebalance operations.

      Configuration Group Considerations

      If your deployment uses Configuration Groups, ensure that:

      • All nodes are updated with the new config before running POST /_post_upgrade.

      • Import and sync workloads are not unintentionally unbalanced across partitions.

      Misalignment between config groups can lead to unexpected deletion of active indexes if POST /_post_upgrade is run. This will result in:

      • Couchbase Server (version 7.6 and later) falling back on a sequential scan of the Query nodes, which will seriously degrade Query performance.

      • Recreating indexes that were deleted by another config when a node is rebooted with a different index.num_partitions, even after POST /_post_upgrade is run.

      Supportability

      Identify Index Configuration

      To identify the current index configuration, you can:

      Identify Failures

      To troubleshoot problems with index configurations, note the following.

      • The status returned by GET /{db}/_index_init includes last_error.

      • Partial updates across nodes using Configuration Groups may result in mixed indexing behavior.

      • If indexes are not removed post-upgrade, POST /_post_upgrade may return a failure or partial success.

      Related Content

      API Topics
      Reference
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials