{"id":10947,"date":"2021-03-30T09:13:45","date_gmt":"2021-03-30T16:13:45","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=10947"},"modified":"2025-06-13T23:42:25","modified_gmt":"2025-06-14T06:42:25","slug":"introduction-to-ottoman-with-couchbase","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/introduction-to-ottoman-with-couchbase\/","title":{"rendered":"Introduction to Ottoman With Couchbase"},"content":{"rendered":"

Ottoman is an Object Data Modeler (ODM) for Couchbase’s Node.js SDK providing JSON schema and validation for NoSQL.<\/span><\/p>\n

Why Use an ODM for Couchbase<\/h2>\n

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. <\/span><\/p>\n

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.<\/span><\/p>\n

NoSQL Database and Schema Design<\/h3>\n

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.<\/p>\n

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.<\/span><\/p>\n

\"Object<\/a><\/p>\n

Couchbase is a NoSQL Database<\/span><\/h2>\n

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<\/a>. Just because a schema is not strictly enforced in NoSQL databases like Couchbase does not mean you should not enforce it.<\/span><\/p>\n

With Couchbase, you get the benefits of enterprise-level scaling, clustered nodes, and the ability to store and retrieve data in a JSON format.<\/span><\/p>\n

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.<\/span><\/p>\n

Document vs Relational <\/span>Database<\/span><\/h2>\n

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. <\/span><\/p>\n

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.<\/span><\/p>\n

\"NoSQL<\/a><\/span><\/p>\n

For more info on document modeling, check out the resources I have put together in a blog post: JSON Data Modeling Guide<\/a><\/span><\/p>\n

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.<\/span><\/p>\n

Types<\/span><\/h3>\n

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. <\/span><\/p>\n

Learn more about indexing in Couchbase<\/a>!<\/span><\/p>\n

Collections<\/span><\/h3>\n

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 (<\/span>already in beta<\/span><\/a>). In the case you were to use collections, you would simply not have a \u2018type\u2019<\/strong> property on each document and instead have the document assigned to a \u2018hotel\u2019<\/strong> collection.<\/span><\/p>\n

Documents<\/span><\/h3>\n

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\u2019s 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.<\/span><\/p>\n

Fields<\/span><\/h3>\n

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.<\/span><\/p>\n

Schema<\/span><\/h3>\n

While Couchbase is schema-less or schema-flexible, we can still enforce structure at the application level for our documents.<\/span><\/p>\n

Model<\/span><\/h3>\n

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()<\/code> method<\/a>.<\/span><\/p>\n

Getting Started<\/span><\/h2>\n

Let’s get started creating a demo application that we can use to get familiar with Ottoman as an object document mapper.<\/p>\n

Couchbase Installation<\/span><\/h3>\n

Before we get started, let\u2019s set up Couchbase. <\/span><\/p>\n

You can choose from <\/span>one of the following options<\/b> (we are using option #1 for this article):<\/span><\/p>\n

    \n
  1. Install Couchbase Server using Docker<\/span><\/a><\/li>\n
  2. Download Couchbase specific for your OS from the <\/span>Couchbase Website<\/span><\/a><\/li>\n<\/ol>\n

    Let\u2019s 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\u2019s Travel-Sample dataset.<\/span><\/p>\n

    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.<\/span><\/p>\n

    Initializing our Project with NPM<\/span><\/h3>\n

    Create a directory, initialize our project, install Ottoman.js and open in VS Code<\/span><\/p>\n

    mkdir intro-ottoman && cd $_ && npm init -y && npm i ottoman && touch createAirline.js && code .<\/pre>\n
    Open the terminal in your editor of choice, I have added a command at the end that will open in VS Code.<\/span><\/p>\n
    Connection to Couchbase with Ottoman<\/span><\/h3>\n
    We will start working out of the file .\/createAirline.js<\/code><\/span> under the project root and add the following (based on the default configuration):<\/span><\/p>\n
    const { Ottoman, model, Schema } = require('ottoman')\r\n\r\nconst ottoman = new Ottoman({collectionName: '_default'});\r\nottoman.connect({\r\n    connectionString: 'couchbase:\/\/localhost',\r\n    bucketName: 'travel',\r\n    username: 'Administrator',\r\n    password: 'password'\r\n});<\/pre>\n
    Together this imports the ottoman package and specifies the default collection (Couchbase Server 6.x style)<\/span><\/p>\n
    Ottoman Schema and Models<\/h3>\n
    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.<\/span><\/p>\n
    Creating an Ottoman model comprises of a few things:<\/span><\/p>\n
    Defining a Document Schema<\/span><\/h3>\n
    A schema defines document properties through an object where the key name corresponds to the property name in the collection.<\/span><\/p>\n
    const airlineSchema = new Schema({\r\n   callsign: String, \r\n   country: String, \r\n   name: String \r\n})<\/pre>\n
    Here we define three properties (callsign, country, name)<\/strong> within our schema, all of type <\/span>String.<\/b> By specifying a type for each of our model properties, \u00a0maps 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 <\/span>String<\/b>.<\/span><\/p>\n
    The following Schema Types are permitted:<\/span><\/p>\n