The Data Model

Couchbase’s use of JSON as a storage format allows powerful search and query over documents. Several data structures are supported by the SDK, including map, list, queue, and set.

These pages cover the sixth alpha release of the Couchbase Scala SDK — 1.0.0-alpha.6. As such they are likely to change without notice. This alpha code should not be used in production.

Documentation is incomplete, subject to change, and likely to contain broken links.

The power to search, query, and easily work with data in Couchbase, comes from the choice of JSON as a storage format. Non-JSON storage is supported — see the nonjson.adoc — including UTF-8 strings, raw sequences of bytes, and language specific serializations, however, only JSON is supported by n1ql-query.adoc. In Couchbase, JSON’s key-value structure allows the storage of collection data structures such as lists, maps, sets and queues — see below. JSON’s tree-like structure allows operations against subdocument.adoc, and efficient support for these data structures.

Data Structures

Data structures in Couchbase are similar in concept to data structures in C# (.NET):

  • Map is like .NET Dictionary<TKey, TValue>, and is a key-value structure, where a value is accessed by using a key string.

  • List is like a .NET List<TValue> and is a sequential data structure. Values can be placed in the beginning or end of a list, and can be accessed using numeric indexes.

  • Queue is like a IQueue implementation which offers FIFO (first-in-first-out) semantics, allowing it to be used as a lightweight job queue.

  • Set is a wrapper over a List<TValue> which provides the ability to handle unique values.

These data structures are stored as JSON documents in Couchbase, and can therefore be accessed using N1QL and normal key-value operations. Data structures can also be manipulated using the traditional sub-document and full-document KV APIs.

Using the data structures API may help your application in two ways:

  • Simplicity: Data structures provide high level operations by which you can deal with documents as if they were container data structures. Adding an item to a dictionary is expressed as MapAdd, rather than retrieving the entire document, modifying it locally, and then saving it back to the server.

  • Efficiency: Data structure operations do not transfer the entire document across the network. Only the relevant data is exchanged between client and server, allowing for less network overhead and lower latency.

Besides the IBucket level data structure methods, there is a new namespace called Couchbase.Collections which contains implementations of some of the core interfaces in System.Collection.Generics such as ISet<TValue>, IList<TValue>, IDictionary<Tkey, TValue> and a CouchbaseQueue class. See section The Couchbase.Collections Namespace below for more details.

Creating a Data Structure