Sub-Document API

High performance Sub-Document API for more efficient use of network bandwidth than fetching entire documents.

Sub-Document operations may be quicker and more network-efficient than full-document operations such as upsert, replace and get because they only transmit the accessed sections of the document over the network.

Sub-Document operations are also atomic, in that if one Sub-Document mutation fails then all will, allowing safe modifications to documents with built-in concurrency control.


While full-document retrievals retrieve the entire document and full document updates require sending the entire document, Sub-Document retrievals only retrieve relevant parts of a document and Sub-Document updates only require sending the updated portions of a document.

You should use Sub-Document operations when you are modifying only portions of a document, and full-document operations when the contents of a document is to change significantly.

The Sub-Document operations described on this page are for Key-Value requests only: they are not related to Sub-Document N1QL queries. (Sub-Document N1QL queries are explained in the section Querying with N1QL.)

In order to use Sub-Document operations you need to specify a path indicating the location of the Sub-Document. The path follows N1QL syntax. Considering the document:

  "name": "Douglas Reynholm",
  "email": "",
  "addresses": {
    "billing": {
      "line1": "123 Any Street",
      "line2": "Anytown",
      "country": "United Kingdom"
    "delivery": {
      "line1": "123 Any Street",
      "line2": "Anytown",
      "country": "United Kingdom"
  "purchases": {
    "complete": [
      339, 976, 442, 666
    "abandoned": [
      157, 42, 999

The paths name, and purchases.complete[0] are all valid paths.

Sub-Doc from the SDK

The Sub-Document APIs is exposed through two separate builders which are available through two top-level Collection methods LookupIn and MutateIn. The object returned, and how to work with it, is extensively documented in our practical guide to using Sub-Doc from the SDK.