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:
{
"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.