More Help

Returns a sorted list of changes made to documents in the database, in time
order of application, can be obtained from the database’s _changes
resource. 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.

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.

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 be
true 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.

attachments (boolean) – Include the Base64-encoded content of
attachments in the documents that
are included if include_docs is true. Ignored if include_docs
isn’t true. Default is false.

att_encoding_info (boolean) – Include encoding information in attachment
stubs if include_docs is true and the particular attachment is
compressed. Ignored if include_docs isn’t true.
Default is false.

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 as 1).

since – Start the results from the change immediately after the given
update sequence. Can be valid update sequence or now value.
Default is 0.

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).

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 httpd/changes_timeout
configuration option. Note that 60000 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 <batchsize> 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.

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.

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_docsmode, 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:

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.

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.

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.

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.

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/filternameHTTP/1.1

Additionally, a couple of built-in filters are available and described
below.

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.