How does couchbase lite work?

I have a question about how does exactly couchbase lite work. This question seems to be a little bit confusing, but I need a simple answer :slight_smile:
Previously I had an idea about how does couchbase work and it was this : It saves JSON strings in documents, then indexes and give us access to them.
But now I’m seeing wired things that says my previous idea is way wrong. As Jim Borrden mentioned Here

No, that is not a supported feature of the library because actually the storage format is not JSON strings but a compressed binary format so in order to support JSON strings we would have to first parse the JSON string to a JSON object anyway.

couchbase doesn’t save strings. WHY?
And they are not even JSON. They are Dictionary < T > .WHY JSON is ignored while all of the focus of couchbase tutorials was JSON data modeling?
And I saw SQLite library in litecore repo. SQL used in NoSQL? WHY?
These are the sub questions I have. They might be silly but I need to be clarified about how does couchbase lite exactly work.
And the very last hing: Is there any big diference about the way couchbase server and couchbase lite work? (in simple describtion not all details)

These questions would probably take an entire blog post to answer in full but here are some simplified explanations:

  1. Couchbase doesn’t save strings because strings waste space and are inefficient in general. Plus with our new binary format we can seek and parse pieces out of them without actually parsing the whole object into memory first (this is very awkward to do with strings). It might also come into play later for sending JSON in network requests to save bandwidth but that is not decided yet.

  2. Dictionary< K, V > is really just an in memory representation of a JSON object. The data is serialized as JSON, it is just not written as a string. On .NET I use JSON .NET to tokenize the object for me and then use those tokens to do the write.

  3. SQLite is used because it is incredibly reliable, mature (as I’m sure everyone knows), and nothing we have found yet has proven faster. Plus it works well with our goal of providing a more SQL-like query implementation that is less foreign to people than map / reduce, and as of 3.9 has ramped up support for working with JSON inside of columns (along with an abstract way to work on arbitrary sub types which is very useful for us). Bonus: there is an open source solution for providing encryption with an identical API. We tried for a while to replace it but failed in the end.

  4. There is an incredible difference in how server and lite works. One is a multi process application running on a powerful machine and the other is an embedded process that runs on a computer the size of an adult hand. The main interaction with server is through its REST API and the command line, and the main interaction with lite is through API calls. Server has a lot of different information stored in a variety of formats (indexing server, analytics engine, key value storage, caching, etc), and lite has just one


The fact that Couchbase Lite 2.0’s internal storage format isn’t JSON shouldn’t matter to an application developer. This is basically an internal optimization that helps make property access and querying efficient.

It may make sense to allow the app to get the document as JSON, for some purposes. It’s not going to be as fast as getting individual properties through the API, though, because it will involve re-encoding the entire document instead of just the pieces you’re interested in.

What’s the reason you want to get the document as JSON?

Thank you for details.
The reason why I’m interested in JSON is that handy tool named Newtonsoft.JSON that let’s me serialize and deserialize. :slight_smile:
And the way you use SQLite is a question for me.
anyway, I’m waiting for you to full describe it in a blog or something if you have time for it(with visualizations that we can understand the process better). I think It’s quite necessary specially for those who wanna get more info about couchbase and contribute. And of course those nosy people (like me) that are interested in realizing how does couchbase lite work as a database storage.

If you want to learn more about how CBL 2 stores data, you can read the docs of the format we use, Fleece. We have found that in CBL usage, parsing JSON into trees of objects (and vice versa) is a major source of slowdown. Fleece eliminates this.

This is especially important in indexing and querying, which has to look at properties inside large numbers of documents. The details of how use Fleece inside SQLite queries are complex, but basically we can read object properties out of the raw blob data in the database (in a callback during an SQLite query or indexing operation) without having to do any parsing or even any memory allocation.


@jens @hideki Is this same for android 1.4 and 2.0? How are documents saved in sqlitedb.

Is it like “In the SQLite case, the main document body is stored as a blob.”


Yes, basically. In the SQLite schema, there’s a blob column that stores the document JSON.