Benefits of Using a CouchDB Update Handler Vs Using Native CouchDB Update APIs

If you are still using the Native CouchDB Update APIs, the CouchDB Update Handler will impress you with its performance. Three times more efficient than some of the de facto approaches, it provides a highly performant mechanisms to bulk updates, especially when you don’t have the _rev id handy.

Before getting into the details of how it works and why you need it, let’s get comfortable with couch:

What is CouchDB?

CouchDB is one of the best document-oriented databases to replace the MySQL. It offers its users a variety of exotic features: Eliminating the application layer procedures, it allows users to handle the data directly.

Access Handling in CouchDB

CouchDB has a huge fan following because it has none of the ‘Read Locks’ that developers might have faced with MySQL. Therefore, if you have multiple users accessing the database simultaneously, CouchDB can offer them quick help.

Features of CouchDB

  • The database is easily replicable across multiple servers.
  • The document level indexing offers fast and error-free retrieval.
  • The new document creation, update, retrieval and deletion is done with REST calls, causing no Read locks.

Update Handling

  • Each document has a unique identifier to read, write, update and perform other operations.
  • Document IDs are case-sensitive strings – so make sure you enter them correctly.
  • If two documents have same Document ID, they will be considered to be the same.

So, looks like you’ve started liking the way CouchDB handles your data on a multi-node CouchDB Cluster due to the utmost safety it offers.

You should. Communicating with your data is very easy on CouchDB. Whether it is retrieval, storage or update, all operation data is returned in JavaScript Object Notation (json) format.

Using Native CouchDB Update APIs

An important question now:

Have you ever been in a situation where you need to put a change on all of the CouchDB documents?

If so, you surely know how time-consuming it is to perform the ‘insert’ operations. CouchDB native update APIs offer a foolproof method of updating a document, although you need to know the revision or document ID. In the event you don’t, it would be necessary to read every revision one by one and then update them.


Updating an existing document can be achieved with a PUT request. As each document in CouchDB is a JSON object, it is identified with the revision number stored as _rev. While you are trying to retrieve a particular revision, you must know the _rev otherwise your query will end up with 409 Error. If the revision number in the PUT command does not match what’s in the database, a new revision number is generated, which is then returned.

Well, with the CouchDB HTTP APIs you need to first:

  1. Fetch the latest document revision (by passing on the Document ID).
  2. If the process was successful, update the descriptions.
  3. Push the updated document back to the CouchDB database.

Doesn’t this sound like a performance challenge? Let’s check:

Performance of Native APIs

We are using 3 HTTP calls to the database here. Whether or not the document is present in the database, the computation resources being utilized remain the same. Fetching, updating and then saving the updated version is an old school way of performing an ‘insert’ – to say the least! Hence, we obviously need a more efficient method for it.

Using CouchDB Update Handler

Update handlers are appropriate for performing an update action on a document. They are the unconventional method of updating the document that speeds up the process and saves resources.

The update handlers can be explicitly called to update a document description. No longer do we need to first retrieve the design document with document ID, update the changes and save it back to the database, and keep on doing this until we update all the documents. Update handler can make the changes to document description within the server itself.

Performance of Update Handlers

With CouchDB update Handlers, the web can now update descriptions by sending a POST request to document. With the document ID and the details of whatever description field needs to update, it will result in single HTTP call for the updates required. Therefore, this method is 3 times faster and efficient than the former (native API) method.

How does the Update Handler work?

For the update request, the update handler will include the document ID in the URL. The syntax for the URL will be:


This will be a REST PUT call, which requires no searching operation to be performed. The server responds to this call with the most recent version of that document ID.

What if you do not know the document ID?

No problem: as described above, you will have to send two parameters in the URL. So are you stuck when the Document ID is not known to you?

Of course not!

As you used the PUT command to invoke the update handler by providing the document ID, you can use POST command to use it without the document ID. The syntax, in this case, will be:

PUT command - /<database>/_design/<design>/_update/<function>/<docid>
POST command- /<database>/_design/<design>/_update/<function>

Effectively, it will also execute the Update handler with 1 HTTP call, in order to complete the update. REST PUT call will be like:


For example:


Then, in the body of the post, you would post the contents of the json file, i.e.:

{"_id": "123456", "doc_type":"shopper_delight","shopper_delight": {"contact_id":234876,"phone_nbr":"7075551234","category":"consumer","department":"health","last_update_timestmp":"2018-08-24T04:59:52.00"}}

This content can be used in multiple ways as needed.

Feature Comparison – The Advantages of Using Update Handler over Native Update APIs

The benefits of Using CouchDB Update Handler Vs Using Native CouchDB Update APIs are numerous. They include:

Increased Operation Speed

In a database connected to the website(s) or application(s), the live updates take place very frequently. If you are using the normal native API to perform these operations, the query will take 300% of the time that it should take through Update Handler API. As operations are generally in hundreds or even thousands, it will cause a drastic decrease in update speed and thereby in performance. But if you are using Update Handler, your system will run very much faster, right?

Optimal use of resources

In the case of Update Handler, only 1 HTTP call happens. That means that far fewer resources are being occupied or consumed than in the case of native APIs.

Usability of fetched data

The returned data is in the .json format. JSON can be converted into array or string with ease. Hence, the automated operations or sending of this data to multiple other applications can be done without facing any major obstacle.

Easier Procedure

Instead of involving a Native API in the call, Update Handler makes use of the conventional POST method. That means you just need to send two parameters in the POST. How tough can it be?


Update Handler makes use of REST API while making the HTTP call. If you are using OAuth, hashing, HTTPS (Secure HTTP, which is already made ‘almost essential’ by search engines nowadays) and taking care of other basic aspects, you can rest assured of the highest level of security.

In Summary

The CouchDB Update Handler features greater efficiency and ease of use across the board – you can tell we’re excited about it, and it’s with good reason. If you make the switch, the new product may take a little getting used to, but we are here to help. Having trouble using the CouchDB Update Handler or still confused about whether to switch or not? Feel free to contact us and we’ll do our best to help you out.

Leave a Reply

Your email address will not be published. Required fields are marked *