Getting familiar with Couchbase for .NET SDK 3


Couchbase NuGet Client CouchbaseNetClient has some major changes in 3.x version compared to its predecessor 2.x version. The aim here is to understand those differences between the two versions and how it has affected creating a connection with the Couchbase cluster and communication with the server.


Couchbase client for .NET applications CouchbaseNetClient provides an API to connect and talk to Couchbase Server, a NoSQL document-oriented database.

CouchbaseNetClient 3.x Vs 2.x

The latest Couchbase .NET SDK 3 has a lot of upgrades over its predecessor.

Collections & Scopes are new concepts in the Couchbase server added for organizational purposes.

A Collection is a logical data container within a bucket. These collections contain several documents. Documents can be categorized based on, say content types, i.e documents of similar content-type together form a Collection.

For example, within a bucket that contains trip booking information, documents that relate specifically to Car might be assigned to a car collection, while documents that relate to Driver might be assigned to a driver collection, and so on.

Documents of similar types makes a collection, which in turn a part of a bucket.
Documents of similar types makes a collection, which in turn a part of a bucket.
Buckets consist of Collectins which contains documents.

A scope is a mechanism for the grouping of multiple collections. Up to 1000 scopes can be created per cluster. Collection names must be unique within their scope. Collections might be assigned to different scopes according to content-type, or to deployment-phase (i.e., dev vs. testing environments). Applications can be assigned per-scope access rights (RBAC: Role-Based Access Control), allowing each application to access only those collections it requires.

This makes the structure as Bucket -> Scopes -> Collections -> Documents

Every created bucket is automatically given a default scope, and within it, a default collection. Each is named _default. All documents created within the bucket without reference to specific scopes or collections are saved in the default collection, within the default scope.

Benefits to having Scopes and Collects

  • The logical grouping of similar documents, potentially simplifying operations such as query, XDCR (Cross Data Centralized Replication), and backup and restore.
  • The increased efficiency of indexing, due to the Data Service being able to provide documents from specific collections to the Index Service.
  • Simplified querying, since query statements are able more easily to specify particular subsets of documents from Scope-Collection combination.
  • Easier migration from relational databases to Couchbase Server, since collections, can be designed to correspond to pre-existing relational tables.
    Parallel to RDBMS,
    The bucket is adjacent to Database.
    The scope is adjacent to Schema.
    The collection is adjacent to Table.
    The document is adjacent to Row.
  • Secure isolation of different document-types, within a bucket, allowing applications to be specifically authorized to use only their appropriate subsets of data

With this change, the documents-related key-value operations are performed on the collection object unlike using the bucket object in the previous versions.

The C# code for accessing a bucket and collection in 2.x and 3.x respectively is shown below.

Couchbase SDK 2 client followed a pattern of having a Method() and a corresponding MethodAsync() . Following Microsoft guidelines, SDK 3 is moved fully to async. Also as it has become more common in contemporary C# code for all methods to return a Task.

Document expiration (Time to Live) is supported in Couchbase at both the bucket and the document level. The setting is intended for use on documents that can be automatically removed after a certain period of time. The expiration time is set during the document creation time using the Couchbase SDK.

With N1QL TTL, the expiration time can now be set and updated directly using the N1QL query syntax. This enhancement allows administrators to change the document expiration policy after the document was created, or selectively choose documents for deletion via the document expiration mechanism.

N1QL receives an impressive number of new capabilities including support for the abovementioned Scopes and Collections, a patent-submitted cost-based query optimizer for Couchbase, transaction support within N1QL.

The addition of scopes and collections has a very positive effect on Indexing making indexes smaller, more targeted, and faster. Full-Text Search also works within Scopes and Collections without improved functioning as the documents are more targeted.

In SDK, we used to get a C# object as a document from the Couchbase server by using Bucket.Get<T>() , wherein the latest version 3 we use the collection to get a JSON and use then typecast it to required c# class using ContentAS<T>(data). This is in line with the Single Responsibility principle of design patterns.

One of the notable differences is in the way of Exception handling. In SDK 2 the openBucket() would not in fact work if it could not open the bucket, while DefacultCollectionAsync() would actually throw an exception if it could not open the collection.

These were some notable major differences when migrating to 3.x, there are few more minor differences.

Software Developer | Technology enthusiast.