Sub-Documents

concept

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.

Sub-Documents

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 SQL++ (formerly N1QL) queries. (Sub-Document SQL++ queries are explained in the section Querying with SQL++.)

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

customer123.json

{
  "name": "Douglas Reynholm",
  "email": "douglas@reynholmindustries.com",
  "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, addresses.billing.country 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.