Linq2Couchbase 2.0.1
dotnet add package Linq2Couchbase --version 2.0.1
NuGet\Install-Package Linq2Couchbase -Version 2.0.1
<PackageReference Include="Linq2Couchbase" Version="2.0.1" />
paket add Linq2Couchbase --version 2.0.1
#r "nuget: Linq2Couchbase, 2.0.1"
// Install Linq2Couchbase as a Cake Addin #addin nuget:?package=Linq2Couchbase&version=2.0.1 // Install Linq2Couchbase as a Cake Tool #tool nuget:?package=Linq2Couchbase&version=2.0.1
Linq2Couchbase
The official Language Integrated Query (LINQ) provider for querying Couchbase Server with N1QL using the Couchbase .NET SDK. The goal of Linq2Couchbase is to create a lightweight ORM/ODM for querying Couchbase Buckets using LINQ as the lingua-franca between your application and Couchbase Server using N1QL, a SQL-like query language for JSON documents. It also provides a write API for performing CRUD operations on JSON documents.
While not an officially supported Couchbase project, this repo is actively maintained and monitored. If you happen to find a bug or have any questions, please either create an issue or make a post on forums.couchbase.com. Additionally, we actively accept contributions!
:info: This documentation is for Linq2Couchbase 2.x, compatible with Couchbase SDK 3.x. For documentation on Linq2Couchbase 1.x compatible with Couchbase SDK 2.x, see the release14 branch.
Getting started
The Linq2Couchbase project has the following dependencies:
- Couchbase Server 5.5 or greater with the query service enabled on at least one node
- Couchbase .NET SDK 3.0.3 or greater
Installing Couchbase Server
For a single instance of Couchbase Server running on localhost, you can download Couchbase Server here (make sure it's 4.0 or later). If you would like to create a cluster, the easiest way is by using the Vagrant scripts for provisioning clusters. Additionally, you can use Docker scripts. Follow the directions on each respective link for installation information.
Installing the package using NuGet
Once you have a Couchbase Server instance or cluster setup, open Visual Studio 2019 or greater or MonoDevelop and create a .NET or .NET Core application. Open the NuGet Package Manager and search for "Couchbase Linq" or type the following into the Package Manager console:
Install-Package Linq2Couchbase
Quick Start
This Quick Start assumes that you have already installed the travel-sample bucket, which is available and built-in to Couchbase Server.
Query the 'travel-sample' bucket and return 10 airlines in any order:
static async void Main() {
var cluster = await Cluster.ConnectAsync("couchbase://localhost", options => {
options.UserName = "Administrator";
options.Password = "password";
options.AddLinq();
});
// Wait until the cluster is bootstrapped
await cluster.WaitUntilReadyAsync(TimeSpan.FromSeconds(10));
var context = new BucketContext(await cluster.BucketAsync("travel-sample"));
var query = (from a in context.Query<AirLine>()
where a.Country == "United Kingdom"
select a)
.Take(10);
await foreach (var airline in query.ToAsyncEnumerable())
{
Console.WriteLine(airline.Name);
}
}
Upon running this query, you should expect console output similar to:
{"Id":"10642","Type":"airline","Name":"Jc royal.britannica","Iata":null,"Icao":"JRB","Callsign":null,"Country":"United Kingdom"}
{"Id":"112","Type":"airline","Name":"Astraeus","Iata":"5W","Icao":"AEU","Callsign":"FLYSTAR","Country":"United Kingdom"}
...
{"Id":"16881","Type":"airline","Name":"Air Cudlua","Iata":null,"Icao":"CUD","Callsign":"Cudlua","Country":"United Kingdom"}
ASP.NET Core Quick Start
For use with ASP.NET Core, it is recommended to use the Couchbase.Extensions.DependencyInjection NuGet package to register Couchbase with DI. Documentation can be found here. In that case, the bootstrap code in Startup.cs
may look like this:
public void ConfigureServices(IServiceCollection services)
{
// Other configuration here
services
.AddCouchbase(options => {
Configuration.GetSection("Couchbase").Bind(options);
options.AddLinq();
})
.AddCouchbaseBucket<INamedBucketProvider>("bucket-name");
}
A BucketContext
may then be created in a controller:
public class MyController : ControllerBase
{
private readonly INamedBucketProvider _bucketProvider;
public MyController(INamedBucketProvider bucketProvider)
{
_bucketProvider = bucketProvider;
}
public async Task<IActionResult> Get()
{
var bucketContext = new BucketContext(await _bucketProvider.GetBucketAsync());
// Use bucket context here
}
}
Developer Guide
- The BucketContext: how to use with ASP.NET and Owin/Katana applications
- Scopes and Collections
- Mapping JSON fields to POCO properties
- Mapping JSON documents to POCOs with DocumentFilters
- Controlling output with Select
- Filtering with Where
- Sorting and Paging Results
- String Handling
- Math Functions
- Date Handling
- Array Filtering, Projections, and Sorting
- Grouping and Aggregation
- The UseKeys Method
- Query Hints
- Joining Documents
- Nesting Documents
- Unnesting Documents
- Any and All
- Testing For NULL And MISSING Attributes
- The META Keyword
- Working With Enumerations
- Asynchronous Queries
- Serialization Converters
- Custom JSON Serializers
- Using Read Your Own Write (RYOW) Consistency
Building From Source
Linq2Couchbase uses the NuGet package manager for handling dependencies. To build from the source, simply clone the GitHub repository and build in Visual Studio. The NuGet package manager should download all required dependencies.
Project management
In the Jira project for Linq2Couchbase, you can file bugs, propose features or get an idea for the roadmap there. There is also a list of supported and proposed N1QL features for Linq2Couchbase.
Contributors
Linq2Couchbase is an open source project and community contributions are welcome whether they be pull-requests, feedback or filing bug tickets or feature requests. We appreciate any contribution no matter how big or small! If you do decide to contribute, please browse the Jira project and ensure that that feature or issue hasn't already been documented. If you want to work on a feature, bug or whatever please create or select a ticket and set the status to "in-progress".
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- CouchbaseNetClient (>= 3.6.2)
- Newtonsoft.Json (>= 13.0.1)
- Remotion.Linq (>= 2.2.0)
- System.Reflection.Emit.Lightweight (>= 4.7.0)
-
.NETStandard 2.1
- CouchbaseNetClient (>= 3.6.2)
- Newtonsoft.Json (>= 13.0.1)
- Remotion.Linq (>= 2.2.0)
- System.Reflection.Emit.Lightweight (>= 4.7.0)
-
net6.0
- CouchbaseNetClient (>= 3.6.2)
- Newtonsoft.Json (>= 13.0.1)
- Remotion.Linq (>= 2.2.0)
NuGet packages (8)
Showing the top 5 NuGet packages that depend on Linq2Couchbase:
Package | Downloads |
---|---|
Neon.Couchbase
Couchbase client extensions |
|
Neon.Xunit.Couchbase
Xunit test fixture for Couchbase |
|
Hangfire.Couchbase
This package adds support to Couchbase for Hangfire |
|
UrumiTech.Core.Couchbase
Couchbase Integration |
|
Stove.Couchbase
Couchbase integration for Stove. |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Linq2Couchbase:
Repository | Stars |
---|---|
stoveproject/Stove
Domain Driven Design oriented application framework, meets CRUD needs
|
Version | Downloads | Last updated |
---|---|---|
2.0.1 | 3,705 | 9/11/2024 |
2.0.1-beta.2 | 1,161 | 6/22/2023 |
2.0.0 | 452,185 | 12/14/2021 |
2.0.0-beta.1 | 9,251 | 11/19/2020 |
1.4.2 | 948,556 | 12/17/2019 |
1.4.1 | 171,822 | 7/9/2019 |
1.4.0 | 217,346 | 8/28/2018 |
1.4.0-beta | 2,163 | 5/24/2018 |
1.3.4 | 478,888 | 2/28/2018 |
1.3.3 | 57,053 | 9/25/2017 |
1.3.2 | 11,894 | 6/2/2017 |
1.2.1 | 9,735 | 10/17/2016 |
1.2.0 | 18,548 | 7/8/2016 |
1.1.0.2 | 5,648 | 4/7/2016 |
1.0.2 | 5,940 | 10/27/2015 |