Couchbase Reference

This section documents the current Couchbase Server 7.6.x line as published at the Couchbase Server documentation, which is the reference these pages are written and verified against. No specific patch version is pinned. Some capabilities (Enterprise-Edition-only Analytics, auditing, encryption at rest, the Backup service and rack-zone awareness, and Capella-only App Services and Columnar) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, as Couchbase iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Welcome to the Couchbase reference. Couchbase Server is a distributed, memory-first JSON document database that is also a key-value store: it stores each record as a JSON document addressed by a key, keeps its working set in memory for microsecond key-value access, exposes a SQL-like query language (*SQL*, formerly N1QL) and an aggregation-and-search stack through separately scalable *services*, and shards every bucket into 1024 vBuckets spread across the cluster with automatic replication and failover. This section documents the current Couchbase Server line as a database-developer reference -- the data model, the key-value and sub-document APIs, SQL, indexing, search, analytics and eventing, clustering and cross-datacenter replication, storage, security and operations, and the drivers — written and verified against the Couchbase Server documentation.

If you are new to Couchbase, read What Couchbase Server is & how to run it first, then Buckets, scopes & collections and Documents, keys, metadata & expiration, followed by Key-value & sub-document operations and Querying with SQL++. Everything after that builds on those foundations.

For the relational and document-database baselines this section contrasts with, see the sibling SQL Reference and MongoDB Reference, which the Couchbase pages cross-link rather than restate.

What’s covered

Getting started

What Couchbase Server is & how to run it — Couchbase as a distributed, memory-first document and key-value database, the document model versus the relational model, the services model and Multi-Dimensional Scaling, the Enterprise and Community editions and Capella, running a node, and driving it from the Web Console, cbq and Couchbase Shell.

Data & modeling

Buckets, scopes & collections — the bucket.scope.collection keyspace, the _default and _system namespaces, the Couchbase / Ephemeral / Memcached bucket types with their RAM, replica, durability and TTL settings, and how the keyspace path is written in SQL++, in the SDKs and in DDL.
Documents, keys, metadata & expiration — an item as key + value + metadata, document-key rules and patterns, JSON and binary values and the 20 MB limit, the CAS / expiry / flags metadata and Extended Attributes, TTL and expiry precedence with tombstones, and the SDK data structures.
Key-value & sub-document operations — the key-value API from Cluster to Collection, the CRUD verbs and their typed errors, atomic counters and binary append/prepend, KV Range Scan, bulk and reactive variants, and the lookupIn / mutateIn sub-document API.
Concurrency, locking & durable writes — optimistic concurrency with CAS and the compare-and-swap retry loop, pessimistic locking with getAndLock, the CAS-as-ETag pattern, and the majority / majorityAndPersistToActive / persistToMajority durable-write levels that supersede observe-based PersistTo / ReplicateTo.
Document-oriented data modeling — embed versus reference, key-based relationships and cardinality, the normalization trade-off, collections and schema versioning as modeling tools, and the anti-patterns that push a workload off Couchbase.

Querying — SQL++

Querying with SQL++ (SELECT & joins) — the Query service and how to run a statement, the SELECT clause set, RAW / VALUE projections, nested-path and array expressions, UNNEST and NEST, lookup / ANSI / index joins, WITH and recursive CTEs, subqueries, collection operators, and avoiding large `OFFSET`s with a keyset seek query.
SQL++ data modification, functions & transactions — INSERT / UPSERT / UPDATE / DELETE / MERGE with KEY, VALUE, USE KEYS and RETURNING; scalar, aggregate, window, array, object and metadata functions plus user-defined functions; and distributed ACID transactions through the SDK lambda API and the BEGIN / COMMIT / ROLLBACK statements.

Indexing & search

Indexing with the Index service (and legacy Views) — how the Index service builds Global Secondary Indexes (primary, secondary, composite, partial, array, adaptive, covering, partitioned and deferred), how EXPLAIN, ADVISE and the cost-based optimizer choose a plan, and why current GSI + SQL++ supersedes the legacy MapReduce Views mechanism.
Full-Text & Vector Search, Analytics & Eventing — the Search service for full-text, geo and vector / hybrid search from SQL++, the Enterprise Analytics service for columnar MPP queries over shadow datasets, and the Eventing service for JavaScript functions that run on the change feed.

Distributed architecture & operations

Clusters, replication, failover & XDCR — how a cluster spreads 1024 vBuckets across nodes with Multi-Dimensional Scaling, how DCP replicates active vBuckets to replicas, how automatic, graceful and hard failover and Server Group awareness work, and how XDCR mirrors buckets between data centers.
Storage internals, security & administration — how the managed cache, disk write queue, Couchstore and Magma engines, compaction, DCP and warm-up move data to disk; the RBAC, authentication, TLS and auditing model; and the console, CLI, backup, import/export and monitoring tooling.

SDKs & Mobile

SDKs, connectors & Couchbase Mobile — the SDK family and its shared API surface, the singleton Cluster and its connection string, timeouts and the retry / error model, the Kafka / Spark / Elasticsearch connectors, and Couchbase Mobile (Couchbase Lite, Sync Gateway, App Services, Edge Server and peer-to-peer sync).

Cheat sheet

Cheat Sheet (PDF) — a single-page, printable summary of everything in this section, with a downloadable PDF.

Bibliography

Couchbase Server documentation — the source every page in this section is written and verified against; see in particular Architecture Overview, Data and Scopes and Collections, Services and Global Secondary Indexes, the SQL++ language reference, Full-Text Search and Vector Search, Analytics, Eventing, Clusters and Availability and XDCR, Storage Engines, Distributed ACID Transactions, and Security.
docs.couchbase.com more broadly — the SDKs, cbq, Couchbase Shell, couchbase-cli, the Backup service, Couchbase Lite, Sync Gateway, Capella, and the release notes.
Couchbase Developer Academy and the Couchbase developer portal — free courses, tutorials and learning paths on the topics above.
Zablocki, John. Couchbase Essentials. Packt Publishing, 2015. ISBN 978-1-78439-449-3. Consulted as part of the bibliography for this section (targets roughly Couchbase Server 3.x) — see the publisher’s book page and packtpub.com.
Vohra, Deepak. Pro Couchbase Development — A NoSQL Platform for the Enterprise. Apress, 2015. ISBN 978-1-4842-1435-0. Consulted as part of the bibliography for this section (targets roughly Couchbase Server 3.x / 4.0) — see the publisher’s book page and apress.com.
Ostrovsky, David; Haji, Mohammed; Rodenski, Yaniv. Pro Couchbase Server, 2nd ed. Apress, 2015. ISBN 978-1-4842-1186-1. Consulted as part of the bibliography for this section (targets roughly Couchbase Server 3.x / 4.0) — see the publisher’s book page and apress.com.
The three books above are consulted bibliographic references only. They predate the current server line, so where they and the official documentation disagree, the official documentation is authoritative and the difference is noted; none of the books is the primary or main reference for this section.