segfault.in

Apache CouchDB is a document-oriented database that can be queried and indexed in a MapReduce fashion using JavaScript. CouchDB also offers incremental replication with bi-directional conflict detection and resolution.

CouchDB provides a RESTful JSON API than can be accessed from any environment that allows HTTP requests. There are myriad third-party client libraries that make this even easier from your programming language of choice. CouchDB’s built in Web administration console speaks directly to the database using HTTP requests issued from your browser.

CouchDB is written in Erlang, a robust functional programming language ideal for building concurrent distributed systems. Erlang allows for a flexible design that is easily scalable and readily extensible.

See the introduction and the technical overview for more information.

Getting Started

The couchdb.client.Server represents a CouchDB server. New databases can be created using the create method:

from couchdb.client import Server
 
server = Server('http://localhost:5984')
print server
try:
        db = server.create('emails')
except Exception:
        db = server['emails']
 
print db

Output:

<database 'emails'>

This class behaves like a dictionary of databases. For example, to get a list of database names on the server, you can simply iterate over the server object.

for db in server:
    print db

The out put will be something like

test
segfault
emails

Creating a Document

To define a document mapping, you declare a Python class inherited from Document, and add any number of Field attributes:

from couchdb.client import Server, Document
from couchdb.mapping import TextField, DateTimeField, ListField

Now you create subclass of Document and fill in the values.

class Email(Document):
  frm  = TextField()
  to = ListField(TextField())
  sub = TextField()
  added = DateTimeField(default=datetime.now())
 
eml = Email()
eml['frm'] = "vinod@example.com"
eml['to'] = "user@domain.com"
eml['sub'] = "test"

To update a document, simply set the attributes, and then call the save() method:

doc_id, doc_rev = db.save(eml)
print doc_id, doc_rev

Output:

8be7ef2e5d711f11e859972ca9d38a52 455397369

Retrieving documents

for docid in db:
  eml = db.get(docid)
  print eml['frm'], eml['to'], eml['sub']

Output:

vinod@example.com user@domain.com test

Working With Views

Views are the primary tool used for querying and reporting on CouchDB documents. There are two different kinds of views: permanent and temporary views.

Temporary Views

The views you don’t want to save in the CouchDB database. NOTE: Temporary views are only good during development. Final code should not rely on them as they are very expensive to compute each time they get called and they get increasingly slower the more data you have in a database.

code = '''function(doc) { if(doc.frm == "vinod@example.com") emit(doc.frm, null); }'''
results = db.query(code)
 
for res in results:
   print res.key

Permenant Views

Permanent views are stored inside special documents called design documents, and can be accessed via an HTTP GET request to the URI /{dbname}/{docid}/{viewname}, where {docid} has the prefix _design/ so that CouchDB recognizes the document as a design document, and {viewname} has the prefix _view/ so that CouchDB recognizes it as a view.

You use ViewDefinition class to create a permanent view in the database.

from couchdb.design import ViewDefinition
 
rpt_view = ViewDefinition('reports', 'fromemail', '''function(doc) { if(doc.frm == "vinod@example.com") emit(doc.frm, null); }''')
rpt_view.sync(db)

You can see our view in the drop down list.

Query permanent views

for res in db.view("_design/reports/_view/fromemail"):
        print res.id, res.key

Output

8be7ef2e5d711f11e859972ca9d38a52 vinod@example.com

Installing Python-CouchDB

If you are a Debian/Ubuntu user install couchdb and python-couchdb via apt:

sudo aptitude install couchdb python-couchdb

Or you can download from python-couchdb project home.