December 1, 2014

Intro to Enterprise Cloud Storage: How to Set Up a Cloudant Database

Enterprise cloud storage has come a long way in the past decade as storage developers have worked out a lot of the kinks that plagued the technology early on. Companies are embracing it as a way to store data without having to manage their own storage servers, while still enjoying the benefits of replication, scalability, and stability.

In this series of articles I'll take you through some different cloud storage options. These are commercial companies, although some of them use open source software. In today's article I look at Cloudant, which uses a modified form of CouchDB. Originally they forked CouchDB and built a scalable and fault-tolerant version called BigCloud; since then, their updates have been merged back into the main CouchDB code. This means in theory you could run your own services similar to Cloudant's offerings; however, there are some recent features of the system that have not yet made it back into CouchDB.

Cloudant, which was founded in 2008, was sold to IBM in February of 2014. As such, we're actually talking about an IBM product here. As for pricing, there are several levels based on your needs. For starting out, though, you can use Cloudant for free, as long as you stay under a monthly charge of $5. You can find the details at

Getting Started

You can configure and access your data either programmatically or through Cloudant's web interface. In either case, however, you'll have to understand JavaScript Object Notation (JSON), as that's the format your data is stored in. You'll need to understand some basics about CouchDB.

The first thing you do, then, is create an account at Then you can log in, which takes you to your dashboard. From there, you can create your first database. Here's a capture of my dashboard; I already have created several databases:

cloudant dashboard

Creating a Database

In the CouchDB (and thus, Cloudant) world, a database is a collection of documents. Documents, in turn, are JSON objects. To create a database, simply click the Add New Database link that's towards the upper-right corner. Enter the name of the database, and then click Create.

 cloudant create database

Adding Documents to a Database

After you create the database, you will be taken to the database's document view in the dashboard, as shown here:

cloudant dbview

The top of the view shows you the name of the current database you're working on. The right-hand pane shows you your documents. Right now there aren't any, so let's go ahead and create one. In the middle pane, to the right of All Documents is a little plus symbol. Click it; this will reveal a dropdown, and in that dropdown click New Doc.

cloudant adddoc

This opens the document editor. The document editor is a code editor within which you can edit your JSON document. Your document must conform to the JSON specification. One way to think of a JSON object is that it's a JavaScript object without any functions or variables or expressions that need to be evaluated; in other words, only literals. The member names and strings must be surrounded in double quotes.

You'll notice that the document editor starts out with a JSON document containing a single member called _id, which is a string containing a UUID. This is _id is required for every CouchDB document, and it must be unique within the database. If you're familiar with SQL databases, you can think of it as essentially a primary key. Every document must have one. The web-based editor here creates an _id for you.

Now you can go ahead and add members to your JSON object. Here's one example; the _id you're presented with will be different:

"_id": "d795ad9029793255261aba9fe045ac4f",
"first_name": "George",
"last_name": "Washington",
"lived": {
"born": 1732,
"died": 1799
"president": 1

After entering or pasting this in, click the green Save button that's at the top. You'll see a message at the top of the window that the document was saved. Or, if you enter code that isn't valid JSON, you'll see an error message instead. The editor includes some syntax checking and will notify you with the location of an error with a little x to the left of the line. It does so as you're typing, so you should be able to catch any errors before you even try saving the document.

Then click Back to return to your database view. Now you'll see your new document listed in the right-hand pane.


Creating databases and documents is easy in Cloudant. You can also create views for searching and mapping your data, as well as construct queries (using a special query syntax) and full-text searches (using Lucene). In the next article we will try all three out. We'll use the dashboard as well as try it programmatically. See you then!

Click Here!