Tearing The Sofa ApartCouchDB & CouchApp from a Beginner’s Perspective

Image: Cat vs The Internet, The Oatmeal http:// theoatmeal.com/

It All Started When…

Pain point: Part III on CouchApps

The example Sofa in the book != the latest code over GitHub

(#*@#^&^+ FAIL!!!)

(* To be fair, it’s still a great introductory book and the other sections are still relevant)

CouchDB in a Nutshell

Core philosophy: Relax~

It’s a distributed database

Data represented as documents – as flexible as the paper counterpart

http://guide.couchdb.org/

Awesome Distributed DB Features!

Replication

Conflict management

Load balancing

Clusteringhttp://guide.couchdb.org/

All You Need is HTTP

It’s all HTTP REST-like API!

No binaries needed! :D

Basic Operations in a Glance

Create a database

$ curl -X PUT http://localhost:5984/sofa

Double e: List all databases

$ curl -X GET http://localhost:5984/_all_dbs

Add a document

$ curl -X PUT http://localhost:5984/sofa/[id] -d ‘{“title”: “Hello world”, …}’

… etc.

Easier Admin: Futon

“OK, that’s neat…”

“… how am I gonna query stuff?”

http://www.flickr.com/photos/yiie/4865201576/

Sofa: Blogging Engine Use Cases

Author can write posts and edit their posts

Commenters can write comments

Core pages

Index page: Recent post listing

Post page: Individual post with comments

Two feeds: Recent post & recent comments

Design Document & Queries

Design documents is special!

Special power: Can contain application code that CouchDB can run!

We can write and save MapReduce view in it

We’ll use the views to do queries later

A Simple Design Document

{“_id”: “_design/sofa”, // Determines the URL“language”: “javascript”,“views”: { … }, // Define your MapReduce views here“validate_doc_update”: “function(…) {}”// Validation function on document inserts/update

}

MapReduce for Dummies

Map: applies a function to every single row and emits key-value data

Reduce: (optional) Take data spewed from map and reduce it a aggregated solution (e.g. sum, count, standard deviation)

© Nadir Muzaffar, hp://www.cs.berkeley.edu/~ballard/cs267.sp11/hw0/results/htmls/Muzaffar.html

used without permission ^-^||

Example: Sofa Blog Post Structure

{“type”: “post”,“author”: “John Doe”,“created_at”: “2011-03-11T11:20:52.22”,“title”: “Blog Post Title”,“body”: “…”,“tags”: [“dummy”, “testing”, “webcamp”]

}

MapReduce Views in Sofa

“recent-posts”: {“map”: “function(doc) { if (doc.type == 'post') { emit(new Date(doc.created_at), doc); } }”

}

Recent posts query

MapReduce Views in Sofa

“post-page”: {“map”: “function(doc) {if (doc.type == 'post') {

emit([doc._id], doc); } else if (doc.type == 'comment') { emit([doc.post_id, doc.created_at], doc); }}”

}

Post page query with comments

… will talk about how to filter an individual post later

MapReduce Views in Sofa

“tags”: {“map”: “function(doc) { if (doc.type == 'post' && doc.tags && doc.tags.length) { for (var idx in doc.tags) { if (doc.tags[idx]) { emit([doc.tags[idx].toLowerCase(), doc.created_at], doc); } } }}”,

“reduce”: “_count” // CouchDB’s built-in reduce function}

List and count tags

Querying Views$ curl -X GET http://localhost:5984/sofa/_design/sofa/_view/recent-posts

{“total_rows”: 4,“offset”: 0,“rows”: [ {“title”: “Hello world”, …}, … ]

}

CouDB response

Filtering Data$ curl -X GET http://localhost:5984/sofa/_design/sofa/_view/post-page?startkey=[“Huh”]&endkey=[“Huh”, {}]

{“total_rows”: 5,“offset”: 2,“rows”: [ {“title”: “Huh”, …} ]

}

CouDB response

Other query parameters

CouDB responseCouDB response

key, limit, descending, skip, group, reduce, include_docs…

“Flexible data is cool, but I need some structure”

Documents are free-form in CouchDB, flexibility == WIN!

Define validate_doc_update function if you need validation, e.g.

Check for mandatory fields,

ACL control,

Field format checking, etc.

Ask to show code

(in case I’d forgotten :)

Why stop here?

“OMG! I can write web apps on CouchDB without frameworks!”

http://www.flickr.com/photos/7386864@N08/3802078924

CouchApp: The Easier Way

Writing design documents is made easy by CouchApp

Follow the file structure and CouchApp will make the design document for you

Design Document Structure

{“_id”: “_design/sofa”,“language”: “javascript”,“views”: { … },“validate_doc_update”: “function(…) {}”,

“show”: { … }, // Formats a single document“lists”: { … }, // Formats a list of documents

“_attachment”: { … }, // CSS, JS, images attached here“templates”: { … }, // Templates stored here“vendor”: { … } // Libraries and scripts

}

Corresponds to CouchApp

project directory structure

Accessing Show and List Pages

Show (single document)hp://localhost:5984/sofa/_design/sofa/_show/edit/[id]

ID is optional; blank ID is good for pages to create new documents

List (list of documents)hp://localhost:5984/sofa/_design/sofa/_list/index/[view-name]?[query-parameters]

(* I know the default URL’s ugly :( – fix this with URL rewrite module + virtual host seings)

Batteries Provided

Baeries (i.e. libraries) provided with CouchApp projects:

jquery.cou.app.js: To interact with CouchDB, query, insert, update…

mustae.js: Template engine

Evently: Writing interactive, event-based widgets without spaghei jery code

Utilities: Atom feed generator, MD5 checksum, path builder, validation functions…

Quick Demo of the Sofa Code

Add/Editing post

Listing recent posts

How to serve HTML and Atom feed?

Why showing an individual post is in “lists” but not “show”?

Ask to show code(in case I’d forgotten :)

Learning More

CouDB Wikihp://wiki.apache.org/couchdb/FrontPage

/usr/local/share/couchdb/server/main.js (Seriously!)

CouDB: e Definite Guidehp://guide.couchdb.org/index.html

CouDB HTTP API Referencehp://docs.couchone.com/couchdb-api/

Contact Me! :)

@felixleong

hp://felixleong.com/

Clone my annotated Sofa CouApp!hps://github.com/felixleong/sofa