Using the N1QL RETURNING Keyword

DZone 's Guide to

Using the N1QL RETURNING Keyword

When updating or inserting documents, save a step by using N1QL's RETURNING keyword from your .NET and .NET Core applications that use Couchbase.

· Database Zone ·
Free Resource

I’ve recently learned about the RETURNING keyword in N1QL. When you add it to the end of a N1QL query, that query will return the result set that was operated on. For instance, if you use an UPDATE, and that query updates 10 documents, the RETURNING will then return those 10 documents.

You can use this within your .NET and .NET Core Couchbase applications.

Basic Setup

This blog post assumes that you have Couchbase Server setup locally, a bucket created called "default", and at least a primary index created on that bucket.

Note: if you are having trouble getting started with Couchbase Server, or you are getting errors, especially in regards to N1QL indexing, you may want to revisit some of my "Getting Started" blog posts: Couchbase with Windows Part 1 and Couchbase with Windows Part 2 in particular.

I’m using a simple .NET Core console project, with the same tooling and setup that I used in my .NET Core with Visual Studio Code blog post.

Coding With .NET and N1QL

Most of this code should be pretty familiar if you’ve used .NET and Couchbase before. I’m creating five documents that have (initially) a processed field set to false. The code below inserts them. It also writes them out to the console for illustration purposes.

for(var i = 0;i < 5; i++) {
    var docKey = Guid.NewGuid().ToString();
    var docContent = new {
            foo = "bar",
            type = "example",
            processed = false,
            dt = DateTime.Now
    var docContentJson = JsonConvert.SerializeObject(docContent);
    bucket.Insert(new Document<dynamic> {
        Id = docKey,
        Content = docContent

    Console.WriteLine($"Inserted: {docKey} - {docContentJson}");

Next, this code immediately runs a N1QL UPDATE to set all the processed fields to true. It also has a RETURNING statement at the end to return the documents as well as the keys.

var n1ql = @"UPDATE `default` d
                SET processed = true
                WHERE d.type = 'example'
                AND d.processed = false
                RETURNING d.*, META().id AS docKey";
var query = QueryRequest.Create(n1ql);
var results = bucket.Query<dynamic>(query);

Finally, the following code prints out the returned JSON to console for illustration purposes.

foreach(var result in results.Rows) {
    var resultJson = JsonConvert.SerializeObject(result);
    Console.WriteLine($"Returned: {resultJson}");

Running the Program

To execute this program, simply enter dotnet run at the console window. You should see an output like this:

Console output demonstrating the N1QL RETURNING keyword


The RETURNING keyword can save you a step when updating/inserting a group of documents. Try experimenting with a more complex UPDATE to see what happens. For example, try using IS MISSING instead of relying on a boolean flag like 'processed'.

The full source code for this blog post is available on GitHub.

If you have any questions, please leave a comment or contact me on Twitter.

couchbase ,n1ql ,.net core ,database

Published at DZone with permission of Matthew Groves , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}