Introduction to CouchDB with .NET part 16: update functions in design documents

Introduction

In the previous post we saw how show functions work in design documents. Show functions are applied on a single document and are able to transform that document into a different format. The formats can range from simple string manipulations to HTML reports. The show function has access to the HTTP request as well with its rich object which contains the request headers, the cookies, the query parameters and much more. Therefore the HTTP request can also be used to refine the logic within a show function.

In this post we’ll look at the last remaining design document function type called update functions.

Update functions

Update functions are functions that can be called to update a document without bothering about the revision ID. The function must be called with a PUT request, i.e. it is not executed automatically upon a document update. An update function has access to the following parameters:

• The document being updated which was retrieved using the ID in the PUT request
• The HTTP request which is the same object we saw in list and show functions

The update function can be as simple as adding an extra row to a document. It can also be more complex that depends on the HTTP request parameter and modifies the document properties based on some logic. The one key takeaway here is that an update function is not applied automatically, the client must call upon it actively through a HTTP request. Update functions also return a HTTP response.

We’ll use the same “players” database for the demo as for the list and show functions. Here’s a reminder of its content:

{
  "name": "John",
  "yearOfBirth": 1980,
  "scoreBase": 100
}

{  
  "name": "Jane",
  "yearOfBirth": 1987,
  "scoreBase": 110
}

{  
  "name": "Mary",
  "yearOfBirth": 1989,
  "scoreBase": 95
}

{
  "name": "Peter",
  "yearOfBirth": 1988,
  "scoreBase": 105
}

Demo

We’ll add a date to the document called last_updated. We’ll also add the requested URL path to see how we can invoke the HTTP request object Add the following design document to the players database:

{
  "_id": "_design/updates",
  "updates": {
    "last-updated": "function(document, request) {if (document != null) {var date = new Date(); document['last_updated']=date; document['path'] = request.raw_path; return [document, 'Added the requested fields'];} return [null, 'No such document'];}"
  }
}

Here’s the JS function:

function(document, request) {
    if (document != null) {
        var date = new Date();
        document['last_updated'] = date;
        document['path'] = request.raw_path;
        return [document, 'Added the requested fields'];
    }
    return [null, 'No such document'];
}

If the document is found, i.e. is not null, then we add the two new fields to it. If the fields exist then they are updated. We finally return a message to the client. If the document doesn’t exist then we return a null object and a different message.

Here’s the URL template to call an update function:

PUT /_design/{design-doc-id}/_update/{update-function-name}/{doc-id-to-be-updated}

The player Mary has ID 3031afee194a8e4295c021221a013327 in my case so the full URL will be the following:

PUT http://localhost:5984/players/_design/updates/_update/last-updated/3031afee194a8e4295c021221a013327

It responds with “Added the requested fields” in the body. It looks like Mary was in fact successfully updated:

{
  "_id": "3031afee194a8e4295c021221a013327",
  "_rev": "5-f470b03d590df83ab0fc55377dfd35d2",
  "name": "Mary",
  "yearOfBirth": 1989,
  "scoreBase": 95,
  "last_updated": "2017-06-11T07:55:56.524Z",
  "path": "/players/_design/updates/_update/last-updated/3031afee194a8e4295c021221a013327"
}

The revision ID is automatically updated.

Update functions can potentially replace the way we updated documents before through the HTTP API. We can send any JSON payload in the request which in turn can be extracted through the request.body property. We then read those values from the JSON and change the properties of the retrieved documents. There’s no need to send the properties that don’t want to modify. We can also apply any extra logic like “updated-by” and read the principal from the HTTP request. That way we know who has updated the document.

The major benefit of an update function is that we don’t need to bother with the latest revision ID, the function will get it for us. Also, we don’t need to send in all properties of the document in the JSON body, only the ones that should be updated.

Read the next part here where we start discussing Mango queries.

You can view all posts related to data storage on this blog here.