CouchDB, nosql tutorial

CouchDB is a document orientated that can be queried and indexed in a MapReduce fashion using JavaScript. It provides a RESTful JSON API than can be accessed from any environment that allows HTTP requests.

And unlike SQL databases CouchDb is schema free, so there are no restrictions for data creation, for example on MySQL to create a person entity we use table called person with sometimes NULL values :

id
Name
phone
adress
123 Jane 11-11111 Adress
124 John NULL NULL

But on CouchDB document are created with only needed attributes so if we want to have the defined on couchDB we’ll have :

{
  _id : '123',
  name : 'John'
}

and

{
  _id : '124',
  name : 'Jane',
  adress : 'Adress',
  phone : '111-11111'
}

Installation

We will not discuss about CouchDB installation, but here you can find all you need for your Os :

http://wiki.apache.org/couchdb/Installation

I personally use couchdbx for intel macos.

Let’s start !

We will use curl to interact with couchDb server. In this tutorial we’ll try to  do basic commands like create database, insert documents, update and delete them.

Creating database “Documents”

curl -X PUT http://127.0.0.1:5984/documents

you will receive message like this : {“ok”:true} that means that creation was successful and now we have a new database called “documents“.
To get all created databases type :

curl -X GET http://127.0.0.1:5984/_all_dbs

A Json array will be returned with the list of created Databases.
Now let’s try to add documents

Creating documents :

Assuming that our documents will have a title, an author and a description :

curl -X PUT http://127.0.0.1:5984/documents/myDocument -d '{"title":"MyDocument", "autho":"hbensalem","description":"test document creation with couchDB"}'

Result :

{"ok":true,"id":"myDocument",
"rev":"1-1a9820b794c6746cf7d45cd9cd949d95"}

Now to get created document :

curl -X GET http://127.0.0.1:5984/documents/myDocument

Result :

{"_id":"myDocument","_rev":"1-1a9820b794c6746cf7d45cd9cd949d95",
"title":"MyDocument","autho":"hbensalem","description":"test document creation with couchDB"}

Updating Documents

We have forgot to add a creation date for myDocument so let’s update it :

curl -X PUT http://127.0.0.1:5984/documents/myDocument -d '{"_rev":"1-1a9820b794c6746cf7d45cd9cd949d95",
"creationDate":"2010-10-10"}'

Result :

{"ok":true,"id":"myDocument",
"rev":"2-68ef7cc631d81746f759f0f0294fd993"}

As you can see we have passed _rev to the service this is very important because couchDb create a revision for every document modification.

deleting documents

curl -X DELETE http://127.0.0.1:5984/documents/myDocument?rev=2-68ef7cc631d81746f759f0f0294fd993

Result :

{"ok":true,"id":"myDocument",
"rev":"3-7095fc86cdd65c9eb286d48acf7ccf00"}

As you can see deletion also creates a new revision !

That’s all for this tutorial, for the next one i will try to explain how to create views in couchDb.

2 thoughts on “CouchDB, nosql tutorial

  1. Thank you for taking the time to write this article. Very clear, concise, and pleasing to read! The only thing that had me confuzzled was the “Updating Documents”. After the update, myDocument no longer contained the original properties but just the new creationDate property. It turns out this was due to the append-only nature of CouchDB. The entire document has to be re-PUT-ed, with changes, unless the intention was to remove those original properties from the document.

    1. Thank you Scott and yes you are right ! if you need to add informations to an existent document you have to pass the old one or couch will consider it as a suppression.

Leave a Reply