Cloudant Fundamentals: The Document

General tips on data modeling (part 1 of 10)

Glynn Bird
Apr 27, 2018 · 3 min read
  • numbers
  • booleans
  • objects
  • arrays of any of the above
Documents with different schemas within the same database? You’ll see that, in Cloudant, we can and should do that. Photo by Kristina Tripkovic on Unsplash.

Rules of thumb

Avoid thinking in joins

Cloudant doesn’t do joins like a relational database, so the JSON objects tend to be denormalised (i.e., contain repetitions of data held elsewhere) . Don’t try to model your data in a relational way and join it yourself in your app.

Size matters

Cloudant will refuse to store documents over 1MB in size, but you shouldn’t be going anywhere near that hard limit. The example document above is less than 1KB.

Schemaless doesn’t mean schema-free

Although Cloudant won’t object if you use a different schema for each document in your database, that’s probably not what you want. One of the first things I do when creating a new project is design the schema, in other words sketch the JSON that represents the objects I’m going to save and the data types of each key. I don’t have to tell Cloudant what the schema is, but that doesn’t mean I shouldn’t give careful consideration to my data model before I jump into the code.

Multiple object types in the same database

One widely used pattern that is odd to folks coming from a relational background is storing different object types in the same database. You could have blog posts and authors in the same Cloudant database using their own separate schema. One convention is to use the type field to indicate which flavour of object it is.

Write-only document patterns

Cloudant allows documents to be updated, but not on a field-by-field basis. For example, your e-commerce site can’t do:

  • a document every time an item is sold

Next time

Next time we’ll look at a vital component of a Cloudant document: the _id field.


Things we made with data at IBM’s Center for Open Source Data and AI Technologies.

Glynn Bird

Written by

Developer @ IBM.


Things we made with data at IBM’s Center for Open Source Data and AI Technologies.