Tag Archives: nosql

CouchDB, Validation functions

The last CouchDB post was about Design Documents, and we described how it’s possible to create views directly on it. Now this post is about another part of Design Documents and it’s fundamental on a CouchDB project context.

We already know that CouchDB is a schema free document oriented database, this means that there are no constraints when we create / update documents ! now let’s imagine that every user of the CouchDB application can create any kind of document with what he wants .. we need to deal with data consistency and for that we’ll need Validation Functions !

The Validation Function definition :

It’s important to know that Validation functions are optional, if you don’t define them there will be no check. Also validation functions are stored on the Design Document under the “validate_doc_update” field.

  function(newDoc, oldDoc, userCtx) {}
  • newDoc is for the incoming document.
  • oldDoc is the current saved document.
  • userCtx the user object doing the request.

Now let’s try to add a validation function to a design document, what you need is to open Futon then :

choose a database > view “Design documents” > Choose a design

Now edit the document and add this at the end of document defintion :

"validate_doc_update": "function(newDoc, oldDoc, userCtx) {
  throw({forbidden : 'you are not allowed !'
});}"

You will get something like this (you’ll need to save the document) :

couchDb validation function

Okey now let’s try to create an new document using Curl :

curl -X PUT http://127.0.0.1:5984/contacts/contactValidation -d '{"name" : "contact validation"}'
//return
{"error":"forbidden","reason":"you are not allowed !"}

Et voilà ! the validation function has thrown an exception and no more document creation / update is possible ! now lets tune it a little bit. We are using a contact database so we’ll not permit creation of document without name, and phone fields :

function(newDoc, oldDoc, userCtx) {
   function require(field){
      var message = field + ' is required';
      if(!newDoc[field]){
         throw({'forbidden':message})
      }
   }
   require('name');
   require('phone')}

Okey let’s try again with curl :

curl -X PUT http://127.0.0.1:5984/contacts/contactValidation -d '{"name" : "contact validation"}'
{"error":"forbidden","reason":"phone is required"}

And now we add required fields :

curl -X PUT http://127.0.0.1:5984/contacts/contactValidation -d '{"name" : "contact validation", "phone":"123-1111"}'
{"ok":true,"id":"contactValidation","rev":"1-8330cb19d688702b4c24e3ae468f31f2"}

And it’s working ! as you can see it’s simple to check document consistency with simple javascript tests ! Hope you like this post.

CouchDb, Creating views

The first couchDb tutorial that i’ve wrote was about simple operations like creating, updating or deleting documents, in this post i will explain how to create views, and how to call them ;

Creating views

The simplest way to create views is to use “Futon” (the phpmyadmin like for couchDb) accessible via :

http://localhost:5984/_utils/

And if everything is ok we should have something like this :

Then choose database where to create View, then on the select box in front of ‘View‘ select ‘Temporary view‘ :

When you click run button :

the last time we have created database called ‘contacts‘ with documents having this structure :

{
   "_id": "johnsmith",
   "_rev": "3-94052866ba060f57508fde265a243b47",
   "firstName": "John",
   "lastName": "Smith",
   "email": [
       "johnsmith@example.com"
   ],
   "phone": "(555) 555-5555"
}

The default function to show database content is :

function(doc) {
  emit(null, doc);
}

And when you hit run it will display all entries from the database “contact“, know let’s try to get contacts with a specific criteria, for example : “all contacts having a phone number” :

function(doc) {
  if(doc.phone){
	emit(doc._id, doc.phone);
  }
}

As result :

Saving the temporary view

Okey now that we are satisfied of the result let’s save the temporary view a permanent one :

  1. Click “Save As” button
  2. Set a design Name
  3. Set a view Name

That’s all ! our view will be accessible from the “View” Select Box :

Getting view result with curl

To query the server will use curl :

curl -X GET http://127.0.0.1:5984/contacts/_design/contacts/_view/phones

Result :

{"total_rows":1,"offset":0,"rows":[
  {"id":"johnsmith","key":"johnsmith","value":"(555) 555-5555"}
]}

Some explanations about params passed to curl :
– First argument “contact” is database name
– Second argument “_design” with value “contacts” is the design name that we have set when we saved the view
– Third argument “_view” with value “phone” is simply the view name

We can also pass other params at the end to tell the server how many entries to return, or to order them :

curl -X GET http://127.0.0.1:5984/contacts/_design/contacts/_view/phones?limit=11&descending=true

Hope this was helpful to understand how to create simple views with couchDb.

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.