share/doc/src/changes.rst - couchdb - Git at Google

 .. Licensed under the Apache License, Version 2.0 (the "License"); you may not
 .. use this file except in compliance with the License. You may obtain a copy of
 .. the License at
 ..
 ..   http://www.apache.org/licenses/LICENSE-2.0
 ..
 .. Unless required by applicable law or agreed to in writing, software
 .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 .. License for the specific language governing permissions and limitations under
 .. the License.

 .. _changes:

 ============
 Changes Feed
 ============

 Polling
 =======

 A list of changes made to documents in the database, in the order they were
 made, can be obtained from the database's ``_changes`` resource. You can query
 the ``_changes`` resource by issuing a ``GET`` request with the following
 (optional) parameters:

 +--------------+----------------------------------------------+---------------+--------------+
 | Parameter    | Value                                        | Default Value |  Notes       |
 +==============+==============================================+===============+==============+
 | since        | seqnum / now                                 | 0             | \(1)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | limit        | maxsequences                                 | none          | \(2)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | descending   | boolean                                      | false         | \(3)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | feed         | normal / longpoll / continuous / eventsource | normal        | \(4)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | heartbeat    | milliseconds                                 | 60000         | \(5)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | timeout      | milliseconds                                 | 60000         | \(6)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | filter       | designdoc/filtername / _view                 | none          | \(7)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | include_docs | boolean                                      | false         | \(8)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | style        | all_docs / main_only                         | main_only     | \(9)         |
 +--------------+----------------------------------------------+---------------+--------------+
 | view         | designdoc/filtername                         | none          | \(10)        |
 +--------------+----------------------------------------------+---------------+--------------+

 Notes:

 (1) Start the results from the change immediately after the given sequence
     number.

 (2) Limit number of result rows to the specified value (note that using 0 here
     has the same effect as 1).

 (3) Return the change results in descending sequence order (most recent change
     first)

 (4) Select the type of feed.

 (5) Period in milliseconds after which an empty line is sent in the results.
     Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout
     to keep the feed alive indefinitely.

 (6) 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. Note that 60000 is also the default maximum timeout to
     prevent undetected dead connections.

     You can change the default maximum timeout in your ini-configuration:

     .. code-block:: ini

         [httpd]
         changes_timeout=#millisecs

 (7) Reference to a :ref:`filter function <filterfun>` from a design document
     that will filter whole stream emitting only filtered events.
     See the `section in the book`_ for more information.

 (8) Include the associated document with each result. If there are conflicts,
     only the winning revision is returned.

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

 (10) Allows to use view functions as filters. It requires to set ``filter``
      special value `_view` to enable this feature. Documents counted as "passed"
      for view filter in case if map function emits at least one record for them.

 .. versionchanged:: 0.11.0 added ``include_docs`` parameter
 .. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
    for ``filter`` one
 .. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
    listen changes since current seq number.
 .. versionchanged:: 1.3.0 ``eventsource`` feed type added.

 By default all changes are immediately returned as a JSON object::

     GET /somedatabase/_changes HTTP/1.1

 .. code-block:: javascript

     {"results":[
     {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
     {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]},
     {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
     ],
     "last_seq":5}

 ``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 sequence number of the last update returned. (Currently it
 will always be the same as the seq of the last item in results.)

 Sending a ``since`` param in the query string skips all changes up to and
 including the given sequence number::

     GET /somedatabase/_changes?since=3 HTTP/1.1

 .. code-block:: javascript

     {"results":[
     {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
     ],
     "last_seq":5}

 Long Polling
 ============

 The `longpoll` feed (probably most useful used from 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 response is basically the same JSON as is sent for the normal feed.

 A timeout limits the maximum length of time the connection is open. If there
 are no changes before the timeout expires the response's results will be an
 empty list.

 Continuous
 ==========

 Polling the CouchDB server is not a good thing to do. 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.

 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.

 .. code-block:: text

     GET /somedatabase/_changes?feed=continuous HTTP/1.1

 .. code-block:: javascript

     {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}
     {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
     {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
     ... tum tee tum ...
     {"seq":6,"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.

 .. _section in the book: http://books.couchdb.org/relax/reference/change-notifications

 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 honors the ``Last-Event-ID`` header,
 and if it's present it will take precedence over the ``since`` query parameter.

 .. code-block:: text

     GET /somedatabase/_changes?feed=eventsource HTTP/1.1

 .. code-block:: javascript

     // 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);

     }

 .. note::

    EventSource connections are subject to cross-origin resource sharing
    restrictions. You might need to use the experimental :ref:`CORS support
    <cors>` to get the EventSource to work in your application.

 .. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
	.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
	.. use this file except in compliance with the License. You may obtain a copy of
	.. the License at
	..
	.. http://www.apache.org/licenses/LICENSE-2.0
	..
	.. Unless required by applicable law or agreed to in writing, software
	.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	.. License for the specific language governing permissions and limitations under
	.. the License.

	.. _changes:

	============
	Changes Feed
	============

	Polling
	=======

	A list of changes made to documents in the database, in the order they were
	made, can be obtained from the database's ``_changes`` resource. You can query
	the ``_changes`` resource by issuing a ``GET`` request with the following
	(optional) parameters:

	+--------------+----------------------------------------------+---------------+--------------+
	\| Parameter \| Value \| Default Value \| Notes \|
	+==============+==============================================+===============+==============+
	\| since \| seqnum / now \| 0 \| \(1) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| limit \| maxsequences \| none \| \(2) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| descending \| boolean \| false \| \(3) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| feed \| normal / longpoll / continuous / eventsource \| normal \| \(4) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| heartbeat \| milliseconds \| 60000 \| \(5) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| timeout \| milliseconds \| 60000 \| \(6) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| filter \| designdoc/filtername / _view \| none \| \(7) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| include_docs \| boolean \| false \| \(8) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| style \| all_docs / main_only \| main_only \| \(9) \|
	+--------------+----------------------------------------------+---------------+--------------+
	\| view \| designdoc/filtername \| none \| \(10) \|
	+--------------+----------------------------------------------+---------------+--------------+

	Notes:

	(1) Start the results from the change immediately after the given sequence
	number.

	(2) Limit number of result rows to the specified value (note that using 0 here
	has the same effect as 1).

	(3) Return the change results in descending sequence order (most recent change
	first)

	(4) Select the type of feed.

	(5) Period in milliseconds after which an empty line is sent in the results.
	Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout
	to keep the feed alive indefinitely.

	(6) 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. Note that 60000 is also the default maximum timeout to
	prevent undetected dead connections.

	You can change the default maximum timeout in your ini-configuration:

	.. code-block:: ini

	[httpd]
	changes_timeout=#millisecs

	(7) Reference to a :ref:`filter function <filterfun>` from a design document
	that will filter whole stream emitting only filtered events.
	See the `section in the book`_ for more information.

	(8) Include the associated document with each result. If there are conflicts,
	only the winning revision is returned.

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

	(10) Allows to use view functions as filters. It requires to set ``filter``
	special value `_view` to enable this feature. Documents counted as "passed"
	for view filter in case if map function emits at least one record for them.

	.. versionchanged:: 0.11.0 added ``include_docs`` parameter
	.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
	for ``filter`` one
	.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
	listen changes since current seq number.
	.. versionchanged:: 1.3.0 ``eventsource`` feed type added.

	By default all changes are immediately returned as a JSON object::

	GET /somedatabase/_changes HTTP/1.1

	.. code-block:: javascript

	{"results":[
	{"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
	{"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]},
	{"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
	],
	"last_seq":5}

	``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 sequence number of the last update returned. (Currently it
	will always be the same as the seq of the last item in results.)

	Sending a ``since`` param in the query string skips all changes up to and
	including the given sequence number::

	GET /somedatabase/_changes?since=3 HTTP/1.1

	.. code-block:: javascript

	{"results":[
	{"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
	],
	"last_seq":5}

	Long Polling
	============

	The `longpoll` feed (probably most useful used from 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 response is basically the same JSON as is sent for the normal feed.

	A timeout limits the maximum length of time the connection is open. If there
	are no changes before the timeout expires the response's results will be an
	empty list.

	Continuous
	==========

	Polling the CouchDB server is not a good thing to do. 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.

	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.

	.. code-block:: text

	GET /somedatabase/_changes?feed=continuous HTTP/1.1

	.. code-block:: javascript

	{"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}
	{"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
	{"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
	... tum tee tum ...
	{"seq":6,"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.

	.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications

	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 honors the ``Last-Event-ID`` header,
	and if it's present it will take precedence over the ``since`` query parameter.

	.. code-block:: text

	GET /somedatabase/_changes?feed=eventsource HTTP/1.1

	.. code-block:: javascript

	// 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);

	}

	.. note::

	EventSource connections are subject to cross-origin resource sharing
	restrictions. You might need to use the experimental :ref:`CORS support
	<cors>` to get the EventSource to work in your application.

	.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/