couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "HTTP_database_API" by MattGoodall
Date Mon, 19 Oct 2009 22:51:14 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "HTTP_database_API" page has been changed by MattGoodall.
http://wiki.apache.org/couchdb/HTTP_database_API?action=diff&rev1=9&rev2=10

--------------------------------------------------

  
  == Changes ==
  
+ 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.
+ 
+   * GET
+     * since=seqnum (default=0). Start the results from the change immediately after the
given sequence number.
+     * feed=normal|longpoll|continuous (default=normal). Select the type of feed.
+     * heartbeat=time (milliseconds, default=60000). Period in milliseconds after which a
empty line is sent in the results. Only applicable for ''longpoll'' or ''continuous'' feeds.
+     * timeout=time (milliseconds, default=60000). 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.
+ 
+ By default all changes are immediately returned as a JSON object:
+ 
  {{{
  GET /somedatabase/_changes HTTP/1.1
  }}}
  
  {{{
- {"results":
+ {"results":[
-   [{"seq":6,"id":"doc","changes":[{"rev":"2-e32fbda1a1a0aeeab717dafac56527e6"}],"deleted":true},
-    {"seq":10,"id":"otherdoc","changes":[{"rev":"2-69b8f3ec4ef9fbbc2409a924b5b0850a"}]}
-   ],
+ {"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":10}
+ "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.
+ 
+ ''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
+ }}}
+ 
+ {{{
+ {"results":[
+ {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+ ],
+ "last_seq":5}
+ }}}
+ 
+ === Long-Polling (Efficient Polling) Feed ===
+ 
+ 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 (Non-Polling) Feed ===
+ 
+ Polling the CouchDB server is not a good thing to do. Setting up new HTTP connections just
to tell the client that nothing's 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''.
+ 
+ {{{
+ GET /somedatabase/_changes?feed=continuous HTTP/1.1
+ }}}
+ 
+ {{{
+ {"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.
  
  == Compaction ==
  

Mime
View raw message