Ottoman is an Object Data Modeler (ODM) for Couchbase’s Node.js SDK providing JSON schema and validation for NoSQL.

Why Use an ODM for Couchbase

With Ottoman, you declare schema in your code. Although Couchbase has no schema enforcement for your documents, most applications need some level of schema even in NoSQL. We will explore how to achieve schema and validation in NoSQL using Ottoman and Couchbase.

It’s important to validate that documents meet certain requirements before persisting. Although Ottoman creates an abstraction over the Couchbase SDK, the benefits outweigh the drawbacks. A developer creates a lot of logic around creating and updating documents, writing pre/post lifecycle, working with data structures, and validation.

NoSQL Database and Schema Design

An ODM serves a similar role in NoSQL as it does in a relational database, but with additional benefits. Couchbase doesn’t enforce validation as it is schema-flexible. Ottoman can perform certain checks are being made as your applications persist data. We can warn and error against unwanted data types and formats for individual fields by defining schema and models for various document types.

Your server application code is where a great place to apply business logic and validation. Ottoman’s goal is to provide a better development experience along with giving you control over schema and validation while using Couchbase with Node. We want to give developers a reliable tool to build systems that are easy to design, maintain, and scale.

Object Data Mapping in Node.js with Ottoman for Couchbase

Couchbase is a NoSQL Database

Couchbase Server is a schema-less document database, categorized as a NoSQL datastore, it’s not the best description as Couchbase uses a variant of SQL for querying called N1QL. Just because a schema is not strictly enforced in NoSQL databases like Couchbase does not mean you should not enforce it.

With Couchbase, you get the benefits of enterprise-level scaling, clustered nodes, and the ability to store and retrieve data in a JSON format.

If you are familiar with Mongoose, an ODM for MongoDB, you will feel pretty comfortable with Ottoman as they have many overlapping features because they both are made for NodeJS and used to model and persist data to a JSON document-oriented key-value database.

Document vs Relational Database

As we explore we will explore Couchbase and NoSQL Database and Schema Design, we will first look at how a document data structure differs from a relational database design, in the example below, you will see a side-by-side comparison of data that represents a Hotel.

On the left, we have a document that can store phone numbers in an array allowing us to store multiple phone numbers for a single hotel. To do this in a relational database you would most certainly need a new table and to maintain a relationship between the two using primary keys.

NoSQL Documents vs. Relational Tables in SQL

For more info on document modeling, check out the resources I have put together in a blog post: JSON Data Modeling Guide

In Ottoman, we have many constructs to help define schema and models at the application level. Let’s go over some of the most important terms you need to know in Ottoman.


As seen in pink in the image above, document properties with the name type in Couchbase are near equivalent to tables in a relational database. They can help to group different types of JSON documents together for indexing purposes. When using Secondary Indexes in Couchbase, we are able to index on any key in the documents. If only 100 of 10,000 documents in your database use a type of ‘hotel’ and you normally want to search for hotels based on city or state, then you might want to build a Composite Secondary Index that only needs to search through those hundred documents where city or state equal a certain value. This is much more efficient than using, for instance, a Primary Index.

Learn more about indexing in Couchbase!


Similar to types in Couchbase 6.x (latest Couchbase major version at the time of writing) and not shown in the illustration above, collections will be favored in Couchbase 7 (already in beta). In the case you were to use collections, you would simply not have a ‘type’ property on each document and instead have the document assigned to a ‘hotel’ collection.


Comparable to rows of data in a relational database. Traditional RDBMS systems will reference related documents from other tables as seen in the illustration above. You can also do this with a JSON document, however; it is suggested to include that information as an embedded document when possible, as we see with the hotel document’s phone number property which is an array of phone numbers. Albeit a very simple example of this, think if you had an address property that itself was another JSON object with many properties, you may think this needs to be given its own document, but nesting that information in the parent document in most cases is fine.


Also known as attributes, are similar to columns in a relational database and with Ottoman, you can create field-level requirements as part of your schema.


While Couchbase is schema-less or schema-flexible, we can still enforce structure at the application level for our documents.


A constructor method that takes a schema and creates an instance of a document equivalent to a single record in a relational database. This document instance can be constructed and then persisted to Couchbase by Ottoman using the save() method.

