When beginning to learn about document databases, it’s nice to have a grasp of JSON data modeling basics. This will help you navigate the space and topics easier having an expanded vocabulary on the subject. Experience with a traditional relational database is also a good start. Knowledge about structuring data, querying, and indexes will give you a headstart. Some concepts will transfer over, especially when learning Couchbase, which utilizes a SQL variant (SQL++) for querying. Many of the terms you already know from SQL will be applicable but differ in that they apply to key-value document data storage and nested documents instead of tables and rows.

History of JSON

With the popularity of AJAX in the early 2000s, the term JSON was coined by Douglas Crockford. The first two links talk about a period of time before JSON when it was being used but didn’t have a name, up to the time period of Single Page Applications. The second link is a video from the last Silicon Valley Code Camp where I had the opportunity to attend Doug’s talk in 2019. His presentation on “The History of JSON” is a great way for us to begin our journey learning more about JSON data modeling.

Working with JSON

With a better understanding of its history and vocabulary, we can move on to actually working with JSON. The MDN link below will answer many questions on structure, obtaining JSON with XMLHttpRequest, and testing your own skills. You can test your understanding of the article at the end with a fun challenge. When you get done, you will be much more prepared to use JSON.

With JavaScript Object Notation basics out of the way, we are prepared to start our journey into document modeling.

JSON Data Modeling Tool

In this category, we first talk about JSON Data Modeling in general. In the upcoming sections, we will discuss strategies to migrate from relational databases.

Outlined below are highlights from each section of the video above, which covers why switching to NoSQL (in our case, a document database) can be beneficial. It covers JSON design strategies for modeling and accessing this data and discusses migration tips. Let’s explore some of the topics in this video.


Some databases, like Couchbase, store their data as plain JSON. This section highlights the many reasons to use a distributed document database. It also addresses the current NoSQL landscape and gives a brief understanding of its scalability, flexibility, availability, performance, and use cases.

List of use cases for NoSQL databases

Couchbase customer derived use cases for NoSQL

JSON Data Modeling

In this section, you are given an exercise on modeling data in JSON and provided JSON data modeling examples. This section is complete with properties of real-world data, a brief section on modeling in the relational world as a comparison, and rules of thumb on strategies for modeling your data. Also discussed are third-party modeling tools like Hackolade, Erwin, and Idera. These are tools geared toward NoSQL databases.

Relational vs JSON Data Modeling

Side by side comparison of table vs JSON data

Accessing Data

This part dives into the strategies and rules of thumb for modeling and accessing your data in a NoSQL database, like reading, updating, and deleting records by key. Recommendations for keys are given, along with some good JSON data model examples. We wrap up this section with approaches to subdocuments and sub-collections, the SQL++ query language found in Couchbase.

Modeling JSON data strategies for data access

Understanding JSON data structure and relationships is key for data access

Migrating Data

Here we get into the moving of data from one database to another with tools that will help you along the way. Tools like Informatica, Kafka, Talend, and Apache Nifi. Couchbase also has a tool called cbimport to help import data into Couchbase.

Keeping migration of data simple

Before investing in tools, keep it simple, use the database tools to help export, import, and transform

Migrating Data from RDBMS to NoSQL

When you are migrating data from a relational database there are many normalization constraints and schema requirements. These are required when working with tables or relating other tables through foreign keys. This type of linking using unique ids is also possible in a document database. There are other options, too, like nesting that data, even if it appears redundant. In this first category of resources, we provide links to courses, videos, and articles that will aid in moving from relational databases to a JSON document database.

This first resource is a video that takes you through the basics and gets you started on your journey of moving from tables to documents.

We start with exporting data from a relational database, using a CSV format, and use a tool called cbimport to import the data into Couchbase. We’ll then instruct you on how to transform and structure that data on the document database side and finalize our data using the SQL++ query language. With SQL++, we can move data from a staging point to a final data bucket ready for use. This video is chock full of real code examples allowing you to follow along and try it yourself.

