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 PR-URL: https://github.com/apache/couchdb-documentation/pull/81 Reviewed-By: Robert Newson <rnew...@apache.org> Reviewed-By: Robert Kowalski <r...@kowalski.gd> Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/fec08935 Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/fec08935 Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/fec08935 Branch: refs/heads/master Commit: fec0893511dad132834835587e2ee8d5b89ab6a0 Parents: c58e360 Author: Will Holley <willhol...@gmail.com> Authored: Tue Oct 11 09:48:54 2016 +0100 Committer: Robert Kowalski <robertkowal...@apache.org> 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(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/fec08935/src/api/ddoc/views.rst ---------------------------------------------------------------------- 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. *Optional* :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`` parameters .. 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 http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/fec08935/src/maintenance/performance.rst ---------------------------------------------------------------------- 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.
