Sub-Documents

  • concept
January 19, 2025
+ 12
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
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.