{"id":2174,"date":"2016-07-28T18:54:41","date_gmt":"2016-07-28T18:54:41","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2174"},"modified":"2022-11-04T16:06:32","modified_gmt":"2022-11-04T23:06:32","slug":"subdoc-explained","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/subdoc-explained\/","title":{"rendered":"Using the Sub-Document API to get (only) what you want"},"content":{"rendered":"

In Matthew’s blog<\/a> the Sub-Document (subdoc<\/em>) API feature is introduced with a short overview: In summary, subdoc allows efficient access to parts of documents (sub<\/em>-documents) without requiring the transfer of the entire document over the network.<\/p>\n

Throughout this blog, we’ll use a reference document. This document will then be accessed through various ways using the subdoc API. Note that for each subdocument operation, doc_size - op_size<\/code> bytes of bandwidth are being saved, where doc_size<\/code> is the length of the document, and op_size<\/code> is the length of the path and sub-document value.<\/p>\n

The document below is 500 bytes. Performing a simple get()<\/code> would consume 500 bytes (plus protocol overhead) on the server response. If you only care for the delivery address, you could issue a lookup_in('customer123', SD.get('addresses.delivery'))<\/code> call. You would receive only about 120 bytes over the network, a savings of over 400 bytes, using a quarter of the bandwidth of the equivalent full-document (fulldoc<\/em>) operation.<\/p>\n

{\r\n  \"name\": \"Douglas Reynholm\",\r\n  \"email\": \"douglas@reynholmindustries.com\",\r\n  \"addresses\": {\r\n    \"billing\": {\r\n      \"line1\": \"123 Any Street\",\r\n      \"line2\": \"Anytown \",\r\n      \"country\": \"United Kingdom\"\r\n    },\r\n    \"delivery\": {\r\n      \"line1\": \"123 Any Street\",\r\n      \"line2\": \"Anytown \",\r\n      \"country\": \"United Kingdom\"\r\n    }\r\n  },\r\n  \"purchases\": {\r\n    \"complete\": [\r\n      339, 976, 442, 666\r\n    ],\r\n    \"abandoned\": [\r\n      157, 42, 999\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n
I’ll be demonstrating examples using a development branch of the Python SDK<\/a> and Couchbase Server 4.5 Developer Preview<\/a>.
\n[EDIT:\u00a0<\/b>An experimental version of the sub-document API is now available in the latest Python SDK<\/a>, version 2.0.8, and the examples below have been updated to reflect the latest API]<\/p>\n
You can read about the other new features in Couchbase 4.5 in Don Pinto’s blog post<\/a><\/p>\n
Subdoc operations<\/h3>\n
A subdoc operation is a single action for a single path in a document. This may be expressed as GET('addresses.billing')<\/code> or ARRAY_APPEND('purchases.abandoned', 42)<\/code>. Some operations are lookups<\/em> (they simply return data without modifying the document) while some are mutations<\/em> (they modify the contents of the document).<\/p>\n
Many of the subdoc operations are smaller scale equivalents of fulldoc operations. It helps to think of a single document as being itself a miniature key-value store. In the Python SDK, operations can be specified via special functions in the couchbase.subdocument<\/code> module, which I will abbreviate in the rest of this blog as SD<\/code>. This is done by<\/p>\n
import couchbase.subdocument as SD<\/code><\/pre>\n
While looking at these operations, note that what is being transmitted over the network is only the arguments passed to the subdoc API itself, rather than the contents of the entire document (as would be with fulldoc). While the document itself may seem small, even a simple<\/p>\n
Lookup Operations<\/h3>\n
Lookup operations queries the document for a certain path and returns that path. You have a choice of actually retrieving<\/em> the document path using the GET<\/code> operation, or simply querying the existence<\/em> of the path using the EXISTS<\/code> operation. The latter saves even more bandwidth by not retrieving the contents of the path if it is not needed.<\/p>\n
rv = bucket.lookup_in('customer123', SD.get('addresses.delivery.country'))\r\ncountry = rv[0] # => 'United Kingdom'<\/code><\/pre>\n
rv = bucket.lookup_in('customer123', SD.exists('purchases.pending[-1]'))\r\nrv.exists(0) # (check if path for first command exists): =>; False<\/code><\/pre>\n
In the second snippet, I also show how to access the last element of an array, using the special [-1]<\/code> path component.<\/p>\n
We can also combine these two operations:<\/p>\n
rv = bucket.lookup_in('customer123',\r\n                  SD.get('addresses.delivery.country'),\r\n                  SD.exists('purchases.pending[-1]'))\r\nrv[0] # => 'United Kingdom'\r\nrv.exists(1) # => False\r\nrv[1] # => SubdocPathNotFoundError<\/code><\/pre>\n
Mutation Operations<\/h3>\n
Mutation operations modify one or more paths in the document. These operations can be divided into several groups:<\/p>\n