CouchDB Data Modelling: Prefer Smaller Documents posted Thursday, February 13, 2025 by The Neighbourhoodie Team

CouchDB document design has a big impact on database performance — so how do you get it right?

CouchDB allows for a lot of flexibility when deciding how to structure your data into documents. You can have a few large documents, or many small ones, or both, and CouchDB will mostly work fine with whatever you store into it.

At the same time, there are a few best practices that can help CouchDB to work best for you. One of these best practices is preferring smaller documents.

CouchDB Documents#

The document is the smallest unit of operation in CouchDB, and everything you do with CouchDB will be influenced by how you structure your documents.

Basic reading and writing data through documents is contingent on document size: read a document and CouchDB will have to read it from the underlying storage disk, encode the JSON body and send it to you via a HTTP response. Writing a doc, same story in reverse. When creating view indexes, CouchDB loads each document in turn and applies it to your index definition.

Designing Small Documents#

Now the best practice should become clear: the smaller your document is, the less work CouchDB has to do to fulfil them, and as a result, the faster all common operations in CouchDB get.

When using PouchDB with CouchDB, small docs have an additional advantage: both replication as well as PouchDB performance benefit from smaller documents.

There are a lot of considerations that go into deciding what your documents should look like, but when in doubt, opt for the smaller document.

This leaves us to discuss the lower bound, i.e. “how small should documents be?” The guideline here is all data that naturally “goes together”. In an address book, a document includes the most common fields pertaining to a person. When taking a sensor measurement, all metrics plus a timestamp for the measurement go into a document, etc.

But when logging trips you’ve done on your bike, the bike gets its own document and each trip is a separate document, instead of putting the bike and trips into a single document.

In CouchDB 3.0 the default document size was reduced from 4GB to 8MB. 4GB in practice wasn’t going to work very well anyway. If you need to use larger docs in 3.0, you can increase the limit.

« Back to the blog post overview