I just want to document what is needed to get a filtered replication between two databases inside CouchDB 2.2.0 up and running. I spend quite some time figuring it out and couldn’t find any useful resource that sums it up.
I used capital cased names where specific names need to be placed - if there is the same placeholder it needs to be the same name.
The goal is to replicate SOURCE_DATABASE to TARGET_DATABASE while applying a filter function that is named DESIGNDOCUMENT/NAME. The filter function in the example checks if the attribute _id starts with abc.
First we create a document that describes the filter. This document is a design document and needs to be placed in the source database under /SOURCE_DATABASE/_design/DESIGNDOCUMENT:
{
"_id": "_design/DESIGNDOCUMENT",
"filters": {
"NAME": "function(doc, req) { if (doc._id.substr(0, 3) === 'abc') { return true; } return false; }"
}
}
To actually test the filter I used a query against the /_changes endpoint of the database:
$ curl "http://DOMAIN:5984/SOURCE_DATABASE/_changes?filter=DESIGNDOCUMENT%2FNAME&feed=normal&style=all_docs&since=0&timeout=10000"
This shows the output and potential errors in the JavaScript code of the filter.
For the actual replication you need to create following documents in the _replicator database for the one time replication of existing documents:
{
"_id": "ID",
"source": "http://DOMAIN:5984/SOURCE_DATABASE",
"target": "http://DOMAIN:5984/TARGET_DATABASE",
"filter": "DESIGNDOCUMENT/NAME"
}
And I created a continuous replication document as well:
{
"_id": "ID-continuous",
"source": "http://DOMAIN:5984/SOURCE_DATABASE",
"target": "http://DOMAIN:5984/TARGET_DATABASE",
"filter": "DESIGNDOCUMENT/NAME",
"continuous": true
}
Following documentation pages helped me to understand how the replication works in general:
Quite interesting in this regard could also be the blog post “Filtered replication: from Couch to Pouch and back at the PouchDB blog.