Sub-document API in Couchbase Server 4.5 with the .NET SDK (revisited)

The Sub-document API offers two new Types that utilize a builder pattern via a fluent-interface for chaining together multiple operations on a document. Both objects are created by calling MutateIn or LookupIn on a CouchbaseBucket object and passing in the key of the document you are working against:

Once you have the builder object, you can chain together a number of operations to execute against the document, for example:

Then you can send all of the operations to the server in a single batch:

You can check the result of one operation, by using OpStatus and a path. In this example, I’m using the path "type":

These are some of the methods and fields you’ll find on the IDocumentFragment interface.

Besides these properties or methods, there are all of the other properties inherited from OperationResult (which is the standard response from a key/value operation): Upsert, Remove, Replace, and so on.

When sending multiple mutations, if one of them fails, the entire multi-operation request fails. This allows transactional “all-or-nothing” semantics when performing mutations within a single document.

When sending multiple lookups, some operations may succeed and some may fail, with the server attempting to return as many items as requested.

If the operation(s) failed, then theStatus property will contain a top-level error response such as SubDocMultiPathFailure. This is an indication that you should dig deeper into the operation’s results to get the specific error. You can do this by iterating: calling the OpStatus method and passing either the index or the path:

In this case, since the path “somepaththatdoesntexist” didn’t exist within the document, the specific error returned was SubDocPathNotFound. There are many different combinations of errors depending upon the builder type and the condition for the error.

Let’s lookup the owner fragment. If I pass in “owner” as the path parameter to this method…​

…​the output to console would be:

We can also check to see if a path exists. If I pass in “owner” as the path to this method…​

…​the output is true, because the path owner does indeed exist within the document.

Insert adds a value to a dictionary, optionally allowing for the containing element (the dictionary itself) to be added.

If I called the above method like so:

Then the document’s attributes dictionary will now look like this:

Note that the Insert method has an optional boolean parameter called createParents. It is false by default. If it’s true, then the sub-document API will create the necessary path for the field to exist. If it’s false, the sub-document API will only create the field if the parents of the field already exist. In the above example, the attributes field already existed.

In this next example, I’ll use a path with a parent field (anewattribute) that doesn’t already exist.

This will create the new attribute called anewattribute in the document and add a single key called withakey with a value of somevalue.

Now, if we passed false for createParents and the parent attribute did not exist, then the multi-mutation would fail with a top-level response status of SubDocMultiPathFailure and the specific error would be SubDocPathNotFound.

Upsert will add or replace an existing dictionary entry. The usage is exactly the same as Insert with the exception of the method name being Upsert.

Remove will remove an element at a given path.

When I call this method:

Here’s how the document will look afterwards:

Replace will swap the value of element at a given path, failing if the path does not exist:

After I call this method:

The document will now have a different value for “owner”:

ArrayAppend adds a value to the end of an array, optionally adding the parent element (the array element itself) if it doesn’t exist.

After that method with the “toys” path…​

…​the toys array in the document will then have the value “slipper” in the last ordinal:

ArrayPrepend works the same way as ArrayAppend, except it adds a value to the front of an array.

Calling that method with the “toys” path…​

The toys array now has the value “slipper” in it’s first ordinal:

ArrayPrepend puts a value at the beginning, ArrayAppend puts it at the end. Just to round things out, you can use ArrayInsert to put a value somewhere in between (at a given index).

And then calling that method with “toys[2]”…​

The toys array now has the value “slipper” at it’s 3rd ordinal (index 2):

ArrayAddUnique will inserts a value into an array, but it will fail if that value already exists (i.e. the value must be unique within the array).

When I call that with “shoe”…​

…​since the value “shoe” already exists in the original document’s toys array, this will fail with the status SubDocPathExists.

Note that this method only allows for JSON primitives to be inserted: strings, numbers, and special values for true, false or null. There is no way to compare for uniqueness without descending into each JSON object and comparing elements item by item.

Adds the specified delta (change) to an existing value, creating the element if it doesn’t exist. It will default both the value and delta to 0. If the delta is negative, the value of the element will be decremented by the given delta.

I’ll create a method that uses Counter:

Then, I’ll call the method twice using a positive 1 and a negative 1 as the “deltas”:

After the first call, since the element doesn’t exist it will be created and then set to one (1). The document will now look like this:

The second call passes a negative one (-1), so then the counter for likes will be decremented to zero (0). The JSON document will now look like this:

The sub-document API gives you the ability to be more granular in your interactions with documents. You can modify and retrieve just the portions that you need.

Leave a comment below, talk to me on Twitter, or email me (matthew.groves AT couchbase DOT com) if you have any questions or comments.