Java SDK 2.0

Important: A newer version of this software with updated documentation is available. Visit the Couchbase Developer Portal for more information.

Fork me on GitHub Welcome to the Java SDK, the next generation of database access. It provides functionality to store and retrieve your documents to and from a Couchbase Server cluster through synchronous and asynchronous (reactive) interfaces. The SDK even has support for Java 8.

Here's a sampling of what you can do with the Couchbase Java SDK:

Storing Documents

JSON is a first-class citizen, but the SDK also provides support for any other type of object (such as serialized Java objects). This example shows how you can create a JSON document and insert it synchronously:

JsonObject user = JsonObject.empty()
  .put("firstname", "Walter")
  .put("lastname", "White")
  .put("job", "chemistry teacher")
  .put("age", 50);
JsonDocument stored = bucket.upsert(JsonDocument.create("walter", user));

Retrieving Documents

You can also retrieve your stored documents in a variety of ways. This first example synchronously loads a document identified by its ID and prints out a field of the JSON. Notice how the JSON handling is done for you:

JsonDocument walter = bucket.get("walter");
System.out.println("Found: " + walter.getString("firstname"));

That doesn't impress you? Asynchronous, reactive APIs are also exposed. The following example uses Java 8 to showcase a more advanced query:

  .onErrorResumeNext(bucket.async().getFromReplica("beer", ReplicaMode.ALL))
  .map(doc -> doc.content().getString("name"))
  .timeout(2, TimeUnit.SECONDS)
  .onErrorReturn(error -> "Not Found!");

This code snippet loads a document, falls back to a replica read if an error happens, grabs the first of potentially many replica responses, and then extracts the beer name. Finally, a timeout is applied and more error handling (printing out the errors) is added as well. This gives you a glimpse of what's possible with our asynchronous, reactive methods that are always available. In fact, the synchronous calls are just convenience wrappers.


Couchbase Server has extensive support for querying (be it through views or the experimental N1QL query language). The SDK provides various ways to query them. Here is how to query a view that gives us beers and breweries, filters out the beers, and prints their name:

ViewResult result = bucket.query(ViewQuery.from("beers_and_breweries", "by_name"));

Iterator<ViewRow> rowIterator = result.rows();
while (rowIterator.hasNext()) {
    ViewRow row =;
    JsonDocument doc = row.document();

    if (doc.content().getString("type").equals("beer")) {

This can also be done asynchronously:

    .query(ViewQuery.from("beers_and_breweries", "by_name"))
    .filter(doc -> doc.content().getString("type").equals("beer"))
    .subscribe(doc -> System.out.println(doc.content().getString("name")));

Here is how to run a N1QL query—notice how nicely the domain-specific language (DSL) leads you to your final query:

  .doOnNext(result -> {
      if (!result.success()) {
  .forEach(row -> System.out.println(row.value()));

The query selects all documents from the beer-sample bucket and prints the content of each row. Of course, synchronous execution is also available.