{"id":2192,"date":"2016-03-10T21:51:31","date_gmt":"2016-03-10T21:51:30","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2192"},"modified":"2025-10-09T07:10:18","modified_gmt":"2025-10-09T14:10:18","slug":"developer-preview-of-new-sub-document-api-included-w-2-2-6-release-of-couchbase-net-sdk","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/developer-preview-of-new-sub-document-api-included-w-2-2-6-release-of-couchbase-net-sdk\/","title":{"rendered":"Developer Preview of new Sub-document API included w\/2.2.6 release of Couchbase .NET SDK"},"content":{"rendered":"

Note: all examples can be found here<\/a>.<\/strong><\/p>\n

Today we are releasing a very special Developer Preview (DP) of a new feature in the upcoming release of Couchbase Server called Sub-document<\/em>, along with our normal Couchbase Server .NET SDK 2.2.6! The Sub-document API is a new feature of Couchbase Server that is available in the Developer Preview of Couchbase Server 4.5.<\/p>\n

If you recall, in Couchbase all document mutations are 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’t 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<\/i>\u00a0of the fragment to be mutated\u00a0is sent over the wire and only that part of the document is modified.<\/p>\n

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

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

IMPORTANT: Sub-document API is a Developer Preview!!!<\/h2>\n

Please note that this is an early DP of the Sub-document API and has not gone through the usual checks and balances that are normal API’s go through before a release. Additionally, based on user feedback, the public interfaces may change in subsequent releases, therefore it is not suggested you use the Sub-document API in production…just yet. The rest of 2.2.6 has been tested, however, and is ready for production usage.<\/em><\/strong><\/p>\n

Prerequisite: Couchbase Server 4.5.0 Developer Preview<\/h3>\n

In order to follow the examples below, you’ll need to download and install Couchbase Server 4.5 developer preview<\/a>. Go, do this now!<\/p>\n

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

The following examples will use a document with an id of “puppy” and will look like this:<\/p>\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}\r\n<\/code><\/pre>\n
All of the examples are available on Github <\/a>so you can clone the project and play around with the API.<\/p>\n
MutateInBuilder and LookupInBuilder<\/h3>\n
As mentioned previously, 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 or id of the document you are working against:<\/p>\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();\r\n<\/code><\/pre>\n
Once you have the builder object, you can chain together a number of operations to execute against the document, for example:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Get(\"type\").\r\n            Get(\"name\").\r\n            Get(\"owner\").\r\n            Exists(\"notfound\");\r\n<\/code><\/pre>\n
Then you can send all of the operations to the server in a single batch:<\/p>\n
var fragment = builder.Execute();\r\n<\/code><\/pre>\n
And then check the result of one operation operation for the path type<\/code>:<\/p>\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}\r\n<\/code><\/pre>\n
The IDocumentFragment<\/p>\n\n\n\n\n\n\n\n\n\n\n
Name<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Content(…)<\/td>\nGets the content for a given path or index.<\/td>\n<\/tr>\n
Exists(…)<\/td>\nReturns true if there is a result for a given path or index.<\/td>\n<\/tr>\n
Count()<\/td>\nThe count of current operations maintained by the builder.<\/td>\n<\/tr>\n
OpStatus(…)<\/td>\nThe ResponseStatus<\/code> of an operation at a given index or path.<\/td>\n<\/tr>\n
Status<\/td>\nThe ResponseStatus<\/code> for the entire multi-operation.<\/td>\n<\/tr>\n
Success<\/td>\nTrue if the entire multi-operation succeeds.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Besides these properties or methods, there are all of the other properties inherited from OperationResult<\/code> which is the standard response from a K\/V operation: Upsert, Remove, Replace, etc.<\/p>\n
Error Handling<\/h3>\n
When sending multiple mutations,\u00a0if\u00a0one of them\u00a0fails, the entire multi-operation request fails, allowing 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.\u00a0If the operations failed then\u00a0Status property will contain a top-level error response such as SubDocMultiPathFailure,<\/code>\u00a0which\u00a0is an indication to dig deeper into the operation’s results to get the specific error. You can do this by iterating by calling the OpStatus method and passing either the index or the path:<\/p>\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\"));\r\n<\/code><\/pre>\n
In this case since the path didn’t 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 – this is a brief introduction and should be suitable for starting out with the API.<\/p>\n
LookupInBuilder Examples<\/h2>\n
The LookUpInBuilder supports two operations: fetching a value by path and checking for the existence of a value at a given path.<\/p>\n
Get:<\/h3>\n
Let’s lookup the owner<\/code> fragment by path<\/code>:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Get(\"owner\").\r\n            Execute();\r\n\r\nvar owner = builder.Content(\"owner\");\r\n<\/code><\/pre>\n
The output is:<\/p>\n
{\r\n    \"type\": \"servant\",\r\n    \"name\": \"Don Knotts\",\r\n    \"age\": 63\r\n}\r\n<\/code><\/pre>\n
Exist:<\/h3>\n
Let’s check if the owner<\/code> path exists:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Exists(\"owner\").\r\n            Execute();\r\n\r\nvar found = builder.Content(\"owner\");\r\n<\/code><\/pre>\n
The output is true<\/code>, the path owner<\/code> does indeed exist within the document.<\/p>\n
MutateInBuilder<\/h2>\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
Insert:<\/h3>\n
Insert adds a value to a dictionary optionally allowing for the containing element (the dictionary itself) to be added:<\/p>\n
var builder = bucket.MutateIn(id).\r\n            Insert(\"attributes.hairLength\", \"short\").\r\n            Execute();\r\n<\/code><\/pre>\n
The document’s attributes dictionary will now look like this:<\/p>\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...\r\n<\/code><\/pre>\n
Now if the parent element doesn’t exist, the createParents<\/code> parameter can be used to create the parent element. This is true by default, so you do not have to do anything – pass false if you want to fail if the parent element doesn’t exist:<\/p>\n
var builder = bucket.MutateIn(id).\r\n            Insert(\"anewattribute.withakey\", \"somevalue\").\r\n            Execute();\r\n<\/code><\/pre>\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
...\r\n\"anewattribute\": \r\n{\r\n    \"withakey\": \"somevalue\"\r\n}\r\n...\r\n<\/code><\/pre>\n
Now, if we passed on 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
Upsert<\/h3>\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
Remove<\/h3>\n
Remove<\/code> will remove an element at a given path. As an example, we will remove the owner’s name from the document above:<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            Remove(\"owner.name\").\r\n            Execute();\r\n<\/code><\/pre>\n
And the document after called Remove<\/code>:<\/p>\n
...\r\n\"owner\": \r\n{\r\n    \"type\": \"servant\",\r\n    \"age\": 63\r\n},\r\n...\r\n<\/code><\/pre>\n
Replace<\/h3>\n
Replace will swap the value of element at a given path, failing if the path does not exist:<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            Replace(\"owner\", new { CatLover=true, CatName=\"celia\"}).\r\n            Execute();\r\n<\/code><\/pre>\n
The document will now have a different value for “owner”:<\/p>\n
...\r\n\"owner\": \r\n{\r\n    \"catLover\": true,\r\n    \"catName\": \"celia\"\r\n},\r\n...\r\n<\/code><\/pre>\n
PushBack<\/h3>\n
Adds a value to the back of an array optionally adding the parent element (the array element itself) if it doesn’t exist.<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            PushBack(path, value, false).\r\n            Execute();\r\n<\/code><\/pre>\n
The toys<\/code> array in the document now has the value “slipper” in the last ordinal:<\/p>\n
...\r\n\"toys\": \r\n[ \r\n    \"squeaker\", \r\n    \"ball\", \r\n    \"shoe\", \r\n    \"slipper\"\r\n],\r\n...\r\n<\/code><\/pre>\n
PushFront<\/h3>\n
Adds a value to the front of an array optionally adding the parent element (the array itself) if it doesn’t exist:<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            PushFront(path, value, false).\r\n            Execute();\r\n<\/code><\/pre>\n
The toys<\/code> array now has the value “slipper” in it’s first ordinal:<\/p>\n
...\r\n\"toys\": \r\n[\r\n    \"slipper\",\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\"\r\n],\r\n...\r\n<\/code><\/pre>\n
ArrayInsert<\/h3>\n
Inserts a value into an array at a given index:<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            ArrayInsert(\"toys[2]\", \"slipper\").\r\n            Execute();\r\n<\/code><\/pre>\n
The toys<\/code> array now has the value “slipper” at it’s 3rd ordinal (index 2):<\/p>\n
\"toys\": \r\n[\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"slipper\",\r\n    \"shoe\"\r\n ],\r\n<\/code><\/pre>\n
AddUnique<\/h3>\n
Inserts a value into an array, failing if it exists (the value must be unique within the array):<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            AddUnique(\"toys\", \"shoe\").\r\n            Execute();\r\n<\/code><\/pre>\n
Since the value “shoe” already exists in the original document’s toys<\/code> array, this will fail withe following status:<\/p>\n
SubDocPathExists\r\n<\/code><\/pre>\n
Note that this method only allows for JSON primitives to be inserted: strings, numbers, and special values for true, false or null. The reason is that there is no way to compare for uniqueness without descending into each JSON object and comparing elements item by item.<\/p>\n
Counter<\/h3>\n
Adds a the specified delta to an existing value, creating the element if it doesn’t exist and defaulting 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
var fragment = bucket.MutateIn(id).\r\n            Counter(\"likes\", 1).\r\n            Execute();\r\n<\/code><\/pre>\n
Since the element doesn’t exist it will be created and then set to one (1). The document will now look like this:<\/p>\n
...\r\n    ],\r\n    \"likes\": 1\r\n}\r\n<\/code><\/pre>\n
If we pass a negative one (-1), then the counter for likes<\/code> will be decremented back to zero (0):<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            Counter(\"likes\", -1).\r\n            Execute();\r\n<\/code><\/pre>\n
And the JSON document will now look like this:<\/p>\n
...\r\n    ],\r\n    \"likes\": 0\r\n}\r\n<\/code><\/pre>\n
Release Notes for v2.2.6<\/h2>\n
Bug<\/h3>\n