| Method | GET /db/_changes | |
| Request | None | |
| Response | JSON of the changes to the database | |
| Admin Privileges Required | no | |
| Query Arguments | Argument | doc_ids |
| Description | Specify the list of documents IDs to be filtered | |
| Optional | yes | |
| Type | json | |
| Default | none | |
| Argument | feed | |
| Description | Type of feed | |
| Optional | yes | |
| Type | string | |
| Default | normal | |
| Supported Values | ||
continuous | Continuous (non-polling) mode | |
longpoll | Long polling mode | |
normal | Normal mode | |
| Argument | filter | |
| Description | Filter function from a design document to get updates | |
| Optional | yes | |
| Type | string | |
| Default | none | |
| Supported Values | ||
| Argument | heartbeat | |
| Description | Period after which an empty line is sent during longpoll or continuous | |
| Optional | yes | |
| Type | numeric | |
| Default | 60000 | |
| Quantity | milliseconds | |
| Argument | include_docs | |
| Description | Include the document with the result | |
| Optional | yes | |
| Type | boolean | |
| Default | false | |
| Argument | limit | |
| Description | Maximum number of rows rows to return | |
| Optional | yes | |
| Type | numeric | |
| Default | none | |
| Argument | since | |
| Description | Start the results from changes immediately after the specified sequence number | |
| Optional | yes | |
| Type | numeric | |
| Default | 0 | |
| Argument | timeout | |
| Description | Maximum period to wait before the response is sent | |
| Optional | yes | |
| Type | numeric | |
| Default | 60000 | |
| Quantity | milliseconds | |
Obtains a list of the changes made to the database. This can be
used to monitor for update and modifications to the database for
post processing or synchronization. There are three different
types of supported changes feeds, poll, longpoll, and continuous.
All requests are poll requests by default. You can select any feed
type explicitly using the feed query argument.
Poll
With polling you can request the changes that have occured since a specific sequence number. This returns the JSON structure containing the changed document information. When you perform a poll change request, only the changes since the specific sequence number are returned. For example, the query
DELETE http://couchdb:5984/recipes/_changes Content-Type: application/json
Will get all of the changes in the database. You can request
a starting point using the since query
argument and specifying the sequence number. You will need
to record the latest sequence number in your client and then
use this when making another request as the new value to the
since parameter.
Longpoll
With long polling the request to the server will remain open until a change is made on the database, when the changes will be reported, and then the connection will close. The long poll is useful when you want to monitor for changes for a specific purpose without wanting to monitoring continuously for changes.
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 open.
Continuous
Continuous sends all new changes back to the client immediately, without closing the connection. In continuous mode the format of the changes is slightly different to accommodate the continuous nature while ensuring that the JSON output is still valid for each change notification.
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 changesand updates.
The return structure for normal and
longpoll modes is a JSON array of changes
objects, and the last update sequence number. The structure is
described in the following table.
Table 5.3. Changes information for a database
| Field | Description |
last_seq | Last change sequence number |
results [array] | Changes made to a database |
changes [array] | List of changes, field-by-field, for this document |
id | Document ID |
seq | Update sequence number |
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.
You can also request the full contents of each document change
(instead of just the change notification) by using the
include_docs parameter.