The official Java client for Couchbase Server
Latest commit 5ce047c Aug 18, 2016 @simonbasle simonbasle committed with simonbasle JCBC-995: Improve customization of subdoc serialization
Subdocument uses the shaded Jackson MAPPER as its default implementation
for serialization and deserialization.

The FragmentTranscoder can be customized, and this is especially useful
on the write path, but the implementation can be a bit tricky.
In order to support custom serialization, a better abstract class would
be useful.

Additionally, the read path is more complex especially when multiple
operations are performed, as the LookupSpec is lost and as such there
is no way for the client to provide a target Class that can be natively
used for the deserialization.

In order to support custom deserialization, the raw bytes should be
exposed so the user can work with its own deserialization mechanism.

Added an optional rawContent getter on SubdocOperationResult.

Added an includeRaw option to the LookupInBuilders that will opt-in into
putting a copy of the raw JSON bytes into the result for GETs. This is
opt-in due to the sometimes undesirable memory overhead this implies.

Added a new abstract FragmentTranscoder that deals with byte arrays
instead of ByteBuf, making it easier to implement a concrete transcoder.

Custom transcoders for subdoc can be written more easily and custom
deserialization can also be applied using the rawContent value.

Change-Id: I6131fb0bee7230c60e92892b818876115406488e
Tested-by: Simon Baslé <>
Reviewed-by: Michael Nitschinger <>

Official Couchbase Java SDK

This project is the official driver for Couchbase when working with Java (or on the JVM). It provides management, CRUD and query facilities through both asynchronous and synchronous APIs.


  • High-Performance Key/Value and Query (N1QL, Views) operations
  • Cluster-Awareness and automatic rebalance and failover handling
  • Asynchronous (through RxJava) and Synchronous APIs
  • Transparent Encryption Support
  • Cluster and Bucket level management facilities
  • Complete non-blocking stack through RxJava and Netty

Getting Help

This README, as well as the reference documentation are the best places to get started and dig deeper into the Couchbase SDK. In addition, you might want to look at our travel-sample application.

The primary way to ask questions is through our official Forums, although there is also a stackoverflow tag. You can also ask questions on #couchbase or #libcouchbase on IRC (freenode). Please file any issues you find or enhancements you want to request against our JIRA which we use for universal issue tracking.

Quick Start

The easiest way is to download the jar as well as its transitive dependencies (only 2) through maven:


You can find information to older versions as well as alternative downloads here.

The following code connects to the Cluster, opens a Bucket, stores a Document, retrieves it and prints out parts of the content.

// Create a cluster reference
CouchbaseCluster cluster = CouchbaseCluster.create("");

// Connect to the bucket and open it
Bucket bucket = cluster.openBucket("default");

// Create a JSON document and store it with the ID "helloworld"
JsonObject content = JsonObject.create().put("hello", "world");
JsonDocument inserted = bucket.upsert(JsonDocument.create("helloworld", content));

// Read the document and print the "hello" field
JsonDocument found = bucket.get("helloworld");
System.out.println("Couchbase is the best database in the " + found.content().getString("hello"));

// Close all buckets and disconnect

If you want to perform a N1QL query against Couchbase Server 4.0 or later, you can do it like this:

N1qlQueryResult result = bucket.query(N1qlQuery.simple("SELECT DISTINCT(country) FROM `travel-sample` WHERE type = 'airline' LIMIT 10"));

for (N1qlQueryRow row : result) {

This prints out the distinct countries for all airlines stored in the travel-sample bucket that comes with the server.

If you want to learn more, check out the Start Using the SDK section in the official documentation.


We use Gerrit for our code review system. Please have a look at the extensive for more details.

Feel free to reach out to the maintainers over the forums, IRC or email if you have further questions on contributing or get stuck along the way. We love contributions and want to help you get your change over the finish line - and you mentioned in the release notes!