A newer version of this documentation is available.

View Latest

Client topology awareness

All Couchbase clients are automatically aware of the topology of the Couchbase Server cluster that they are connected to and transparently maintain this awareness for all 3 services (data, index, query) across any topology change or failure. An application will typically be configured with the IP addresses of more than one Couchbase Server node for high availability when bootstrapping into the cluster.

When interacting with the data service, Couchbase clients directly access any document in a Couchbase Server cluster, without consulting a proxy or external routing entity. This works because they store and transparently update a local copy of the complete cluster map based on topology change notifications from the Couchbase Server. In order to locate the active copy of any stored object, a Couchbase client uses a CRC32 hashing algorithm on the key and the list of vBuckets (1024) to identify which vBucket is responsible for that key. The client then consults its internal cluster map to determine which node is currently active for that vBucket. The access request is then sent directly to the node itself, without needing to lookup the location of that item in any external authority. This is a faster, more efficient, more robust, and more scalable approach than routing through sharding proxies or performing meta-data lookups each operation.

Similar topology awareness is used to maintain a list of nodes running the N1QL query service, and that service in turn uses the same underlying cluster map when servicing queries. The query service itself is stateless, so any query node can process any N1QL request.