{"id":2000,"date":"2015-10-27T20:51:14","date_gmt":"2015-10-27T20:51:14","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2000"},"modified":"2025-06-13T23:54:01","modified_gmt":"2025-06-14T06:54:01","slug":"linq-n1ql-and-couchbase-oh-mai-linq2couchbase-ga","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/linq-n1ql-and-couchbase-oh-mai-linq2couchbase-ga\/","title":{"rendered":"Couchbase LINQ Provider GA: LINQ, N1QL and Couchbase, oh mai!"},"content":{"rendered":"

Today Couchbase is happy to announce the GA release of the official LINQ provider for Couchbase Server and the hot query language for JSON documents, N1QL! The goal of the provider is to provide a simple, easy to use ORM\/ODM that is closer to Linq2SQL than EntityFramework or NHibernate, which are verbose and can be complex.<\/p>\n

While simplicity is the goal, don’t underestimate the power of Linq2Couchbase; it’s a fully functional Linq implementation with extended support for all of N1QL’s awesome features!<\/p>\n

In this post we will go over the basics of getting started with Linq2Couchbase, the major actors in the API, and integration with ASP.NET and Owin\/Katana. In later posts we will go into more detail about specifics and details of Linq2Couchbase!<\/p>\n

The Architecture<\/h2>\n

The provider is really just another layer over the SDK; the provider handles query parsing and query generation and the SDK handles the request and mapping of the results. The provider uses Re-linq<\/a> internally to create an abstract syntax tree (AST) from the Linq query, which is then used to emit the N1QL statement. Note that Re-linq is used by both NHibernate and the EntityFramework, so your in good hands!<\/p>\n

Getting Started<\/h2>\n

The source is available on Github<\/a> and the package is available on NuGet<\/a>; if you use NuGet package manager to install Linq2Couchbase all dependencies, including the Couchbase.NET SDK will be handled for you.<\/p>\n

To install Linq2Couchbase using the NuGet package manager (assuming you have already created a Visual Studio project) open the package manager by right clicking the “Manage Nuget Packages” and searching for Linq2Couchbase or using the package manager command line:<\/p>\n

PM> Install-Package Linq2Couchbase \r\n<\/code><\/pre>\n
Once you have done this the project will have all the necessary dependencies. Next you’ll need to install Couchbase Server either locally or via VM’s. The download link for Couchbase Server is here<\/a>. For the VM’s, use vagrants<\/a> which uses Puppet and Vagrant to install a cluster of Couchbase servers. Make sure you install Couchbase 4.0! If you are using Vagrants, then provision up the cluster:<\/p>\n
peep@ELJEFE-PC ~\/repos\/vagrants\/4.0.0\/debian7 (master)\r\n$ vagrant up\r\n<\/code><\/pre>\n
Once you have a Couchbase Server or cluster, setup up the Server or Cluster and make sure at least one node is an Index node and one node is a Query node<\/em><\/strong>. You will do this on the the first step of the “Server Setup” or when you add an additional server to your cluster. Also, add the “beer-sample” data set to the cluster during setup or from the Settings>Samples tab after you have setup up the cluster or instance.<\/p>\n
Now that your Couchbase instance or cluster is setup, you will need to create a primary index in the “beer-sample” bucket. To do this either navigate C:Program FilesCouchbaseServerbin or if using vagrants<\/code> (or linux) \/opts\/couchbase\/bin<\/code>using a command prompt. Then type either cbq or .\/cbq (on linux) to start the query CIL and then:<\/p>\n
CREATE PRIMARY INDEX ON `beer-sample` USING GSI;\r\n<\/code><\/pre>\n
This will create a primary index on the beer-sample bucket. Note the backticks “`”, these are required to escape the “-” in beer-sample. Now you are ready to write some code!<\/p>\n
Creating the BucketContext<\/h2>\n
The main object for working with the bucket is the BucketContext. The BucketContext is analogous to the DataContext in Linq2Sql and the DbContext in the EntityFramework. It’s primary purpose is to provide and interface for building queries and submitting them to the Couchbase server.<\/p>\n
You can use the BucketContext as a stand-alone object or you can derive from it and create a strongly typed object that maps properties to the types in your bucket and domain model. In this example I will do the latter:<\/p>\n
\/\/\/ \r\n\r\n\/\/\/ A concrete DbContext for the beer-sample example bucket.\r\n\/\/\/ <\/code><\/pre>\n
public class BeerSample : BucketContext { public BeerSample() : this(ClusterHelper.GetBucket(“beer-sample”)) { } public BeerSample(IBucket bucket) : base(bucket) { DocumentFilterManager.SetFilter(new BreweryFilter()); } public IQueryable Beers { get { return Query(); } } public IQueryable Breweries { get { return Query(); } } }<\/p>\n
The beer-sample bucket (a bucket is similar to a database in a RDBMS system) contains documents that are “typed” as a “brewery” and a “beer”, this informal type system will allow to query the bucket and return either brewery documents or beer documents via a predicate(WHERE type=”beer” for example). In the code above we have defined explicit properties which return IQueryable<\/p>\n
An Example Query<\/h2>\n
You will find that using Linq2Couchbase is pretty much identical to Linq2SQL or the EF:<\/p>\n
var db = new BeerSample();\r\n\r\nvar query = from beer in db.Beers\r\n            join brewery in db.Breweries\r\n            on beer.BreweryId equals N1QlFunctions.Key(brewery)\r\n            select new { beer.Name, beer.Abv, BreweryName = brewery.Name };\r\n\r\nforeach (var beer in query)\r\n{\r\n    Console.WriteLine(beer.Name);\r\n}    \r\n<\/code><\/pre>\n
Once you have a BucketContext reference all you do is query it like you would any other Linq provider. All Linq keywords are supported as well as N1QL constructs like ON KEYS, NEST and UNNEST! In a later post, we will go over all of this is much greater detail!<\/p>\n
The Document Model<\/h2>\n
In the BeerSample context above, the Beer and Brewery objects will be the targets for our Linq projections and they correspond or map to equivalent JSON documents in our bucket (beer-sample). Here is a listing for each (note that this is partial listing, the classes in their entirety can be found here<\/a>):<\/p>\n
[Filters.DocumentTypeFilter(\"beer\")]\r\npublic class BeerFiltered\r\n{\r\n    [JsonProperty(\"name\")]\r\n    public string Name { get; set; }\r\n\r\n    [JsonProperty(\"abv\")]\r\n    public decimal Abv { get; set; }\r\n\r\n    ...\r\n\r\n    [JsonProperty(\"category\")]\r\n    public string Category { get; set; }\r\n\r\n    [JsonProperty(\"updated\")]\r\n    public DateTime Updated { get; set; }\r\n}\r\n<\/code><\/pre>\n
This of course maps to “beer” documents; note that DocumentTypeFilter attribute. This will “auto-magically” add a predicate or WHERE clause that filters by the type “beer” to every query that targets that document. The DocumentTypeFilter attribute is one of two ways to apply a filter, unless you manually add the predicate to each query.<\/p>\n
public class Brewery\r\n{\r\n    [JsonProperty(\"name\")]\r\n    public string Name { get; set; }\r\n\r\n    [JsonProperty(\"city\")]\r\n    public string City { get; set; }\r\n\r\n    ...\r\n\r\n    [JsonProperty(\"geo\")]\r\n    public Geo Geo { get; set; }\r\n\r\n    [JsonProperty(\"beers\")]\r\n    public List Beers { get; set; }\r\n}\r\n<\/code><\/pre>\n
This is the object that “brewery” documents will be mapped to. Note that there is no DocumentTypeFilter attribute explicitly defined; that is because the constructor for the BeerSample context will add the filter to the DocumentFilterManager. This is purely a different approach to the same problem; adding a predicate to a query to filter by type.<\/p>\n
Integrating with ASP.NET or Owin\/Katana<\/h2>\n
Their is a very distinct pattern for using the Couchbase .NET SDK in ASP.NET or Katana\/OWin projects. Since the BucketContext uses the Couchbase .NET SDK, you will need to follow this pattern so that you have take advantage object caching within the SDK and shared TCP connections. Fortunately, its a very simple pattern:<\/p>\n
Using Global.asax in ASP.NET<\/h3>\n
In an ASP.NET application using Global.asax, you will take advantage of the Application_Start and Application_End event handlers to create and destroy the Cluster and Bucket objects that the BucketContext depends on.<\/p>\n
public class MvcApplication : System.Web.HttpApplication\r\n{\r\n    protected async void Application_Start()\r\n    {\r\n        AreaRegistration.RegisterAllAreas();\r\n        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);\r\n        RouteConfig.RegisterRoutes(RouteTable.Routes);\r\n        BundleConfig.RegisterBundles(BundleTable.Bundles);\r\n\r\n        var config = new ClientConfiguration\r\n        {\r\n            Servers = new List\r\n            {\r\n                new Uri(\"https:\/\/192.168.77.101:8091\/\")\r\n            }\r\n        };\r\n\r\n        ClusterHelper.Initialize(config);\r\n        var bucket = ClusterHelper.GetBucket(\"default\");\r\n    }\r\n\r\n    protected void Application_End()\r\n    {\r\n        ClusterHelper.Close();\r\n    }\r\n}\r\n<\/code><\/pre>\n
Here we are creating the configuration (btw this could come from the App.Config as well) and then initializing the ClusterHelper object. Finally when the application shuts down, we are destroying the long-lived Cluster and Bucket objects in the Application_End handler. This will be a graceful shutdown and OS level constructs will be returned back to the OS in a timely manner.<\/p>\n
Using Setup.cs in Owin\/Katana<\/h3>\n
In Owin\/Katana hosted applications, we follow a similar pattern, we just use a different method, the Setup.cs class.<\/p>\n
public partial class Startup\r\n{\r\n    public void Configuration(IAppBuilder app)\r\n    {\r\n        ConfigureAuth(app);\r\n\r\n        \/\/initialize the ClusterHelper\r\n        ClusterHelper.Initialize(new ClientConfiguration\r\n        {\r\n            Servers = new List\r\n            {\r\n                new Uri(\"https:\/\/localhost:8091\/\")\r\n            }\r\n        });\r\n\r\n        \/\/Register a callback that will dispose of the ClusterHelper on app shutdown\r\n        var properties = new AppProperties(app.Properties);\r\n        var token = properties.OnAppDisposing;\r\n        if (token != CancellationToken.None)\r\n        {\r\n            token.Register(() =>\r\n            {\r\n                ClusterHelper.Close();\r\n            });\r\n        }\r\n    }\r\n}\r\n<\/code><\/pre>\n
Here we create and initialize the ClusterHelper when the Configuration method runs at startup and then we register a delegate that will fire when the application shuts down, closing our ClusterHelper and freeing up resources.<\/p>\n
Injecting into your Controllers<\/h3>\n
The BucketContext itself takes on the characteristics of the Unit of Work pattern; you can create one for each request and since the ClusterHelper manages the references (assuming you are following the advice above) the instance will simply be GC’d at the end of the request.<\/p>\n
The simplest way to do this is by simply using Dependency Injection<\/a> (the pattern) within your Controllers to create the instance when the controller is created, for example:<\/p>\n
public class HomeController : Controller\r\n{\r\n    private BeerSample _context;\r\n\r\n    public HomeController()\r\n        : this(new BeerSample(ClusterHelper.GetBucket(\"beer-sample\")))\r\n    {\r\n    }\r\n\r\n    public HomeController(BeerSample context)\r\n    {\r\n        _context = context;\r\n    }\r\n\r\n    ...\r\n}\r\n<\/code><\/pre>\n
Now, you simply use the BucketContext within your Action methods:<\/p>\n
public ActionResult Index()\r\n{\r\n    var query = (from beer in db.Beers\r\n        join brewery in db.Breweries\r\n        on beer.BreweryId equals N1QlFunctions.Key(brewery)\r\n        select new { \r\n            beer.Name, \r\n            beer.Abv, \r\n            BreweryName = brewery.Name \r\n        }).Take(10);\r\n\r\n    return View(query.ToList());\r\n}\r\n<\/code><\/pre>\n
Once again, since the context a short-lived lightweight object, you could scope it to the request and inject it there reusing it for all controllers invoked within that request.<\/p>\n
What’s coming up?<\/h2>\n
Very quickly, the next major feature will be Change Tracking using proxies. Additionally, expect bug fixes, performance enhancements and other featured aimed at making Linq2Couchbase a fully featured, lightweight ODM\/ORM!<\/p>\n
If there is a feature you want, a bug fix or perhaps you want to contribute we welcome all kinds of feedback both good and bad.<\/p>\n