Here is an article on the same topic if you prefer scanning a blog article over watching the entire video.

You can also check out the following JSON data video: Model Your Relational Database Data as NoSQL Document Data, which contains additional insights and walkthroughs. It will help you think about JSON, including how to model existing relational data to document data.

Another resource to help you understand the differences between relational data and how Couchbase works comes from a thirty-plus-year veteran of the database community.

Our blogs are another great resource, so I have hand-picked several that deal specifically with moving from relational systems to Couchbase. This information is also highly applicable to moving from any relational database like SQL Server to a JSON document database like Couchbase.

Migrating from MongoDB to Couchbase

The most common document database we experience our customers switching from is Mongo. Some come for the scalability, others for the query language. If you find yourself needing to get data from Mongo into Couchbase, these resources are for you!

A few blog posts in our Couchbase blog do a great job of covering this topic. The first two links are articles that are new and contain up to date information on making the switch from MongoDB to Couchbase.

Next Steps and Resources

Here are some final resources that may pique your interest in JSON data modeling techniques. Because learning as you build real-world projects is critical, the following link will help you understand how to tackle registration, login, and authentication in NoSQL.

Want a walkthrough on planning a simple REST API? The resource below implements the ideas discussed above using Node and Express JS. It contains a GitHub repository of the source code, postman collections, and environment variables to aid in easily getting the project up and running.

And we can’t mention the two articles above without mentioning the frontend client explicitly built for the REST API from the repository above using Angular 11. Also, a resource that was updated with a GitHub repository of the finished code.

Couchbase Training on Data Modeling

Let’s introduce you to our Couchbase Data Modeling resources from Couchbase Academy. With this course, you will get your hands dirty with Couchbase, taking into consideration data modeling and tuning queries for use with the SQL++ query language.

This Couchbase documentation has a few really good pages that deal with data modeling and entity relationships in document data. The links below were part of the Couchbase 5x versions but contain valuable information still.

Embedded versus referenced documents

Embedded versus referenced documents

In the current version of Couchbase Server, we also have a page that is evolved and updated with the most recent versions of our database in mind:

External Data Modeling Resources

Couchbase is one of the best places on the web to learn about data modeling for NoSQL, document databases, or key-value datastores. But it’s good to venture outside because there are many more great resources for you out there. There is a wonderful course on Pluralsight that walks you through creating data models in JSON and addresses the difference between modeling relational vs. document data.

NoSQL database and key-value stores or document databases

In this slide from the Pluralsight video, Kishan Iyer talks about one of the many different database technologies he covers in his course

In this slide from the Pluralsight video, Kishan Iyer talks about one of the many different database technologies he covers in his course

Pluralsight is an amazing resource for application developers and also has many Couchbase related courses as well.

This article from the Highly Scalable Blog about NoSQL Data Modeling Techniques is informative, funny, and loaded with more external resources.

We hope that the resources provided in this article go a long way in helping you hit the ground running on your path to learning about document databases and Couchbase. We have tried building a learning resource you can bookmark and revisit. If you feel we have missed any essential resources, comment, and mention those resources, as we are always looking to add to this guide and ensure everyone benefits from having a single point of access for JSON data modeling resources.


Posted by Matthew Groves

Matthew D. Groves is a guy who loves to code. It doesn't matter if it's C#, jQuery, or PHP: he'll submit pull requests for anything. He has been coding professionally ever since he wrote a QuickBASIC point-of-sale app for his parent's pizza shop back in the 90s. He currently works as a Senior Product Marketing Manager for Couchbase. His free time is spent with his family, watching the Reds, and getting involved in the developer community. He is the author of AOP in .NET, Pro Microservices in .NET, a Pluralsight author, and a Microsoft MVP.

One Comment

  1. […] You can find the full and original article here: https://www.couchbase.com/a-json-data-modeling-guide/ […]

Leave a reply