Peter in the Azure sky

Got a message from one of my blog visitors that were related to two of my previous blog posts (DocumentDB revisited Part 3 – Concurrency in DocumentDB and  DocumentDB revisited Part 4 – Stored Procedures) that I wrote when I revisited DocumentDB some time ago. The problem was that he (hi Mark) had tried to get the optimistic concurrency to work from within a stored procedure (JavaScript) but had tried some trouble getting that to work the same way as in the c# example. As Mark noted I had not presented any solution if you wanted to update documents also from a stored procedure with concurrency checks. I believe this fell a bit between the two posts as I discussed concurrency in part 3 and stored procedures in part 4. So to bridge these I will present the solution for stores procedures and optimistic concurrency below.

Default behavior of DocumentDB SPs

By default you will not get any warnings when a DocumentDB stored procedure wants to update a document that someone else have updated between the load of the document to the time when it is saved. Meaning that effectively the last write wins (overwrites any intermediate saves). This behavior is discussed in detail in DocumentDB revisited Part 3 – Concurrency in DocumentDB and I showed some techniques how to avoid that from c# code.

You need to consider the consequences before you turn on the concurrency check in the Stored Procedure. The reason for this is that the Stored Procedures are atomic – meaning that it is transactional (implicitly). If the function throws an error then the transaction is rolled back, if not – it is committed. So if you get an exception about concurrency (i.e. “Precondition failed”) and throw an error – all other changes will effectively be rolled back**.

** I will show you ways of dealing with this for alternate solutions later where you want to keep as much of the changes as possible.

But you need to consider this before you implements your SPs as it may affect  the choice of whether to turn it on or not also.

Also consider the likelihood that someone/something else would be updating the same document during the timespan of a “quick read-update value-save” operation will be very slim (depending a bit on the application and its implementation) so this might also speak for not turning on optimistic concurrency on your SP.

You also need to consider that (if you use a partitioned DocumentDB instance) the transaction must occur within a single partition.

The above is an example of a SP not handling optimistic concurrency. It opens a document and changes the firstname of the customer (very simplified and hardcoded)

The solution – , { etag: doc._etag}

Turn on Optimistic Concurrency in your DocumentDB SP is very simple. The code change is equivalent of the AccessConditionType.IfMatch from the C# code described in the post regarding optimistic concurrency.

The example above just adds a {etag: doc1._etag} option in the replaceDocument JavaScript which really is the one change that you need to do. Just remember that the second part must be from the document that you are actually updating, in this case doc1.

So prove that it works…

The above SP will work, but as did the first one without concurrency checks. The problem with optimistic concurrency is of course to make it occur which it will hardly do in a well designed system. I will therefor create a special SP that will open two copies of the same document and will try to update them one after the other. The second update should fail as the etag will change after the first save.

So what happens if I run this in the portal…

So we have proven in this sample that the etag is a precondition for the save to be successful save. The sample itself is not very useful as you would not have an SP designed this way. If you need to update the same record you would not load the second document until you have saved it the first time and would therefor use the new etag in the second save.

IMPORTANT: By throwing the error you will now roll back the first save also so no change will be saved.

What if you don’t want to rollback but just exit

For this scenario – lets imagine that the second save is a bonus. If it works then fine lets save it but we don’t want to loose the first update OR overwrite any other persons updates (strange scenario but still…). So basically if we get an optimistic concurrency error I want to just ignore it BUT if I get any other error I want to roll back everything.

