What are CouchDB design documents and what do they contain?

Design documents are special CouchDB documents whose IDs begin with _design/. They live in the same database as regular documents but hold server-side JavaScript code that CouchDB's query server executes. Updating a design document invalidates and rebuilds all its associated indexes.

A design document can contain the following sections:

• views — MapReduce index definitions. Each view has a map function and an optional reduce function.
• indexes — Mango (json/text) index definitions for the _find endpoint.
• validate_doc_update — a JavaScript function that runs before any document is saved; throw an error to reject the write.
• filters — JavaScript functions used to filter which documents are replicated or streamed via the _changes feed.
• updates — update handler functions that let you perform server-side document transformations via a POST request.
• lists and shows — legacy functions (deprecated in 3.x) for server-side rendering of view results and individual documents as HTML/XML/text.

{
  "_id": "_design/orders",
  "views": {
    "by_status": {
      "map": "function(doc){ if(doc.type==='order') emit(doc.status, doc.total); }",
      "reduce": "_sum"
    }
  },
  "validate_doc_update": "function(newDoc, oldDoc, userCtx){ if(!newDoc.type) throw({forbidden:'type required'}); }",
  "filters": {
    "pending_only": "function(doc, req){ return doc.type==='order' && doc.status==='pending'; }"
  }
}

Design documents are versioned just like regular documents and replicate alongside data documents. Changing a design document in a replicated database will propagate the new index definitions to all replica nodes.