You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by fl...@apache.org on 2017/11/17 19:35:09 UTC
[couchdb-documentation] branch master updated: Update _all_docs
documentation (#203)
This is an automated email from the ASF dual-hosted git repository.
flimzy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new bdfa864 Update _all_docs documentation (#203)
bdfa864 is described below
commit bdfa864b3a6d449f0f7e382628c2ab8350679d13
Author: Jonathan Hall <fl...@flimzy.com>
AuthorDate: Fri Nov 17 20:35:07 2017 +0100
Update _all_docs documentation (#203)
* Refer to main _view documentation, rather than duplicating info for _all_docs
* Remove 500 from list of expected result codes
* Cleanups, clarifications, and better formatting consistency.
---
src/api/database/bulk-api.rst | 57 ++++----------------------------------
src/api/ddoc/views.rst | 64 ++++++++++++++++++++-----------------------
2 files changed, 36 insertions(+), 85 deletions(-)
diff --git a/src/api/database/bulk-api.rst b/src/api/database/bulk-api.rst
index 905e43c..c794f14 100644
--- a/src/api/database/bulk-api.rst
+++ b/src/api/database/bulk-api.rst
@@ -19,59 +19,14 @@
.. http:get:: /{db}/_all_docs
:synopsis: Returns a built-in view of all documents in this database
- Returns a JSON structure of all of the documents in a given database.
- The information is returned as a JSON structure containing meta
- information about the return structure, including a list of all documents
- and basic contents, consisting the ID, revision and key. The key is the
- from the document's ``_id``.
+ Executes the built-in `_all_docs` :ref:`view <views>`, returning all of the
+ documents in the database. With the exception of the URL parameters
+ (described below), this endpoint works identically to any other view. Refer
+ to the :ref:`view endpoint <api/ddoc/view>` documentation for a complete
+ description of the available query parameters and the format of the returned
+ data.
:param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``.
- :query boolean descending: Return the documents in descending by key order.
- Default is ``false``.
- :query string endkey: Stop returning records when the specified key is
- reached. *Optional*.
- :query string end_key: Alias for `endkey` param.
- :query string endkey_docid: Stop returning records when the specified
- document ID is reached. *Optional*.
- :query string end_key_doc_id: Alias for `endkey_docid` param.
- :query boolean include_docs: Include the full content of the documents in
- the return. Default is ``false``.
- :query boolean inclusive_end: Specifies whether the specified end key
- should be included in the result. Default is ``true``.
- :query string key: Return only documents that match the specified key.
- *Optional*.
- :query string keys: Return only documents that match the specified keys.
- *Optional*.
- :query number limit: Limit the number of the returned documents to the
- specified number. *Optional*.
- :query number skip: Skip this number of records before starting to return
- the results. Default is ``0``.
- :query string stale: Allow the results from a stale view to be used,
- without triggering a rebuild of all views within the encompassing design
- doc. Supported values: ``ok`` and ``update_after``. *Optional*.
- :query string startkey: Return records starting with the specified key.
- *Optional*.
- :query string start_key: Alias for `startkey` param.
- :query string startkey_docid: Return records starting with the specified
- document ID. *Optional*.
- :query string start_key_doc_id: Alias for `startkey_docid` param.
- :query boolean update_seq: Response includes an ``update_seq`` value
- indicating which sequence id of the underlying database the view
- reflects. Default is ``false``.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response signature
- :>json number offset: Offset where the document list started
- :>json array rows: Array of view row objects. By default the information
- returned contains only the document ID and revision.
- :>json number total_rows: Number of documents in the database/view. Note
- that this is not the number of rows returned in the actual query.
- :>json number update_seq: Current update sequence for the database
- :code 200: Request completed successfully
**Request**:
diff --git a/src/api/ddoc/views.rst b/src/api/ddoc/views.rst
index f2349be..5d3df71 100644
--- a/src/api/ddoc/views.rst
+++ b/src/api/ddoc/views.rst
@@ -28,20 +28,21 @@
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``
- :query boolean descending: Return the documents in descending by key order.
- Default is ``false``
+ :query boolean conflicts: Include `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``.
+ :query boolean descending: Return the documents in descending order by key.
+ Default is ``false``.
:query json endkey: Stop returning records when the specified key is
- reached. *Optional*
+ reached.
:query json end_key: Alias for `endkey` param
:query string endkey_docid: Stop returning records when the specified
- document ID is reached. Requires ``endkey`` to be specified for this to
- have any effect. *Optional*
- :query string end_key_doc_id: Alias for `endkey_docid` param
+ document ID is reached. Ignored if `endkey` is not set.
+ :query string end_key_doc_id: Alias for `endkey_docid`.
:query boolean group: Group the results using the reduce function to a
- group or single row. Default is ``false``
- :query number group_level: Specify the group level to be used. *Optional*
+ group or single row. Implies `reduce` is ``true`` and the maximum
+ `group_level`. Default is ``false``.
+ :query number group_level: Specify the group level to be used. Implies
+ `group` is ``true``.
:query boolean include_docs: Include the associated document with each row.
Default is ``false``.
:query boolean attachments: Include the Base64-encoded content of
@@ -53,59 +54,54 @@
attachment is compressed. Ignored if `include_docs` isn't ``true``.
Default is ``false``.
:query boolean inclusive_end: Specifies whether the specified end key
- should be included in the result. Default is ``true``
+ should be included in the result. Default is ``true``.
:query json key: Return only documents that match the specified key.
- *Optional*
:query json-array keys: Return only documents where the key matches one of
- the keys specified in the array. *Optional*
+ the keys specified in the array.
:query number limit: Limit the number of the returned documents to the
- specified number. *Optional*
- :query boolean reduce: Use the reduction function. Default is ``true``
+ specified number.
+ :query boolean reduce: Use the reduction function. Default is ``true`` when
+ a reduce function is defined.
:query number skip: Skip this number of records before starting to return
- the results. Default is ``0``
+ the results. Default is ``0``.
:query boolean sorted: Sort returned rows (see :ref:`Sorting Returned Rows
<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``
+ 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*
+ from a stable set of shards. Default is ``false``.
:query string stale: Allow the results from a stale view to be used.
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
+ :query json start_key: Alias for `startkey`.
:query string startkey_docid: Return records starting with the specified
- document ID. Requires ``startkey`` to be specified for this to have any
- effect. *Optional*
+ document ID. Ignored if ``startkey`` is not set.
: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``.
+ prior to responding to the user. Supported values: ``true``, ``false``,
+ ``lazy``. Default is ``true``.
+ :query boolean update_seq: Whether to include in the response an
+ `update_seq` value indicating the sequence id of the database the view
+ reflects. Default is ``false``.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Response signature
:>header Transfer-Encoding: ``chunked``
- :>json number offset: Offset where the document list started
+ :>json number offset: Offset where the document list started.
:>json array rows: Array of view row objects. By default the information
- returned contains only the document ID and revision
- :>json number total_rows: Number of documents in the database/view
- :>json object update_seq: Current update sequence for the database
+ returned contains only the document ID and revision.
+ :>json number total_rows: Number of documents in the database/view.
+ :>json object update_seq: Current update sequence for the database.
:code 200: Request completed successfully
:code 400: Invalid request
:code 401: Read permission required
:code 404: Specified database, design document or view is missed
- :code 500: View function execution error
**Request**:
--
To stop receiving notification emails like this one, please contact
['"commits@couchdb.apache.org" <co...@couchdb.apache.org>'].