{"id":2327,"date":"2016-07-12T13:18:54","date_gmt":"2016-07-12T13:18:53","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2327"},"modified":"2025-10-09T07:25:56","modified_gmt":"2025-10-09T14:25:56","slug":"sub-document-api-in-couchbase-server-4-5-with-the-net-sdk-revisted","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/sub-document-api-in-couchbase-server-4-5-with-the-net-sdk-revisted\/","title":{"rendered":"Sub-document API in Couchbase Server 4.5 with the .NET SDK (revisited)"},"content":{"rendered":"
\n
\n

This blog post is based on an earlier blog post by Jeff Morris<\/a> that covered the sub-document API while it was still in developer preview. There have been some changes to the API since that release.<\/em><\/p>\n<\/div>\n

\n

With Couchbase Server 4.5<\/a> and the .NET SDK 2.3.x<\/a>, you can now use the Sub-document<\/em> feature in your .NET application.<\/p>\n<\/div>\n

\n

In previous Couchbase releases, all document mutations were atomic and involve the entire document. If you only want to change a single field and then do an update, the entire document in Couchbase server is copied over by the new revision. The problem with is that if the document is large or the network slow (or both), then a lot of resources are wasted sending data that hasn\u2019t been modified. A better, more performant solution would be to just send the portion of the document or the value which has been mutated. Essentially, that is what you get with sub-document API; when you update an element or delete an element of a document, only the path of the fragment to be mutated is sent over the wire and only that part of the document is modified.<\/p>\n<\/div>\n

\n
\"Subdocument\"<\/div>\n<\/div>\n
\n

There are several different operations that are supported by the API, from mutations on individual nested elements (aka sub-<\/em>documents) to array and dictionary modifications. Counter operations are also supported, as are retrieval operations for embedded JSON fragments.<\/p>\n<\/div>\n

\n

The API is exposed via a fluent<\/em> interface which allows you to append multiple operations and then execute them against the document atomically. There are two different “builders”: a builder for mutation operations and a builder for reads or “lookups” (which can also check if an element exists at a given path).<\/p>\n<\/div>\n<\/div>\n

\n

Prerequisite: Couchbase Server 4.5<\/h3>\n
\n

In order to follow the examples below, you\u2019ll need to download and install Couchbase Server 4.5<\/a>. If you\u2019ve never installed Couchbase Server before, you can check out my video on how to install Couchbase Server on Windows<\/a>. It\u2019s really easy, no matter what OS you are using.<\/p>\n<\/div>\n<\/div>\n

\n

Sub-Document API Overview<\/h2>\n
\n
\n

The following examples will use a document with an id of “puppy” and will start out looking like this:<\/p>\n<\/div>\n

\n
\n
  {\r\n  \"type\": \"dog\",\r\n  \"breed\": \"Pitbull\/Chihuahua\",\r\n  \"name\": \"Puppy\",\r\n  \"toys\": [\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\"\r\n  ],\r\n  \"owner\": {\r\n    \"type\": \"servant\",\r\n    \"name\": \"Don Knotts\",\r\n    \"age\": 63\r\n  },\r\n  \"attributes\": {\r\n    \"fleas\": true,\r\n    \"color\": \"white\",\r\n    \"eyeColor\": \"brown\",\r\n    \"age\": 5,\r\n    \"dirty\": true,\r\n    \"sex\": \"female\"\r\n  }\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
All of the examples are available on Github<\/a> so you can clone the project and play around with the API.<\/p>\n<\/div>\n
\n
MutateInBuilder and LookupInBuilder<\/h3>\n
\n
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<\/code> or LookupIn<\/code> on a CouchbaseBucket<\/code> object and passing in the key of the document you are working against:<\/p>\n<\/div>\n
\n
\n
\/\/Initialize the cluster helper with the default settings - i.e. localhost\r\nClusterHelper.Initialize();\r\nvar bucket = ClusterHelper.GetBucket(\"default\");\r\n\r\n\/\/create a mutation builder for the document \"thekey\"\r\nvar mutate = bucket.MutateIn(\"thekey\");\r\n\r\n\/\/create a lookup builder for the document \"thekey2\"\r\nvar lookup = bucket.LookupIn(\"thekey2\");\r\n\r\nClusterHelper.Close();<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Once you have the builder object, you can chain together a number of operations to execute against the document, for example:<\/p>\n<\/div>\n
\n
\n
var builder = bucket.LookupIn(id).\r\n    Get(\"type\").\r\n    Get(\"name\").\r\n    Get(\"owner\").\r\n    Exists(\"notfound\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Then you can send all of the operations to the server in a single batch:<\/p>\n<\/div>\n
\n
\n
var fragment = builder.Execute();<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
You can check the result of one operation, by using OpStatus and a path. In this example, I\u2019m using the path \"type\"<\/code>:<\/p>\n<\/div>\n
\n
\n
if (fragment.OpStatus(\"type\") == ResponseStatus.Success)\r\n{\r\n    string format = \"Path='{0}' Value='{1}'\";\r\n    Console.WriteLine(format, \"type\", fragment.Content(\"type\"));\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
These are some of the methods and fields you\u2019ll find on the IDocumentFragment<\/code> interface.<\/p>\n<\/div>\n\n\n\n\n\n\n\n\n\n
\n
Name<\/p>\n<\/td>\n
\n
Description<\/p>\n<\/td>\n<\/tr>\n
\n
Content(\u2026\u200b)<\/p>\n<\/td>\n
\n
Gets the content for a given path or index.<\/p>\n<\/td>\n<\/tr>\n
\n
Exists(\u2026\u200b)<\/p>\n<\/td>\n
\n
Returns true if there is a result for a given path or index.<\/p>\n<\/td>\n<\/tr>\n
\n
Count()<\/p>\n<\/td>\n
\n
The count of current operations maintained by the builder.<\/p>\n<\/td>\n<\/tr>\n
\n
OpStatus(\u2026\u200b)<\/p>\n<\/td>\n
\n
The ResponseStatus<\/code> of an operation at a given index or path.<\/p>\n<\/td>\n<\/tr>\n
\n
Status<\/p>\n<\/td>\n
\n
The ResponseStatus<\/code> for the entire multi-operation.<\/p>\n<\/td>\n<\/tr>\n
\n
Success<\/p>\n<\/td>\n
\n
True if the entire multi-operation succeeds.<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n
Besides these properties or methods, there are all of the other properties inherited from OperationResult<\/code> (which is the standard response from a key\/value operation): Upsert, Remove, Replace, and so on.<\/p>\n<\/div>\n<\/div>\n
\n
Error Handling<\/h3>\n
\n
When sending multiple mutations<\/em>, 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.<\/p>\n<\/div>\n
\n
When sending multiple lookups<\/em>, some operations may succeed and some may fail, with the server attempting to return as many items as requested.<\/p>\n<\/div>\n
\n
If the operation(s) failed, then the`Status` property will contain a top-level error response such as SubDocMultiPathFailure<\/code>. This is an indication that you should dig deeper into the operation\u2019s results to get the specific error. You can do this by iterating: calling the OpStatus<\/code> method and passing either the index or the path:<\/p>\n<\/div>\n
\n
\n
var builder = bucket.LookupIn(id).\r\n    Get(\"type\").\r\n    Get(\"somepaththatdoesntexist\").\r\n    Get(\"owner\");\r\n\r\nvar fragment = builder.Execute();\r\nConsole.WriteLine(\"Generic error: {0}{1}Specific Error: {2}\",\r\n    fragment.Status, Environment.NewLine, fragment.OpStatus(1));\r\n\r\nConsole.WriteLine(\"Generic error: {0}{1}Specific Error: {2}\",\r\n   fragment.Status, Environment.NewLine, fragment.OpStatus(\"somepaththatdoesntexist\"));<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
In this case, since the path \u201csomepaththatdoesntexist\u201d didn\u2019t exist within the document, the specific error returned was SubDocPathNotFound<\/code>. There are many different combinations of errors depending upon the builder type and the condition for the error.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
LookupInBuilder Examples<\/h2>\n
\n
\n
The LookUpInBuilder<\/code> type supports two operations: fetching a value by path and checking for the existence of a value at a given path.<\/p>\n<\/div>\n
\n
Get:<\/h3>\n
\n
Let\u2019s lookup the owner<\/code> fragment. If I pass in “owner” as the path parameter to this method\u2026\u200b<\/p>\n<\/div>\n
\n
\n
public static void GetExample(IBucket bucket, string path, string id)\r\n{\r\n    var builder = bucket.LookupIn(id).\r\n        Get(path).\r\n        Execute();\r\n\r\n    var fragment = builder.Content(path);\r\n    Console.WriteLine(fragment);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
\u2026\u200bthe output to console would be:<\/p>\n<\/div>\n
\n
\n
{\r\n    \"type\": \"servant\",\r\n    \"name\": \"Don Knotts\",\r\n    \"age\": 63\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
Exist:<\/h3>\n
\n
We can also check to see if a path exists. If I pass in “owner” as the path to this method\u2026\u200b<\/p>\n<\/div>\n
\n
\n
public static void ExistsExample(IBucket bucket, string path, string id)\r\n{\r\n    var builder = bucket.LookupIn(id).\r\n        Exists(path).\r\n        Execute();\r\n\r\n    var found = builder.Content(path);\r\n    Console.WriteLine(found);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
\u2026\u200bthe output is true<\/code>, because the path owner<\/code> does indeed exist within the document.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
MutateInBuilder<\/h2>\n
\n
\n
The MutateInBuilder offers a number of methods supporting mutations on scalar values, dictionaries and arrays, along with support for atomic counter operations.<\/p>\n<\/div>\n
\n
Insert:<\/h3>\n
\n
Insert adds a value to a dictionary, optionally allowing for the containing element (the dictionary itself) to be added.<\/p>\n<\/div>\n
\n
\n
public static void InsertExample(IBucket bucket, string id, string path, string value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        Insert(path, value, true).  \/\/ false is the default\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
If I called the above method like so:<\/p>\n<\/div>\n
\n
\n
InsertExample(bucket, id,\"attributes.hairLength\", \"short\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Then the document\u2019s attributes dictionary will now look like this:<\/p>\n<\/div>\n
\n
\n
...\r\n\"attributes\":\r\n{\r\n    \"fleas\": true,\r\n    \"color\": \"white\",\r\n    \"eyeColor\": \"brown\",\r\n    \"age\": 5,\r\n    \"dirty\": true,\r\n    \"sex\": \"female\",\r\n    \"hairLength\": \"short\"\r\n}\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Note that the Insert<\/code> method has an optional boolean parameter called createParents<\/code>. It is false by default. If it\u2019s true, then the sub-document API will create the necessary path for the field to exist. If it\u2019s false, the sub-document API will only create the field if the parents of the field already exist. In the above example, the attributes<\/code> field already existed.<\/p>\n<\/div>\n
\n
In this next example, I\u2019ll use a path with a parent field (anewattribute<\/code>) that doesn\u2019t already exist.<\/p>\n<\/div>\n
\n
\n
InsertExample(bucket, id, \"anewattribute.withakey\", \"somevalue\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
This will create the new attribute called anewattribute<\/code> in the document and add a single key called withakey<\/code> with a value of somevalue<\/code>.<\/p>\n<\/div>\n
\n
\n
...\r\n\"anewattribute\":\r\n{\r\n    \"withakey\": \"somevalue\"\r\n}\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Now, if we passed false<\/code> for createParents<\/code> and the parent attribute did not exist, then the multi-mutation would fail with a top-level response status of SubDocMultiPathFailure<\/code> and the specific error would be SubDocPathNotFound<\/code>.<\/p>\n<\/div>\n<\/div>\n
\n
Upsert<\/h3>\n
\n
Upsert will add or replace an existing dictionary entry. The usage is exactly the same as Insert<\/code> with the exception of the method name being Upsert<\/code>.<\/p>\n<\/div>\n<\/div>\n
\n
Remove<\/h3>\n
\n
Remove<\/code> will remove an element at a given path.<\/p>\n<\/div>\n
\n
\n
public static void RemoveExample(IBucket bucket, string id, string path)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        Remove(path).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
When I call this method:<\/p>\n<\/div>\n
\n
\n
RemoveExample(bucket, id, \"owner.name\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Here\u2019s how the document will look afterwards:<\/p>\n<\/div>\n
\n
\n
...\r\n\"owner\":\r\n{\r\n    \"type\": \"servant\",\r\n    \"age\": 63\r\n},\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
Replace<\/h3>\n
\n
Replace will swap the value of element at a given path, failing if the path does not exist:<\/p>\n<\/div>\n
\n
\n
public static void ReplaceExample(IBucket bucket, string id, string path, object value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        Replace(path, value).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
After I call this method:<\/p>\n<\/div>\n
\n
\n
ReplaceExample(bucket, id, \"owner\", new { CatLover=true, CatName=\"celia\"});<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
The document will now have a different value for “owner”:<\/p>\n<\/div>\n
\n
\n
...\r\n\"owner\":\r\n{\r\n    \"catLover\": true,\r\n    \"catName\": \"celia\"\r\n},\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
ArrayAppend<\/h3>\n
\n
ArrayAppend adds a value to the end of an array, optionally adding the parent element (the array element itself) if it doesn\u2019t exist.<\/p>\n<\/div>\n
\n
\n
public static void ArrayAppendExample(IBucket bucket, string id, string path, object value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        ArrayAppend(path, value, false).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
After that method with the “toys” path\u2026\u200b<\/p>\n<\/div>\n
\n
\n
ArrayAppendExample(bucket, id, \"toys\", \"slipper\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
\u2026\u200bthe toys<\/code> array in the document will then have the value “slipper” in the last ordinal:<\/p>\n<\/div>\n
\n
\n
...\r\n\"toys\":\r\n[\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\",\r\n    \"slipper\"\r\n],\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
ArrayPrepend<\/h3>\n
\n
ArrayPrepend works the same way as ArrayAppend, except it adds a value to the front<\/em> of an array.<\/p>\n<\/div>\n
\n
\n
public static void ArrayAppendExample(IBucket bucket, string id, string path, object value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        ArrayAppend(path, value, false).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Calling that method with the “toys” path\u2026\u200b<\/p>\n<\/div>\n
\n
\n
ArrayAppendExample(bucket, id, \"toys\", \"slipper\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
The toys<\/code> array now has the value “slipper” in it\u2019s first<\/em> ordinal:<\/p>\n<\/div>\n
\n
\n
...\r\n\"toys\":\r\n[\r\n    \"slipper\",\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\"\r\n],\r\n...<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
ArrayInsert<\/h3>\n
\n
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).<\/p>\n<\/div>\n
\n
\n
public static void ArrayInsertExample(IBucket bucket, string id, string path, object value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        ArrayInsert(path, value).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
And then calling that method with “toys[2]”\u2026\u200b<\/p>\n<\/div>\n
\n
\n
ArrayInsertExample(bucket, id, \"toys[2]\", \"slipper\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
The toys<\/code> array now has the value “slipper” at it\u2019s 3rd ordinal (index 2):<\/p>\n<\/div>\n
\n
\n
\"toys\":\r\n[\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"slipper\",\r\n    \"shoe\"\r\n ],<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
ArrayAddUnique<\/h3>\n
\n
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).<\/p>\n<\/div>\n
\n
\n
public static void ArrayAddUniqueExample(IBucket bucket, string id, string path, object value)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        ArrayAddUnique(path, value).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
When I call that with “shoe”\u2026\u200b<\/p>\n<\/div>\n
\n
\n
ArrayAddUniqueExample(bucket, id, \"toys\", \"shoe\");<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
\u2026\u200bsince the value “shoe” already exists in the original document\u2019s toys<\/code> array, this will fail with the status SubDocPathExists<\/code>.<\/p>\n<\/div>\n
\n
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.<\/em><\/p>\n<\/div>\n<\/div>\n
\n
Counter<\/h3>\n
\n
Adds the specified delta (change) to an existing value, creating the element if it doesn\u2019t 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.<\/p>\n<\/div>\n
\n
I\u2019ll create a method that uses Counter<\/code>:<\/p>\n<\/div>\n
\n
\n
public static void CounterExample(IBucket bucket, string id, string path, long delta)\r\n{\r\n    var fragment = bucket.MutateIn(id).\r\n        Counter(path, delta).\r\n        Execute();\r\n\r\n    var status = fragment.OpStatus(path);\r\n    Console.WriteLine(status);\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Then, I\u2019ll call the method twice using a positive 1 and a negative 1 as the “deltas”:<\/p>\n<\/div>\n
\n
\n
CounterExample(bucket, id, \"likes\", 1);\r\nCounterExample(bucket, id, \"likes\", -1);<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
After the first call, since the element doesn\u2019t exist it will be created and then set to one (1). The document will now look like this:<\/p>\n<\/div>\n
\n
\n
...\r\n    ],\r\n    \"likes\": 1\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
The second call passes a negative one (-1), so then the counter for likes<\/code> will be decremented to zero (0). The JSON document will now look like this:<\/p>\n<\/div>\n
\n
\n
...\r\n    ],\r\n    \"likes\": 0\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
Conclusion<\/h2>\n
\n
\n
Since the developer preview blog post, the Couchbase .NET SDK has been updated to version 2.3.2 (as of the time of this blog post). You can check out the work that\u2019s been done in the Release Notes of Version 2.3.2<\/a>.<\/p>\n<\/div>\n
\n
How to get v2.3.x<\/h3>\n
\n