Install and Start Using the Scala SDK with Couchbase Server

    +
    The Couchbase Scala SDK enables you to interact with a Couchbase Server cluster from the Scala language.

    Installing the SDK

    The Couchbase Scala SDK is available on the Maven repository. The latest version, as of June 2020, is 1.0.5.

    It can be included in your build.gradle like this:

    dependencies {
        compile group: 'com.couchbase.client', name: 'scala-client_2.12', version: '1.0.5'
    }

    Or into your Maven pom.xml:

    <dependencies>
        <dependency>
            <groupId>com.couchbase.client</groupId>
            <artifactId>scala-client_2.12</artifactId>
            <version>1.0.5</version>
        </dependency>
    </dependencies>

    Or for SBT:

    libraryDependencies += "com.couchbase.client" %% "scala-client" % "1.0.5"

    Connecting to a Cluster

    Now you have the Scala client installed, try out the following to connect to a Couchbase cluster.

    First pull in all the imports we’ll be using:

    import java.util.UUID
    
    import com.couchbase.client.scala.Cluster
    import com.couchbase.client.scala.durability.Durability
    import com.couchbase.client.scala.json.{JsonObject, JsonObjectSafe}
    import com.couchbase.client.scala.kv.ReplaceOptions
    
    import scala.util.{Failure, Success, Try}
    import concurrent.duration._

    Now we can connect to the cluster:

    val cluster = Cluster.connect("10.112.180.101", "username", "password").get

    Of course, you’ll need to change the IP address to match your own cluster’s.

    Cluster.connect actually returns a Try[Cluster], as the Scala client uses functional error handling and does not throw exceptions. You’ll see examples later of how to better handle a Try, but for simplicity here we’ll assume the operation succeeded and get the result as a Cluster using .get.

    Couchbase uses Role Based Access Control (RBAC) to control access to resources, so specify the username and password of a user you’ve setup during installation of the Couchbase Data Platform.

    Now we can open a Couchbase bucket, and its default collection:

    val bucket = cluster.bucket("bucket-name")
    val collection = bucket.defaultCollection

    The Scala SDK is forwards-looking to future releases of Couchbase Server which will support the new features of scopes and collections. These will allow documents to be grouped in a more granular way than buckets allow. For now, we will just open the 'default collection', which includes all documents in a bucket, and is forwards and backwards compatible with all supported versions of Couchbase Server.

    JSON

    Now we can do some simple Key Value (KV) operations. First, let’s create some JSON.

    The Scala SDK directly supports several popular JSON libraries, including uPickle/uJson, Circe, Play Json, Jawn, and Json4s (if you’d like to see your favourite supported, please let us know). In addition you can supply JSON encoded into a String or Array[Byte], opening the door to any JSON library; Jsoniter and Jackson have been tested this way, but any should work.

    You can also directly encode and decode Scala case classes to and from the SDK.

    To make things easy and to help get you started, the Scala SDK also bundles a home-grown small JSON library, which you are free to use instead of or alongside any of the other supported JSON libraries. The philosophy behind this library is to provide a very easy-to-use API and the fastest JSON implementation possible.

    These options are described in detail here, but to get us started let’s created some simple JSON using the built-in JsonObject library:

    val json = JsonObject("status" -> "awesome")

    Key-Value Operations

    And now let’s upsert it into Couchbase (upsert is an operation that will insert the document if it does not exist, or replace it if it does). We need to provide a unique ID for the JSON, and we’ll use a UUID here:

    val docId = UUID.randomUUID().toString
    collection.upsert(docId, json) match {
      case Success(result)    =>
      case Failure(exception) => println("Error: " + exception)
    }

    As mentioned above, the Scala SDK will not throw exceptions. Instead, methods that can error - such as the upsert above - will return a Scala Try result, which can either be a Success containing the result, or a Failure containing a Throwable exception. The easiest way to handle a single operation is with pattern matching, as shown above.

    Now let’s get the data back (this example will look a little messy due the the nested handling of multiple Try results, but we’ll see how to clean it up shortly):

    // Get a document
    collection.get(docId) match {
      case Success(result) =>
        // Convert the content to a JsonObjectSafe
        result.contentAs[JsonObjectSafe] match {
          case Success(json) =>
            // Pull out the JSON's status field, if it exists
            json.str("status") match {
              case Success(hello) => println(s"Couchbase is $hello")
              case _              => println("Field 'status' did not exist")
            }
          case Failure(err) => println("Error decoding result: " + err)
        }
      case Failure(err) => println("Error getting document: " + err)
    }

    Here we’re fetching the value for the key docId, converting that value to a JsonObjectSafe (a simple wrapper around JsonObject that returns Try results - see here for details), and then accessing the value of the status key as a String.

    Better Error Handling

    All three of these operations could fail, so there’s quite a lot of error handling code here to do something quite simple. One way to improve on this is by using flatMap, like this:

    val result: Try[String] = collection
      .get(docId)
      .flatMap(_.contentAs[JsonObjectSafe])
      .flatMap(_.str("status"))
    
    result match {
      case Success(status) => println(s"Couchbase is $status")
      case Failure(err)    => println("Error: " + err)
    }

    Alternatively, you can use a for-comprehension, like so:

    val result: Try[String] = for {
      result <- collection.get(docId)
      json <- result.contentAs[JsonObjectSafe]
      status <- json.str("status")
    } yield status
    
    result match {
      case Success(status) => println(s"Couchbase is $status")
      case Failure(err)    => println("Error: " + err)
    }

    Either of these methods will stop on the first failed operation. So the final returned Try contains either a) Success and the result of the final operation, indicating that everything was successful, or b) Failure with the error returned by the first failing operation.

    Overloads

    You’ll notice that most operations in the Scala SDK have two overloads. One will take an Options class, which provides all possible options that operation takes. For instance:

    collection
      .replace(docId, json, ReplaceOptions()
        .expiry(10.seconds)
        .durability(Durability.Majority)) match {
      case Success(status) =>
      case Failure(err)    => println("Error: " + err)
    }

    These options blocks are implemented as Scala case classes, e.g. they are immutable data objects that return a copy of themselves on each change.

    The other overload is provided purely for convenience. It takes named arguments instead of an Options object, but provides only the most commonly used options:

    collection.replace(docId, json, durability = Durability.Majority) match {
      case Success(status) =>
      case Failure(err)    => println("Error: " + err)
    }

    Next Steps

    You now know the basics of connecting to a Couchbase cluster, creating some JSON, and performing Key-Value operations.

    Key-Value operations are described in detail here.

    For performing operations against multiple documents, check out how to use N1QL in Scala here.

    The Scala SDK includes three APIs. The examples above show the simple blocking API, for simplicity, but you can also perform all operations in an async style using Scala Future, and a reactive style using Project Reactor SMono and SFlux. Please see Choosing an API for more details.

    API reference are available in a javadocs jar alongside the release.