A newer version of this documentation is available.

View Latest

Architecture Overview

    Couchbase Server is a distributed, open source NoSQL database engine. The core architecture is designed to simplify building modern applications with a flexible data model and simpler high availability, high scalability, high performance, and advanced security.

    Couchbase Server consists of a single package that is installed on all nodes. Using the SDKs, 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 architecture, it is important to understand both the core components of the system and the behavior of core run time capabilities.

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

    The following are the core runtime systems within Couchbase Server:

    The runtimes such as replication, storage, caching, and so on can be tuned to the needs of different services within the system. Couchbase Server also consists of the following services:


    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, Search, 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 indexers:

    • Incremental Map-Reduce View indexer

    • Global Secondary Index (GSI) indexer

    • Spatial Views indexer

    • Full Text Search 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, both MapReduce view and spatial view indexers provide direct access to the indexes through the View API. Both the indexers are placed within the data service as they are partition-aligned to the core data distribution.

    + The full text search indexer (Developer Preview) provides direct access to indexers through the FTS API. FTS index is placed within its own service (FTS service) for independent scalability.

    + 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

    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.

    Full text search indexer provides a Search API that can perform keyword searches directly on data in Couchbase Server. Search API is available through the Search service.

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