I\u2019m very happy to report that Couchbase now has a supported Scala SDK, allowing you to get and fetch documents, run N1QL queries, perform analytics and full text search lookups – all with native Scala.<\/p>\n
In this blog I\u2019m going to touch on the key features and design principles of the Scala SDK. \u00a0Or if you want to get going right away, then check out the getting started guide here<\/a>. \u00a0The Scala SDK is available to download right now, in a pre-release alpha form.<\/p>\n The Scala SDK uses the same high-performance and stable internal core as the new Java SDK 3.x, so although it\u2019s brand new, you can rest assured that it will be production-ready come GA.<\/p>\n The Scala SDK presents a functional interface, with the majority of operations returning a Scala Try. \u00a0This can either be a Success and contain the expected value, or a Failure containing a Throwable. Though at first this seems a little verbose, and requires some programming discipline to always handle errors, this form of error handling quickly becomes second nature and lets you develop safe in the knowledge that a random exception isn\u2019t going to be thrown from the SDK.<\/p>\n Here\u2019s a simple demo of inserting a document:<\/p>\n And then pattern matching on the Try result:<\/p>\n (Of course, a production app would handle errors properly, rather than just using println!)<\/p>\n If you\u2019d rather have something similar to the Java SDK, which throws exceptions, this is easy to simulate by simply calling .get() on any Try, which will throw if it\u2019s a Failure:<\/p>\n It\u2019s easy to combine multiple Try\u2019s through flatMap. \u00a0Here we upsert a document, then get it, retrieve its content converted into the built-in JSON library JsonObjectSafe (more on that later), and finally getting a field named \u201cstatus\u201d from that. \u00a0All in a completely functional style, so for instance the get operation will only be tried if the upsert is successful.<\/p>\n (For conciseness, most of the examples below will leave out checking the result. \u00a0But production apps should of course ABC – always be checking.)<\/p>\n Out of the box, the SDK supports the new stronger durability that will be available in Couchbase Server 6.5:<\/p>\n And bakes in support for collections, a new method of organizing documents inside buckets which will be a cornerstone feature of a future release of Couchbase Server (with a preview coming soon). \u00a0The keen will soon be able to create some toy collections to play with, but for now it will suffice to open the default collection:<\/p>\n This logic will work on all supported Couchbase Server versions (5.x and above).<\/p>\n In addition, support is included for OpenTracing (now OpenTelemetry), the platform that\u2019s becoming the defacto standard for tracing complex distributed systems:<\/p>\n The SDK leverages named and default parameters in place of overloads, so your code can be as simple:<\/p>\n or as customized:<\/p>\n as you need it to be.<\/p>\n Like the Java SDK, three APIs are presented, giving you the flexibility to structure your application the way you need to.<\/p>\n First is the simple blocking synchronous API you\u2019ve seen in the examples above. \u00a0This can be a good default choice, but of course requires you to explicitly manage your own threading if needed.<\/p>\n Second is one built around reactive programming, using standard reactive types (Mono and Flux) from Project Reactor.<\/p>\n An example of upserting in a reactive way:<\/p>\n With reactive programming, nothing will happen until we subscribe to the Mono. \u00a0The simplest way to do this for testing purposes is to use block(), though this is bad practice for a real app:<\/p>\n Reactive programming is a complex and deep subject that I can\u2019t go into too much here, but when mastered it provides a powerful tool, especially for handling the complexities of real-world distributed systems. \u00a0In particular, the reactive API provides backpressure on N1QL, FTS and analytics queries – so if the application is struggling to keep up with the data, it will automatically slow down consumption of rows and avoid out-of-memory errors. \u00a0I encourage the curious to check out the Project Reactor documentation<\/a> to learn more.<\/p>\n Finally, there is the asynchronous API built around Scala Futures, which provides a little of the thread management and composability of reactive programming, but in a form that\u2019s more familiar to many Scala developers. \u00a0A simple upsert example looks like this:<\/p>\n A key aim was to not fence you into any particular JSON implementation, and out-of-the-box the Scala SDK will play nice with several popular Scala JSON libraries, including Circe, \u00b5Pickle \/ \u00b5Json, Json4s and Jawn. \u00a0You can see snippets of how to use each of them in the JSON docs<\/a>, but to whet your appetite here\u2019s some Circe in action – note how Circe types are directly sent to, and returned from, the SDK:<\/p>\n Taking a \u2018batteries included\u2019 approach there\u2019s also a simple JSON library included with the SDK, JsonObject. \u00a0Its main goals are:<\/p>\n You can delve into the JsonObject docs here<\/a>. \u00a0Of course, if you\u2019d rather have a more \u2018typically Scala\u2019 JSON library with immutable data, algebraic data types, lenses, cursors and other functional goodies, then one of the other supported libraries may be a better choice – the choice is yours, and you can easily mix and match multiple JSON libraries in the same app.<\/p>\n Though the Scala SDK has great support for JSON, sometimes it\u2019s easier and preferable to work directly with Scala case classes.<\/p>\n By just adding this tiny bit of boilerplate for your case class, the SDK can automatically generate serialization logic:<\/p>\n And then you can easily send that case class directly to, and receive it back from, the SDK:<\/p>\n Under the hood this is converted and stored on Couchbase Server as the JSON you’d expect:<\/p>\n This is plain ordinary JSON with no extra serialization metadata or similar, so it can be freely written as a case class and read out into a JSON library or by another SDK – or vice versa.<\/p>\n Check out the documentation on using case classes<\/a> for more.<\/p>\n We\u2019ve made it as easy as possible to use Couchbase Analytics, N1QL and Full Text Search. \u00a0Here\u2019s an example of a N1QL query where rows are converted into JsonObject.<\/p>\n And of course it\u2019s possible to get those results as any of the supported JSON types above, or directly as Scala case classes.<\/p>\n And as mentioned above, using the reactive API means you get automatic backpressure for free, ensuring that your application consumes rows at a manageable rate and cannot hit out-of-memory issues on very large queries.<\/p>\n <\/p>\n If you\u2019re excited to get started with the Couchbase Scala SDK, then check out the quickstart guide<\/a>. \u00a0It\u2019s available right now, though in an early alpha form. \u00a0There may be a few breaking changes ahead before going to GA, but on the flip-side this is the perfect time to try it out and give us your feedback by dropping a comment below, or raising it on our forums<\/a>, Twitter<\/a> or gitter<\/a>.\u00a0 Nothing is set in stone and we welcome the chance to make some changes and make this the best SDK possible.<\/p>\n","protected":false},"excerpt":{"rendered":" I\u2019m very happy to report that Couchbase now has a supported Scala SDK, allowing you to get and fetch documents, run N1QL queries, perform analytics and full text search lookups – all with native Scala. In this blog I\u2019m going […]<\/p>\n","protected":false},"author":40102,"featured_media":7088,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":""},"categories":[2201],"tags":[],"ppma_author":[9084],"class_list":["post-7085","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tools-sdks"],"acf":[],"yoast_head":"\nFunctional Error Handling – No Exceptions!<\/b><\/h3>\n
val json = JsonObject(\"status\" -> \"awesome!\")\r\n\r\nval result: Try[MutationResult] = collection.insert(\"document-key\", json)<\/pre>\n
result match {\r\n \u00a0\u00a0\u00a0 case Success(mr) => println(\"Upsert was successful\")\r\n \u00a0\u00a0\u00a0 case Failure(err: KeyAlreadyExistsException) => println(\"document-key already exists\") \r\n \u00a0\u00a0\u00a0 case Failure(err) => println(\"Error: \" + err)\r\n}<\/pre>\nval result: MutationResult = collection.insert(\"document-key\", json).get()<\/pre>\n
val result: Try[String] = collection.upsert(\"document-key\", json)\r\n .flatMap(_ => collection.get(\"document-key\"))\r\n .flatMap(_.contentAs[JsonObjectSafe])\r\n .flatMap(_.str(\"status\"))\r\n\r\nresult match {\r\n case Success(status) => println(s\"Couchbase is $status\")\r\n case Failure(err) =>\u00a0\u00a0\u00a0 println(\"Error: \" + err)\r\n}<\/pre>\nForward Looking<\/b><\/h3>\n
val result = collection.upsert(\u201cdocId\u201d, json, durability = Durability.Majority)<\/pre>\n
val cluster = Cluster.connect(\"cluster-ip\", \"username\", \"password\")\r\nval collection = cluster.bucket(\"bucket-name\").defaultCollection<\/pre>\n
val result = collection.upsert(\u201cdocId\u201d, json, parentSpan = Some(mySpan))<\/pre>\n
Simple API<\/b><\/h3>\n
val result = collection.upsert(\u201cdocId\u201d, json)<\/pre>\n
val result = collection.upsert(\u201cdocId\u201d, json, durability = Durability.Majority, expiration = 60.minutes, parentSpan = Some(mySpan))<\/pre>\n
Asynchronous<\/b><\/h3>\n
val mono: Mono[MutationResult] = collection.reactive.upsert(\"document-key\", json)\r\n .doOnError(err => println(s\"Error during upsert: ${err}\"))\r\n .doOnNext(mutationResult => println(\"Success\"))<\/pre>\nval result: MutationResult = mono.block()<\/pre>\n
val result: Future[MutationResult] = collection.async.upsert(\"document-key\", json)\r\n\r\nresult onComplete {\r\n case Success(_) \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 => println(\"Successfully upserted\")\r\n case Failure(exception) => println(\"Error: \" + exception)\r\n}<\/pre>\nJSON Flexibility<\/b><\/h3>\n
import io.circe.generic.auto._\r\nimport io.circe.syntax._\r\n\r\nval user = User(\u201cJohn Smith\u201d, 29)\r\nval json: io.circe.Json = user.asJson\r\n\r\nval result: Try[io.circe.Json] = collection.insert(\"id\", json)\r\n .flatMap(_ => collection.get(\"id\"))\r\n .flatMap(doc => doc.contentAs[io.circe.Json])\r\n\r\nresult match {\r\n case Success(content: io.circe.Json) =>\r\n \/\/ Handle Circe Json here\r\n case Failure(err) =>\u00a0\u00a0\u00a0 println(\"Error: \" + err)\r\n}<\/pre>\nBuilt-in JSON<\/h4>\n
\n
Direct Case Class Support<\/b><\/h4>\n
case class User(name: String, age: Int)\r\n\r\nobject User {\r\n implicit val codec: Codec[User] = Codecs.codec[User]\r\n}<\/pre>\nval r: Try[User] = collection.insert(\u201cdocId\u201d, User(\u201cJohn Smith\u201d, 29))\r\n .flatMap(_ => collection.get(\u201cdocId\u201d)\r\n .flatMap(doc => doc.contentAs[User])<\/pre>\n
{\"name\":\"John Smith\",\"age\":29}<\/pre>\nEasy Queries<\/b><\/h3>\n
cluster.query(\"\"\"select * from `travel-sample` limit 10;\"\"\")\r\n .flatMap(_.allRowsAs[JsonObject]) match {\r\n\r\n case Success(rows: Seq[JsonObject]) =>\r\n rows.foreach(row => println(row))\r\n case Failure(err) =>\r\n println(s\"Error: $err\")\r\n}<\/pre>\n