To do this first we need to understand the err object (the below is taken from http://azure.github.io/azure-documentdb-js-server/Collection.html#.RequestCallback)

The key here is to understand the ErrorCodes. After all we don’t want to ignore all problems we just want to handle the situation where someone else have updated our record.

The possible ErrorCodes are:

And as you saw in the error earlier from the script explorer and in my other related post on optimistic concurrency – the ErrorCode we want to ignore is the PreConditionFailed error.

Knowing this and that If I raise the error everything is rolled back… I modified the function like below.

So what will happen in the above example.

1. We will change the name on the order to ‘First Committed’ and successfully update it
2. We will change the name in the second version of the document to ‘Second fails’. We then get an optimistic concurrency error BUT I will check the errorcode if (err.number != PreconditionFailed) and will only throw an error if it is NOT a Precondition Failed error.

Result: First save is persisted in the database.

Important: Though I may have solved the scenario described above…I have no clue that there was a concurrency issue. If I throw an error the first update is rolled back. So you’d better know what you are doing in this case.

Recover from Optimistic Concurrency

The next example is nicer. In this I want to update a customers first name. I will then force a concurreny error by harcoding a faulty etag. In your SP you will use the real etag. I will recover from etag error 412 PreconditionFailed error by reloading the document, setting the name on the updated document and then saving it – effectively allowing me not to overwrite any changed data (except for the name of course).  Below follows an example that handles this.

Not perfectly formatted and designed JavaScript perhaps and some inconsistent error handling but the point is more showing how you can recover from Optimistic Concurrency in your SP. I will end this post by discussing returning errors which will suggest ideas on how to handle errors in your code.

What about the error/return codes….

As Mark had noted was that he got different error codes from the C# example and the JavaScript SP raised errors.

Let’s first verify Marks claims…

If you recall the entry from the post DocumentDB revisited Part 3 – Concurrency in DocumentDB I had a method defined like this when updating with ordinary c# code.

and we caught the error like this

So now lets try again with a SP that generates a Optimistic Concurrency Error.

We can then see that the JavaScript generates a BadRequest(400) response instead of PreconditionFailed (412). So Mark was right. There was a discrepancy in the return codes. The reason is likely that the SP uses a JavaScript throw statement and we cannot specify to throw a specific status code like PreconditionFailed (a shortcoming of the untyped javaScript language). The native C# SDK however can and can return a more suitable error code. For the JavaScript errors we use the same throw statement for all errors.

However….all is not lost because we can still see the inner exception in the code

Had DocumentDB had been a bit nicer it could have converted the error in this example to 412 Preconition failed. But as it is right now we are stuck with this message and it would be simple to write some ugly code like below to handle all OptimisticConcurrency errors the same way ( for both C# AccessCondition errors  and SP etag error)

The worst part of this solution is of course that we are depeding on a string constant. What if the error text is replaced or spelled differently – then we will not classify it as a optimistic concurrency error anymore…..

Using Customized Errors to avoid hard coded string comparison

So I would like to do something nicer and more resilient perhaps and I intend to use the details from the errorobject described in section What if you don’t want to rollback but just exit earlier. I know in the SP JavaScript code when I have a PreconditionFailed so I will try to return a more custom error message and I will allow you to return additional  JSON depending on the error and still be able to parse it. Sounds good, right?

First a new SP

Notice that I don’t throw the Err object directly anymore. Instead I throw a valid JSON string throw  “{‘StatusCode’:” + err.number + “,’CustomMessage’:’Error opening order’}”;  which will resemble the following string {‘StatusCode’:412, ‘CustomMessage’:’Error opening order’} .  The method will fake a conscurrency error by setting a faulty etag.

So what will happen in our client?

Well you can see that my JSON is there. So now we will just have to extract it. The nice thing about the method I created is that you could return many more values for specific errors, such as etag, order number etc. You can just add it in the JSON on the server side and write logic to consume the additional columns if you want to.

So first I need to parse the JSON. I use a very simplified RegEx expression and try to extract the JSON part. I will then Deserialize the JSON as dynamic to be able to use it flexible with custom properties. If there is no match I will return a custom return object to not generate errors later.

Here is the function. Note that it does not support JSON hierarchies.

Now we can add the check for StatusCode 412 also for bad requests and treat them the same way as our other concurrency errors from the SDK.

So with this I check if it is either a StatusCode PreconcitidonFailed or if the StatusCode is Badrequest and the custom StatusCode is PreconditionFailed. Note also that the Debug write accesses the CustomMessage that I sent.

This is of course but one way to do it. Only imagination stops you from doing your own solution for this – but at least give me some credit and agree that this is nicer (propagates original error to check for precondition failed and allows for custom properties to be read as well as). The string comparison is likely somewhat faster but it is less flexible and a error string change would break the functionality.

Good luck with your own choice in concurrency selection. I hope that this have given you some thoughts that you can reuse in your solution,