What is filtered replication in CouchDB and how do you implement it?

Filtered replication allows you to replicate only a subset of documents from a source database, rather than copying every document. This reduces bandwidth, storage on the target, and replication lag. There are two ways to filter: using a filter function (server-side JavaScript) or using a Mango selector in the replication document (CouchDB 2.x+).

Option 1 — Filter function in a design document:

// In _design/replication_filters:
{
  "filters": {
    "by_type": "function(doc, req) { return doc.type === req.query.type; }"
  }
}

# Replicate only order documents
curl -X POST http://admin:pass@localhost:5984/_replicator \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "orders-only",
    "source": "http://localhost:5984/mydb",
    "target": "http://replica:5984/orders",
    "continuous": true,
    "filter": "replication_filters/by_type",
    "query_params": { "type": "order" }
  }'

Option 2 — Mango selector (preferred in 2.x+, avoids a round-trip through the JavaScript query server):

curl -X POST http://admin:pass@localhost:5984/_replicator \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "active-orders",
    "source": "http://localhost:5984/mydb",
    "target": "http://replica:5984/active_orders",
    "continuous": true,
    "selector": { "type": "order", "status": { "$in": ["pending","processing"] } }
  }'

The Mango selector approach is more efficient because the filter is evaluated against the changes feed using an in-process Erlang evaluator rather than spawning a JavaScript OS process for each document. It is the recommended approach for all new replication setups.