Sub-Document API

  • 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.


    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.