A newer version of this documentation is available.

View Latest

Dealing with non-JSON documents

Store and retrieve non-JSON ("binary") data with Couchbase

Couchbase is a document database and functions best when document contents are JSON. Nevertheless Couchbase may be used to store non-JSON data for various use cases.

Non-JSON formats may be more efficient in terms of memory and processing power (for example, if storing only flat strings, JSON adds an additional syntactical overhead of two bytes per string). Non-JSON documents may be desirable if migrating a legacy application which is using a customized binary format.

Note that only JSON documents can be accessed using Query (N1QL). Limited support for non-JSON documents is available for MapReduce views. Additionally, non-JSON documents will not be accessible using the Web UI (the contents will be shown in their Base64 equivalent).

Using non-JSON documents with SDKs

Couchbase SDKs have options for storing documents as non-JSON. The process is different for each SDK. Some SDKs will offer a format option to store a non-JSON value, while others will have a special "Raw Document" type.

You may extend the SDK by using a transcoder, which can help make handling non-JSON documents a bit more transparent to the application.

Here is an example of storing a non-JSON document using the Python SDK:

>>> cb.upsert('binary_doc', "\x01\x02\x03\x00\x03\xff", format=FMT_BYTES)
OperationResult<RC=0x0, Key=u'binary_doc', CAS=0x553debe8f413>