A newer version of this documentation is available.

View Latest

Couchbase Server architecture

Couchbase Server is an open source scalable NoSQL database engine. The core architecture is designed to simplify building modern applications with a flexible data model and core database platform abilities ranging from high availability, high scalability, high performance all the way to security.

Couchbase Server consists of a single package that is installed on all nodes. Using SDKs (also known as smart client connectivity libraries), you can write applications in the language of your choice (Java, node.js, .NET, or others). The applications connect to a Couchbase Server cluster to perform read and write operations, and run queries with low latencies (sub millisecond) and high throughput (millions of operations per second).

To understand the Couchbase Server’s runtime behavior, it is important to understand the high level connectivity, replication, storage, caching, and security runtimes. For more information about the core runtime behavior, see the following topics:

The Couchbase Server consists of the following core components: Cluster Manager, Data service, Index service, and Query service. The runtime behaviors such as replication, storage, caching, and so on can be tuned to the needs of the different services. For more information about the core components, see the sections under Cluster manager and Services architecture.

server cluster single node type
Figure 1. Nodes, services, and cluster


Couchbase services are components that run specific independent workloads within the cluster. Databases handle three distinct workloads: core data operations, indexing, and query processing. Couchbase Server includes Data, Index, and Query Services to enable independent deployment of these workloads within a cluster.

Each node can run all services or a subset of the services. As an administrator, you can create unique topologies using these independent services and independently scale the three workloads. For more information, see Services architecture and multidimensional scaling.

Core data access and data service

Data Service provides the key-value API that you can use to perform CRUD operations (create, retrieve, update, and delete) on items with keys within buckets. For more information, see Data service and core data access.

Indexing and index service

Indexes provide faster access to data in a bucket. Couchbase Server supports the following three indexers:

  • Incremental Map-Reduce View indexer

  • Global Secondary Index (GSI) indexer

  • Spatial Views indexer

    Using these indexers, you can create two types of indexes:

  • Primary indexes which index all the keys in a given bucket and are used when a secondary index cannot be used to satisfy a query and a full bucket scan is required.

  • Secondary indexes can index a subset of the items in a given bucket and are used to make queries targeting a specific subset of fields more efficient.

In Couchbase Server, Views (both Incremental Map-Reduce Views and Spatial Views) are placed within the data service as they are partition-aligned to the core data distribution. The Global Secondary Indexes (GSI) are deployed on nodes hosting the index service and can be independently partitioned for better performance and throughput with N1QL queries. For more information about indexers and index services, see Views, indexing, and index services.

Querying data and query service

You can retrieve data in a number of ways in Couchbase Server depending on the type of query.

  • Querying with keys

    Data service and core data operations provide a key based lookup. You can retrieve items based on the item key using the key-value API.

  • Querying with value, document, or document attribute

    • With N1QL, you can query JSON documents using SQL-like syntax. You can also run ad-hoc queries with filters and aggregates over JSON data and reshape the JSON output. N1QL API is available through the query service.

    • Incremental Map-Reduce views provide a View API that can query data based on the keys defined by a view. Views can define the keys using the MapReduce functions in JavaScript. Incremental Map-Reduce view API are available through data service.

    • Spatial views provide a Spatial View API that can query data based on a bounding box (rectangle with coordinates). Spatial views define the attributes that signify the coordinates a given item represents using the MapReduce functions in JavaScript. Spatial view API is available through the data service.

For more information about querying and retrieving data, see Querying data and query service.