Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

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.

    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 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:

    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.