couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject documentation commit: updated refs/heads/master to fec0893
Date Thu, 01 Dec 2016 02:16:05 GMT
Repository: couchdb-documentation
Updated Branches:
  refs/heads/master c58e360bb -> fec089351

Document stable and update query parameters

CouchDB-3063 adds 2 new query parameters when querying views.
This commit adds API documentation for these and a note in the
performance guide around when to use them.

PR: #81
Reviewed-By: Robert Newson <>
Reviewed-By: Robert Kowalski <>


Branch: refs/heads/master
Commit: fec0893511dad132834835587e2ee8d5b89ab6a0
Parents: c58e360
Author: Will Holley <>
Authored: Tue Oct 11 09:48:54 2016 +0100
Committer: Robert Kowalski <>
Committed: Thu Dec 1 03:15:57 2016 +0100

 src/api/ddoc/views.rst          | 15 +++++++++++++--
 src/maintenance/performance.rst |  8 ++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)
diff --git a/src/api/ddoc/views.rst b/src/api/ddoc/views.rst
index 2eace71..bd217b8 100644
--- a/src/api/ddoc/views.rst
+++ b/src/api/ddoc/views.rst
@@ -67,8 +67,14 @@
      <api/ddoc/view/sorting>`). Setting this to ``false`` offers a performance
      boost. The `total_rows` and `offset` fields are not available when this
      is set to ``false``. Default is ``true``
+    :query boolean stable: Whether or not the view results should be returned
+     from a stable set of shards. Default is ``false``. *Optional*
     :query string stale: Allow the results from a stale view to be used.
-      Supported values: ``ok`` and ``update_after``. *Optional*
+      Supported values: ``ok``, ``update_after`` and ``false``.
+      ``ok`` is equivalent to ``stable=true&update=false``.
+      ``update_after`` is equivalent to ``stable=true&update=lazy``.
+      ``false`` is equivalent to ``stable=false&update=true``.
+      *Optional*
     :query json startkey: Return records starting with the specified key.
     :query json start_key: Alias for `startkey` param
@@ -76,9 +82,13 @@
       document ID. Requires ``startkey`` to be specified for this to have any
       effect. *Optional*
     :query string start_key_doc_id: Alias for `startkey_docid` param
+    :query string update: Whether or not the view in question should be updated
+     prior to responding to the user.
+     Supported values: ``true``, ``false``, ``lazy``.
+     Default is ``true``. *Optional*
     :query boolean update_seq: Response includes an ``update_seq`` value
       indicating which sequence id of the database the view reflects.
-      Default is ``false``
+      Default is ``false``.
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
@@ -142,6 +152,7 @@
 .. versionchanged:: 1.6.0 added ``attachments`` and ``att_encoding_info``
 .. versionchanged:: 2.0.0 added ``sorted`` parameter
+.. versionchanged:: 2.1.0 added ``stable`` and ``update`` parameters
 .. warning::
     Using the ``attachments`` parameter to include attachments in view results
diff --git a/src/maintenance/performance.rst b/src/maintenance/performance.rst
index 4e0eec3..ac2f08f 100644
--- a/src/maintenance/performance.rst
+++ b/src/maintenance/performance.rst
@@ -230,6 +230,14 @@ that will occur giving you a quick response and when views will be updated
 which will take a long time. (A 10 million document database took about 10
 minutes to load into CouchDB but about 4 hours to do view generation).
+In a cluster, "stale" requests are serviced by a fixed set of shards in order
+to present users with consistent results between requests. This comes with an
+availability trade-off - the fixed set of shards might not be the most
+responsive / available within the cluster. If you don't need this kind of
+consistency (e.g. your indexes are relatively static), you can tell CouchDB to
+use any available replica by specifying ``stable=false&update=false`` instead of
+``stale=ok``, or ``stable=false&update=lazy`` instead of ``stale=update_after``.
 View information isn't replicated - it is rebuilt on each database so you
 can't do the view generation on a separate sever.

View raw message