Getting Started

Let’s get started creating a demo application that we can use to get familiar with Ottoman as an object document mapper.

Couchbase Installation

Before we get started, let’s set up Couchbase.

You can choose from one of the following options (we are using option #1 for this article):

  1. Install Couchbase Server using Docker
  2. Download Couchbase specific for your OS from the Couchbase Website

Let’s navigate through some of the basics of Ottoman by implementing a model that represents data for a simplified airline example keeping in tradition with Couchbase’s Travel-Sample dataset.

I am using Visual Studio Code, NodeJS v12.14, and NPM 6.14.8, so you will need to have Node.js installed on your machine. next, we will create a blank project and get started writing some code.

Initializing our Project with NPM

Create a directory, initialize our project, install Ottoman.js and open in VS Code

Open the terminal in your editor of choice, I have added a command at the end that will open in VS Code.

Connection to Couchbase with Ottoman

We will start working out of the file ./createAirline.js under the project root and add the following (based on the default configuration):

Together this imports the ottoman package and specifies the default collection (Couchbase Server 6.x style)

Ottoman Schema and Models

Models are fancy constructors compiled from Schema definitions. An instance of a model is called a document. Models in Ottoman help you to easily create, read, update, and delete documents in your Couchbase database.

Creating an Ottoman model comprises of a few things:

Defining a Document Schema

A schema defines document properties through an object where the key name corresponds to the property name in the collection.

Here we define three properties (callsign, country, name) within our schema, all of type String. By specifying a type for each of our model properties,  maps to an internal validator that will be triggered when the model is saved to the database and fail if the data type of the value is not of type String.

The following Schema Types are permitted:

Defining a Document Model

We need to call the model constructor on the ottoman instance and pass it the name of the collection and a reference to the schema definition.

When you call the model() function it creates a copy of the schema and compiles the model for you.

Let’s also give the airlineSchema a phone number property. We can add a validation function that will ensure that the value is a valid phone number. Replace the airlineSchema section with these three blocks of code:

In the example above, I show you how to create a custom validator, we just happen to be using a regular expression as the check-in our validator, just understand that you could have any logic inside one of these validators and in a moment I will show you a nice trick to reduce our code down considering we are using regular expression for our matching of the phone numbers.

Defining Validators

Validators registered with Ottoman (as we have done here with the ottoman.addValidators() method) will be called once for every value our document’s property has in the array. If the property did not have an array and instead just a single String value, the validator would only be run once. For this reason, I print out the problematic phone number if the validation fails.

There is however an easier way to validate any document properties value so long as the check you are performing uses a regular expression. The ValidatorOption can take a regexp and message as an argument, so we can reduce our code down to:

As you can see, we can do everything we were doing before inline when creating a new Schema. But don’t let this keep you from understanding how to create a custom validator, sometimes we need additional logic and that is why the first example is still something worth knowing.

Basic Document Operations in NoSQL

Most of the basic operations are covered in our Ottoman V2 documentation, we will cover some of that here, but feel free to dive into our Ottoman V2 (alpha) docs and let us know if there is something that you cannot find or don’t understand.

Create Documents

Considering the code that we already went over above that creates a schema, model, and validators. Saving a model and persisting it to the database is quite easy. Let’s create a new Airline model using our Schema and then save/persist it to the database.

You may be wondering why we don’t just call the saveDocument() function on its own. Instead, we call it after the ottoman.start() is finished. The start method is a shortcut to run ensureCollections and ensureIndexes. All you have to know for now is that this method makes sure that the proper Ottoman-related indexes have been created on Couchbase and this is important to ensure we can run things like the find() method and use tools like the QueryBuilder which we will get to at the end of the article.

At this point, if you were to run all of the code we have written using Node, our document would be saved to the database:

The result from this operation:

The following fields are returned:

  1. Callsign, country, and name fields are all String, the most basic value we could have in a document.
  2. The id field is auto-generated by Couchbase and is a unique key. The ID value is what you will use in any case to find a document with Ottoman in methods like findByID or removeByID
  3. The phone field is represented by an array and contains valid phone numbers.
  4. The _type field can help us to organize our documents like a table does in a relational database, in Couchbase 7, we can use collections and scopes.
Validation Errors

If we enter an invalid phone number and run node createAirline.js this file again, we would get an error message:

TIP: You can define your connection, schema, and models in separate files, export, and use them in other files. Create a new file named airline-schema-model.js and move our schema and model definition to it:

Now we can create a few new files, findAirline.js, updateAirline.js, and removeAirline.js and populate each file with the following:

This will help us to separate some of our code so we are not repeating it in each file and as we go over each of the CRUD operations we can just add some code to each file and our schema and model will already be imported.

Find Documents

Let’s try to retrieve the record we saved to the database earlier. The model class exposes several static and instance methods to perform operations on the database. We will now try to find the record that we created previously using the find method and pass the callsign as the search term. Let’s create a new file named findAirline.js and we can add the following code:

Find document result:

Update Documents

Let’s modify the record above by finding it using the callsign, which we can assume that callsign will be a unique field in our data, then we can update the document all in a single operation.

Find document and update result:

Remove Documents

Ottoman has several methods that deal with removing documents: remove, removeById and removeMany. Considering the many examples we have had so far, each of these should be very easy to understand how to use, so we will just provide a simple example here to show how to remove a document that we have already found using the find() method.

Remove document result is a simple cas value, used to track changes in Couchbase documents.


We have already seen our middleware in action, our validator that we initially created can take advantage of middleware using functions that run at specific stages of a pipeline passing control during the execution of asynchronous functions.

Available Hooks

  • validate
  • save
  • update
  • remove

Example of Middleware (a.k.a. pre and post hooks)

Let’s try an example by simply generating a log in the console before and after the creation (save) of a document, I’m going to create a new file called createWithHooks.js and most of the code will look familiar except I have added pre and post hooks that will just report to us the document name pre-save and document id post-save:

Save document result:

We got our messages before and after the save. With validation, you can ensure certain document property values meet your criteria. Tapping into the lifecycle when the document is saved, updated, and removed also helped us gain a handle on Ottoman middleware! 

Query Building

Ottoman has a very rich API that handles many complex operations supported by Couchbase and N1QL. Our query builder behind the scenes creates your N1QL statements for you. When using Query Builder you have three options of which mode to use. 

  1. Using parameters
  2. Access Functions
  3. or using Parameters and Access Functions

In the next three examples, I’ll do the same thing using each of the three different QueryBuilder modes (params, access functions, and mixed-mode). Each example will:

  1. Select name and country from Airline
  2. Where the country value is “United States”
  3. And LIMIT our results to 10

Let’s first create a new file named: findWithQueryBuilder.js, and add the following code:

This file has a comment in the middle that says: “Replace with QueryBuilder Example”. We can just copy any of the following examples in this section into that area of the file.


Access Functions

Mixed Mode

Once you have created a generateQuery() function using one of the mixed modes above, you would then need to asynchronously call generateQuery and executeQuery and the code for that like I said will work with many flavors of the above code:

A result from any of the three modes above:



We’ve taken a guided tour through Ottoman gaining an understanding of many concepts. Schema, models, middleware, plugins, hooks, and query building.

We explored how to connect to Couchbase in Ottoman. Defined schema and models. Touched on various fundamentals in NoSQL database schema and design. Finally, we walked through some of the most useful CRUD operations. All an effort to get you up to speed creating, reading, updating, and deleting documents in Couchbase via Ottoman.

Give Feedback and Contribute

I hope that this article has demystified why and how to use Ottoman and ODM for Couchbase. As shown you can use Ottoman for NoSQL database schema design, validation, and reduction of boiler-plate. Writing CRUD operations are made simple and aid in rapid development.

If you have any questions about Ottoman, want to help contribute to this open-source project, or would just like to say hello, my name is Eric Bishard and I am the Developer Advocate here at Couchbase focusing on the Node.js and JavaScript developer experience, my DM’s are always open at Twitter/@httpJunkie.


Posted by Eric Bishard

International speaker, blogging and advocating for the JavaScript, React, GraphQL and NoSQL community working as a Senior Developer Advocate for Couchbase.

Leave a reply