1.3.12. /{db}/_changes
¶
- GET /{db}/_changes¶
Returns a sorted list of changes made to documents in the database, in time order of application. Only the most recent change for a given document is guaranteed to be provided, for example if a document has had fields added, and then deleted, an API client checking for changes will not necessarily receive the intermediate state of added documents.
This can be used to listen for update and modifications to the database for post processing or synchronization, and for practical purposes, a continuously connected
_changes
feed is a reasonable approach for generating a real-time log for most applications.- Parameters:
db – Database name
- Request Headers:
Accept –
application/json
text/event-stream
text/plain
Last-Event-ID – ID of the last events received by the server on a previous connection. Overrides
since
query parameter.
- Query Parameters:
doc_ids (array) – List of document IDs to filter the changes feed as valid JSON array. Used with _doc_ids filter. Since length of URL is limited, it is better to use
POST /{db}/_changes
instead.conflicts (boolean) – Includes conflicts information in response. Ignored if include_docs isn’t
true
. Default isfalse
.descending (boolean) – Return the change results in descending sequence order (most recent change first). Default is
false
.feed (string) –
normal Specifies Normal Polling Mode. All past changes are returned immediately. Default.
longpoll Specifies Long Polling Mode. Waits until at least one change has occurred, sends the change, then closes the connection. Most commonly used in conjunction with
since=now
, to wait for the next change.continuous Sets Continuous Mode. Sends a line of JSON per event. Keeps the socket open until
timeout
.eventsource Sets Event Source Mode. Works the same as Continuous Mode, but sends the events in EventSource format.
filter (string) –
design_doc/filter_name Reference to a filter function from a design document that will filter whole stream emitting only filtered events. See the section Change Notifications in the book CouchDB The Definitive Guide for more information.
_doc_ids doc_ids filter
_view view filter
_design design filter
heartbeat (number) – Period in milliseconds after which an empty line is sent in the results. Only applicable for longpoll, continuous, and eventsource feeds. Overrides any timeout to keep the feed alive indefinitely. Default is
60000
. May betrue
to use default value.include_docs (boolean) – Include the associated document with each result. If there are conflicts, only the winning revision is returned. Default is
false
. When used withall_docs
style and a filter, return the document body even if does not pass the filtering criteria. In other words, filtering applies only to the list of"changes"
revision list not the returned document body in the"doc"
field.attachments (boolean) – Include the Base64-encoded content of attachments in the documents that are included if
include_docs
istrue
. Ignored ifinclude_docs
isn’ttrue
. Default isfalse
.att_encoding_info (boolean) – Include encoding information in attachment stubs if
include_docs
istrue
and the particular attachment is compressed. Ignored ifinclude_docs
isn’ttrue
. Default isfalse
.last-event-id (number) – Alias of Last-Event-ID header.
limit (number) – Limit number of result rows to the specified value (note that using
0
here has the same effect as1
).since – Start the results from the change immediately after the given update sequence. Can be valid update sequence or
now
value. Default is0
.style (string) – Specifies how many revisions are returned in the changes array. The default,
main_only
, will only return the current “winning” revision;all_docs
will return all leaf revisions (including conflicts and deleted former conflicts). When using a filter withall_docs
style, if none of the revisions match the filter, the changes row is skipped. If at least one revision matches, the changes row is returned with all matching revision. Ifall_docs
style is used withinclude_docs=true
and at least one revision matches the filter, the winning doc body is returned, even if it doesn’t not pass the filtering criteria.timeout (number) – Maximum period in milliseconds to wait for a change before the response is sent, even if there are no results. Only applicable for longpoll or continuous feeds. Default value is specified by
chttpd/changes_timeout
configuration option. Note that60000
value is also the default maximum timeout to prevent undetected dead connections.view (string) – Allows to use view functions as filters. Documents counted as “passed” for view filter in case if map function emits at least one record for them. See _view for more info.
seq_interval (number) – When fetching changes in a batch, setting the seq_interval parameter tells CouchDB to only calculate the update seq with every Nth result returned. By setting seq_interval=<batch size> , where
<batch size>
is the number of results requested per batch, load can be reduced on the source CouchDB database; computing the seq value across many shards (esp. in highly-sharded databases) is expensive in a heavily loaded CouchDB cluster.
- Response Headers:
Cache-Control –
no-cache
if changes feed is eventsourceapplication/json
text/event-stream
text/plain; charset=utf-8
ETag – Response hash if changes feed is normal
Transfer-Encoding –
chunked
- Response JSON Object:
last_seq (json) – Last change update sequence
pending (number) – Count of remaining items in the feed
results (array) – Changes made to a database
- Status Codes:
200 OK – Request completed successfully
400 Bad Request – Bad request
The
results
field of database changes:- JSON Parameters:
changes (array) – List of document’s leaves with single field
rev
.id (string) – Document ID.
seq (json) – Update sequence.
deleted (bool) –
true
if the document is deleted.
Request:
GET /db/_changes?style=all_docs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Mon, 12 Aug 2013 00:54:58 GMT ETag: "6ASLEKEMSRABT0O5XY9UPO9Z" Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "last_seq": "5-g1AAAAIreJyVkEsKwjAURZ-toI5cgq5A0sQ0OrI70XyppcaRY92J7kR3ojupaSPUUgotgRd4yTlwbw4A0zRUMLdnpaMkwmyF3Ily9xBwEIuiKLI05KOTW0wkV4rruP29UyGWbordzwKVxWBNOGMKZhertDlarbr5pOT3DV4gudUC9-MPJX9tpEAYx4TQASns2E24ucuJ7rXJSL1BbEgf3vTwpmedCZkYa7Pulck7Xt7x_usFU2aIHOD4eEfVTVA5KMGUkqhNZV-8_o5i", "pending": 0, "results": [ { "changes": [ { "rev": "2-7051cbe5c8faecd085a3fa619e6e6337" } ], "id": "6478c2ae800dfc387396d14e1fc39626", "seq": "3-g1AAAAG3eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MSGXAqSVIAkkn2IFUZzIkMuUAee5pRqnGiuXkKA2dpXkpqWmZeagpu_Q4g_fGEbEkAqaqH2sIItsXAyMjM2NgUUwdOU_JYgCRDA5ACGjQfn30QlQsgKvcjfGaQZmaUmmZClM8gZhyAmHGfsG0PICrBPmQC22ZqbGRqamyIqSsLAAArcXo" }, { "changes": [ { "rev": "3-7379b9e515b161226c6559d90c4dc49f" } ], "deleted": true, "id": "5bbc9ca465f1b0fcd62362168a7c8831", "seq": "4-g1AAAAHXeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBMZc4EC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HqQ_kQG3qgSQqnoUtxoYGZkZG5uS4NY8FiDJ0ACkgAbNx2cfROUCiMr9CJ8ZpJkZpaaZEOUziBkHIGbcJ2zbA4hKsA-ZwLaZGhuZmhobYurKAgCz33kh" }, { "changes": [ { "rev": "6-460637e73a6288cb24d532bf91f32969" }, { "rev": "5-eeaa298781f60b7bcae0c91bdedd1b87" } ], "id": "729eb57437745e506b333068fff665ae", "seq": "5-g1AAAAIReJyVkE0OgjAQRkcwUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloRid3MMkEUoJHbXbOxVy6arc_SxQWQzRVHCuYHaxSpuj1aqbj0t-3-AlSrZakn78oeSvjRSIkIhSNiCFHbsKN3c50b02mURvEB-yD296eNOzzoRMRLRZ98rkHS_veGcC_nR-fGe1gaCaxihhjOI2lX0BhniHaA" } ] }
Changed in version 0.11.0: added include_docs
parameter
Changed in version 1.2.0: added view
parameter and special value _view
for filter
one
Changed in version 1.3.0: since
parameter could take now value to start
listen changes since current seq number.
Changed in version 1.3.0: eventsource
feed type added.
Changed in version 1.4.0: Support Last-Event-ID
header.
Changed in version 1.6.0: added attachments
and att_encoding_info
parameters
Changed in version 2.0.0: update sequences can be any valid json object,
added seq_interval
Note
If the specified replicas of the shards in any given since value are
unavailable, alternative replicas are selected, and the last known
checkpoint between them is used. If this happens, you might see changes
again that you have previously seen. Therefore, an application making use
of the _changes
feed should be ‘idempotent’, that is, able to receive the
same data multiple times, safely.
Note
Cloudant Sync and PouchDB already optimize the replication process by
setting seq_interval
parameter to the number of results expected per
batch. This parameter increases throughput by reducing latency between
sequential requests in bulk document transfers. This has resulted in up to
a 20% replication performance improvement in highly-sharded databases.
Warning
Using the attachments
parameter to include attachments in the changes
feed is not recommended for large attachment sizes. Also note that the
Base64-encoding that is used leads to a 33% overhead (i.e. one third) in
transfer size for attachments.
Warning
The results returned by _changes are partially ordered. In other words, the order is not guaranteed to be preserved for multiple calls.
- POST /{db}/_changes¶
Requests the database changes feed in the same way as
GET /{db}/_changes
does, but is widely used with?filter=_doc_ids
or?filter=_selector
query parameters and allows one to pass a larger list of document IDs or the body of the selector to filter.- Parameters:
db – Database name
- Query Parameters:
filter (string) –
_doc_ids doc_ids filter
_selector selector filter
Request:
POST /recipes/_changes?filter=_doc_ids HTTP/1.1 Accept: application/json Content-Length: 40 Content-Type: application/json Host: localhost:5984 { "doc_ids": [ "SpaghettiWithMeatballs" ] }
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 28 Sep 2013 07:23:09 GMT ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2" Server: CouchDB (Erlang OTP) Transfer-Encoding: chunked { "last_seq": "5-g1AAAAIreJyVkEsKwjAURZ-toI5cgq5A0sQ0OrI70XyppcaRY92J7kR3ojupaSPUUgotgRd4yTlwbw4A0zRUMLdnpaMkwmyF3Ily9xBwEIuiKLI05KOTW0wkV4rruP29UyGWbordzwKVxWBNOGMKZhertDlarbr5pOT3DV4gudUC9-MPJX9tpEAYx4TQASns2E24ucuJ7rXJSL1BbEgf3vTwpmedCZkYa7Pulck7Xt7x_usFU2aIHOD4eEfVTVA5KMGUkqhNZV8_o5i", "pending": 0, "results": [ { "changes": [ { "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e" } ], "id": "SpaghettiWithMeatballs", "seq": "5-g1AAAAIReJyVkE0OgjAQRkcwUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloRid3MMkEUoJHbXbOxVy6arc_SxQWQzRVHCuYHaxSpuj1aqbj0t-3-AlSrZakn78oeSvjRSIkIhSNiCFHbsKN3c50b02mURvEB-yD296eNOzzoRMRLRZ98rkHS_veGcC_nR-fGe1gaCaxihhjOI2lX0BhniHaA" } ] }
Request:
POST /db/_changes?filter=_selector HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Length: 25 Content-Type: application/json Host: 127.0.0.1:5984 { "selector": { "data": 1 } }
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Fri, 05 Jan 2024 18:08:46 GMT ETag: "9UTJJV90GMV3XQKBM9RNAS0IK" Server: CouchDB/3.3.3-42c2484 (Erlang OTP/24) Transfer-Encoding: chunked { "last_seq": "4-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE5lzgQLshqkGSWmGyZjKcRqRxwIkGRqA1H-oSYxgk0ySLSxSEi0wdWUBAGlCJKQ", "pending": 0, "results": [ { "changes": [ { "rev": "3-fc9d7a5cf38c9f062aa246cb072eae68" } ], "id": "d1", "seq": "4-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE5lzgQLshqkGSWmGyZjKcRqRxwIkGRqA1H-oSYxgk0ySLSxSEi0wdWUBAGlCJKQ" } ] }
1.3.12.1. Changes Feeds¶
1.3.12.1.1. Polling¶
By default all changes are immediately returned within the JSON body:
GET /somedatabase/_changes HTTP/1.1
{"results":[
{"seq":"1-g1AAAAF9eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P__7MSGXAqSVIAkkn2IFUZzIkMuUAee5pRqnGiuXkKA2dpXkpqWmZeagpu_Q4g_fGEbEkAqaqH2sIItsXAyMjM2NgUUwdOU_JYgCRDA5ACGjQfn30QlQsgKvcTVnkAovI-YZUPICpBvs0CAN1eY_c","id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
{"seq":"3-g1AAAAG3eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MSGXAqSVIAkkn2IFUZzIkMuUAee5pRqnGiuXkKA2dpXkpqWmZeagpu_Q4g_fGEbEkAqaqH2sIItsXAyMjM2NgUUwdOU_JYgCRDA5ACGjQfn30QlQsgKvcjfGaQZmaUmmZClM8gZhyAmHGfsG0PICrBPmQC22ZqbGRqamyIqSsLAAArcXo","id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337CFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloRid3MMkEUoJHbXbOxVy6arc_SxQWQzRVHCuYHaxSpuj1aqbj0t-3-AlSrZakn78oeSvjRSIkIhSNiCFHbsKN3c50b02mURvEB-yD296eNOzzoRMRLRZ98rkHS_veGcC_nR-fGe1gaCaxihhjOI2lX0BhniHaA","id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
],
"last_seq":"5-g1AAAAIreJyVkEsKwjAURZ-toI5cgq5A0sQ0OrI70XyppcaRY92J7kR3ojupaSPUUgotgRd4yTlwbw4A0zRUMLdnpaMkwmyF3Ily9xBwEIuiKLI05KOTW0wkV4rruP29UyGWbordzwKVxWBNOGMKZhertDlarbr5pOT3DV4gudUC9-MPJX9tpEAYx4TQASns2E24ucuJ7rXJSL1BbEgf3vTwpmedCZkYa7Pulck7Xt7x_usFU2aIHOD4eEfVTVA5KMGUkqhNZV-8_o5i",
"pending": 0}
results
is the list of changes in sequential order. New and changed
documents only differ in the value of the rev; deleted documents include the
"deleted": true
attribute. (In the style=all_docs mode
, deleted applies
only to the current/winning revision. The other revisions listed might be
deleted even if there is no deleted property; you have to GET
them
individually to make sure.)
last_seq
is the update sequence of the last update returned (Equivalent
to the last item in the results).
Sending a since
param in the query string skips all changes up to and
including the given update sequence:
GET /somedatabase/_changes?since=4-g1AAAAHXeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBMZc4EC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HqQ_kQG3qgSQqnoUtxoYGZkZG5uS4NY8FiDJ0ACkgAbNx2cfROUCiMr9CJ8ZpJkZpaaZEOUziBkHIGbcJ2zbA4hKsA-ZwLaZGhuZmhobYurKAgCz33kh HTTP/1.1
The return structure for normal
and longpoll
modes is a JSON
array of changes objects, and the last update sequence.
In the return format for continuous
mode, the server sends a CRLF
(carriage-return, linefeed) delimited line for each change. Each line
contains the JSON object described above.
You can also request the full contents of each document change (instead
of just the change notification) by using the include_docs
parameter.
{
"last_seq": "5-g1AAAAIreJyVkEsKwjAURZ-toI5cgq5A0sQ0OrI70XyppcaRY92J7kR3ojupaSPUUgotgRd4yTlwbw4A0zRUMLdnpaMkwmyF3Ily9xBwEIuiKLI05KOTW0wkV4rruP29UyGWbordzwKVxWBNOGMKZhertDlarbr5pOT3DV4gudUC9-MPJX9tpEAYx4TQASns2E24ucuJ7rXJSL1BbEgf3vTwpmedCZkYa7Pulck7Xt7x_usFU2aIHOD4eEfVTVA5KMGUkqhNZV-8_o5i",
"pending": 0,
"results": [
{
"changes": [
{
"rev": "2-eec205a9d413992850a6e32678485900"
}
],
"deleted": true,
"id": "deleted",
"seq": "5-g1AAAAIReJyVkE0OgjAQRkcwUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloRid3MMkEUoJHbXbOxVy6arc_SxQWQzRVHCuYHaxSpuj1aqbj0t-3-AlSrZakn78oeSvjRSIkIhSNiCFHbsKN3c50b02mURvEByD296eNOzzoRMRLRZ98rkHS_veGcC_nR-fGe1gaCaxihhjOI2lX0BhniHaA",
}
]
}
1.3.12.1.2. Long Polling¶
The longpoll feed, probably most applicable for a browser, is a more efficient form of polling that waits for a change to occur before the response is sent. longpoll avoids the need to frequently poll CouchDB to discover nothing has changed!
The request to the server will remain open until a change is made on the database and is subsequently transferred, and then the connection will close. This is low load for both server and client.
The response is basically the same JSON as is sent for the normal feed.
Because the wait for a change can be significant you can set a
timeout before the connection is automatically closed (the
timeout
argument). You can also set a heartbeat interval (using
the heartbeat
query argument), which sends a newline to keep the
connection active.
Keep in mind that heartbeat
means “Send a linefeed every x
ms
if no change arrives, and hold the connection indefinitely” while timeout
means “Hold this connection open for x
ms, and if no change arrives in that
time, close the socket.” heartbeat
overrides timeout
.
1.3.12.1.3. Continuous¶
Continually polling the CouchDB server is not ideal - setting up new HTTP connections just to tell the client that nothing happened puts unnecessary strain on CouchDB.
A continuous feed stays open and connected to the database until explicitly closed and changes are sent to the client as they happen, i.e. in near real-time.
As with the longpoll feed type you can set both the timeout and heartbeat intervals to ensure that the connection is kept open for new changes and updates.
Keep in mind that heartbeat
means “Send a linefeed every x
ms
if no change arrives, and hold the connection indefinitely” while timeout
means “Hold this connection open for x
ms, and if no change arrives in that
time, close the socket.” heartbeat
overrides timeout
.
The continuous feed’s response is a little different than the other feed types to simplify the job of the client - each line of the response is either empty or a JSON object representing a single change, as found in the normal feed’s results.
If limit has been specified the feed will end with a { last_seq } object.
GET /somedatabase/_changes?feed=continuous HTTP/1.1
{"seq":"1-g1AAAAF9eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MSGXAqSVIAkkn2IFUZzIkMuUAee5pRqnGiuXkKA2dpXkpqWmZeagpu_Q4g_fGEbEkAqaqH2sIItsXAyMjM2NgUUwdOU_JYgCRDA5ACGjQfn30QlQsgKvcTVnkAovI-YZUPICpBvs0CAN1eY_c","id":"fresh","changes":[{"rev":"5-g1AAAAHxeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D666H6GcH6DYyMzIyNTUnwRR4LkGRoAFJAg-YjwiMtOdXCwJyU8ICYtABi0n6EnwzSzIxS00yI8hPEjAMQM-5nJTIQUPkAovI_UGUWAA0SgOI","id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
{"seq":"3-g1AAAAHReJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D660H6ExlwqspjAZIMDUAKqHA-yCZGiEuTUy0MzEnxL8SkBRCT9iPcbJBmZpSaZkKUmyFmHICYcZ-wux9AVIJ8mAUABgp6XQ","id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
... tum tee tum ...
{"seq":"6-g1AAAAIreJyVkEsKwjAURWMrqCOXoCuQ9MU0OrI70XyppcaRY92J7kR3ojupaVNopRQsgRd4yTlwb44QmqahQnN7VjpKImAr7E6Uu4eAI7EoiiJLQx6c3GIiuVJcx93vvQqxdFPsaguqLAY04YwpNLtYpc3RatXPJyW__-EFllst4D_-UPLXmh9VPAaICaEDUtixm-jmLie6N30YqTeYDenDmx7e9GwyYRODNuu_MnnHyzverV6AMkPkAMfHO1rdUAKUkqhLZV-_0o5j","id":"updated","changes":[{"rev":"3-825cb35de44c433bfb2df415563a19de"}]}
Obviously, … tum tee tum … does not appear in the actual response, but represents a long pause before the change with seq 6 occurred.
1.3.12.1.4. Event Source¶
The eventsource feed provides push notifications that can be consumed in
the form of DOM events in the browser. Refer to the W3C eventsource
specification for further details. CouchDB also honours the Last-Event-ID
parameter.
GET /somedatabase/_changes?feed=eventsource HTTP/1.1
// define the event handling function
if (window.EventSource) {
var source = new EventSource("/somedatabase/_changes?feed=eventsource");
source.onerror = function(e) {
alert('EventSource failed.');
};
var results = [];
var sourceListener = function(e) {
var data = JSON.parse(e.data);
results.push(data);
};
// start listening for events
source.addEventListener('message', sourceListener, false);
// stop listening for events
source.removeEventListener('message', sourceListener, false);
}
If you set a heartbeat interval (using the heartbeat
query argument),
CouchDB will send a hearbeat
event that you can subscribe to with:
source.addEventListener('heartbeat', function () {}, false);
This can be monitored by the client application to restart the EventSource connection if needed (i.e. if the TCP connection gets stuck in a half-open state).
Note
EventSource connections are subject to cross-origin resource sharing restrictions. You might need to configure CORS support to get the EventSource to work in your application.
1.3.12.2. Filtering¶
You can filter the contents of the changes feed in a number of ways. The most basic way is to specify one or more document IDs to the query. This causes the returned structure value to only contain changes for the specified IDs. Note that the value of this query argument should be a JSON formatted array.
You can also filter the _changes
feed by defining a filter function
within a design document. The specification for the filter is the same
as for replication filters. You specify the name of the filter function
to the filter
parameter, specifying the design document name and
filter name. For example:
GET /db/_changes?filter=design_doc/filtername HTTP/1.1
Additionally, a couple of built-in filters are available and described below.
1.3.12.2.1. _doc_ids¶
This filter accepts only changes for documents which ID in specified in
doc_ids
query parameter or payload’s object array. See
POST /{db}/_changes
for an example.
1.3.12.2.2. _selector¶
Added in version 2.0.
This filter accepts only changes for documents which match a specified selector, defined using the same selector syntax used for _find.
This is significantly more efficient than using a JavaScript filter function and is the recommended option if filtering on document attributes only.
Note that, unlike JavaScript filters, selectors do not have access to the request object.
Request:
POST /recipes/_changes?filter=_selector HTTP/1.1
Content-Type: application/json
Host: localhost:5984
{
"selector": { "_id": { "$regex": "^_design/" } }
}
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Tue, 06 Sep 2016 20:03:23 GMT
Etag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang OTP/18)
Transfer-Encoding: chunked
{
"last_seq": "11-g1AAAAIreJyVkEEKwjAQRUOrqCuPoCeQZGIaXdmbaNIk1FLjyrXeRG-iN9Gb1LQRaimFlsAEJnkP_s8RQtM0VGhuz0qTmABfYXdI7h4CgeSiKIosDUVwcotJIpQSOmp_71TIpZty97OgymJAU8G5QrOLVdocrVbdfFzy-wYvcbLVEvrxh5K_NlJggIhSNiCFHbmJbu5yonttMoneYD6kD296eNOzzoRNBNqse2Xyjpd3vP96AcYNTQY4Pt5RdTOuHIwCY5S0qewLwY6OaA",
"pending": 0,
"results": [
{
"changes": [
{
"rev": "10-304cae84fd862832ea9814f02920d4b2"
}
],
"id": "_design/ingredients",
"seq": "8-g1AAAAHxeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D666H6GcH6DYyMzIyNTUnwRR4LkGRoAFJAg-ZnJTIQULkAonI_ws0GaWZGqWkmRLkZYsYBiBn3Cdv2AKIS7ENWsG2mxkampsaGmLqyAOYpgEo"
},
{
"changes": [
{
"rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
}
],
"deleted": true,
"id": "_design/cookbook",
"seq": "9-g1AAAAHxeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D661F8YWBkZGZsbEqCL_JYgCRDA5ACGjQ_K5GBgMoFEJX7EW42SDMzSk0zIcrNEDMOQMy4T9i2BxCVYB-ygm0zNTYyNTU2xNSVBQDnK4BL"
},
{
"changes": [
{
"rev": "6-5b8a52c22580e922e792047cff3618f3"
}
],
"deleted": true,
"id": "_design/meta",
"seq": "11-g1AAAAIReJyVkE0OgjAQRiegUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloQhO7mGSCKWEjtrtnQq5dFXufhaoLIZoKjhXMLtYpc3RatXNxyW_b_ASJVstST_-UPLXRgpESEQpG5DCjlyFm7uc6F6bTKI3iA_Zhzc9vOlZZ0ImItqse2Xyjpd3vDMBfzo_vrPawLiaxihhjOI2lX0BirqHbg"
}
]
}
1.3.12.2.2.1. Missing selector¶
If the selector object is missing from the request body, the error message is similar to the following example:
{
"error": "bad request",
"reason": "Selector must be specified in POST payload"
}
1.3.12.2.2.2. Not a valid JSON object¶
If the selector object is not a well-formed JSON object, the error message is similar to the following example:
{
"error": "bad request",
"reason": "Selector error: expected a JSON object"
}
1.3.12.2.2.3. Not a valid selector¶
If the selector object does not contain a valid selection expression, the error message is similar to the following example:
{
"error": "bad request",
"reason": "Selector error: expected a JSON object"
}
1.3.12.2.3. _design¶
The _design
filter accepts only changes for any design document within the
requested database.
Request:
GET /recipes/_changes?filter=_design HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Tue, 06 Sep 2016 12:55:12 GMT
ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked
{
"last_seq": "11-g1AAAAIreJyVkEEKwjAQRUOrqCuPoCeQZGIaXdmbaNIk1FLjyrXeRG-iN9Gb1LQRaimFlsAEJnkP_s8RQtM0VGhuz0qTmABfYXdI7h4CgeSiKIosDUVwcotJIpQSOmp_71TIpZty97OgymJAU8G5QrOLVdocrVbdfFzy-wYvcbLVEvrxh5K_NlJggIhSNiCFHbmJbu5yonttMoneYD6kD296eNOzzoRNBNqse2Xyjpd3vP96AcYNTQY4Pt5RdTOuHIwCY5S0qewLwY6OaA",
"pending": 0,
"results": [
{
"changes": [
{
"rev": "10-304cae84fd862832ea9814f02920d4b2"
}
],
"id": "_design/ingredients",
"seq": "8-g1AAAAHxeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D666H6GcH6DYyMzIyNTUnwRR4LkGRoAFJAg-ZnJTIQULkAonI_ws0GaWZGqWkmRLkZYsYBiBn3Cdv2AKIS7ENWsG2mxkampsaGmLqyAOYpgEo"
},
{
"changes": [
{
"rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
}
],
"deleted": true,
"id": "_design/cookbook",
"seq": "9-g1AAAAHxeJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBOZcoEC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HkV_kkGyZWqSEXH6E0D661F8YWBkZGZsbEqCL_JYgCRDA5ACGjQ_K5GBgMoFEJX7EW42SDMzSk0zIcrNEDMOQMy4T9i2BxCVYB-ygm0zNTYyNTU2xNSVBQDnK4BL"
},
{
"changes": [
{
"rev": "6-5b8a52c22580e922e792047cff3618f3"
}
],
"deleted": true,
"id": "_design/meta",
"seq": "11-g1AAAAIReJyVkE0OgjAQRiegUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloQhO7mGSCKWEjtrtnQq5dFXufhaoLIZoKjhXMLtYpc3RatXNxyW_b_ASJVstST_-UPLXRgpESEQpG5DCjlyFm7uc6F6bTKI3iA_Zhzc9vOlZZ0ImItqse2Xyjpd3vDMBfzo_vrPawLiaxihhjOI2lX0BirqHbg"
}
]
}
1.3.12.2.4. _view¶
Added in version 1.2.
The special filter _view
allows to use existing
map function as the filter. If the map
function emits anything for the processed document it counts as accepted and
the changes event emits to the feed. For most use-practice cases filter
functions are very similar to map ones, so this feature helps to reduce
amount of duplicated code.
Warning
While map functions doesn’t process the design documents,
using _view
filter forces them to do this. You need to be sure, that
they are ready to handle documents with alien structure without panic.
Note
Using _view
filter doesn’t queries the view index files, so you cannot
use common view query parameters to additionally
filter the changes feed by index key. Also, CouchDB doesn’t returns
the result instantly as it does for views - it really uses the specified
map function as filter.
Moreover, you cannot make such filters dynamic e.g. process the request query parameters or handle the User Context Object - the map function is only operates with the document.
Request:
GET /recipes/_changes?filter=_view&view=ingredients/by_recipe HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Tue, 06 Sep 2016 12:57:56 GMT
ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked
{
"last_seq": "11-g1AAAAIreJyVkEEKwjAQRUOrqCuPoCeQZGIaXdmbaNIk1FLjyrXeRG-iN9Gb1LQRaimFlsAEJnkP_s8RQtM0VGhuz0qTmABfYXdI7h4CgeSiKIosDUVwcotJIpQSOmp_71TIpZty97OgymJAU8G5QrOLVdocrVbdfFzy-wYvcbLVEvrxh5K_NlJggIhSNiCFHbmJbu5yonttMoneYD6kD296eNOzzoRNBNqse2Xyjpd3vP96AcYNTQY4Pt5RdTOuHIwCY5S0qewLwY6OaA",
"results": [
{
"changes": [
{
"rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
}
],
"id": "SpaghettiWithMeatballs",
"seq": "11-g1AAAAIReJyVkE0OgjAQRiegUVceQU9g-mOpruQm2tI2SLCuXOtN9CZ6E70JFmpCCCFCmkyTdt6bfJMDwDQNFcztWWkcY8JXyB2cu49AgFwURZGloQhO7mGSCKWEjtrtnQq5dFXufhaoLIZoKjhXMLtYpc3RatXNxyW_b_ASJVstST_-UPLXRgpESEQpG5DCjlyFm7uc6F6bTKI3iA_Zhzc9vOlZZ0ImItqse2Xyjpd3vDMBfzo_vrPawLiaxihhjOI2lX0BirqHbg"
}
]
}