You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2018/03/18 04:22:06 UTC
[couchdb-documentation] branch master updated: Document _local_docs
endpoint
This is an automated email from the ASF dual-hosted git repository.
wohali 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 24e242b Document _local_docs endpoint
24e242b is described below
commit 24e242b70e35f7c97a03bff64fb4cfc072802355
Author: jjrodrig <jj...@gmail.com>
AuthorDate: Sat Mar 17 22:41:09 2018 +0100
Document _local_docs endpoint
---
src/api/local.rst | 209 +++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 193 insertions(+), 16 deletions(-)
diff --git a/src/api/local.rst b/src/api/local.rst
index 2caddd8..7350aff 100644
--- a/src/api/local.rst
+++ b/src/api/local.rst
@@ -25,32 +25,209 @@ Local documents have the following limitations:
- Local documents are not replicated to other databases.
-- The ID of the local document must be known for the document to accessed. You
- cannot obtain a list of local documents from the database.
-
- Local documents are not output by views, or the :ref:`api/db/all_docs` view.
+From CouchDB 2.0, Local documents can be listed by using the /db/_local_docs
+endpoint.
+
Local documents can be used when you want to store configuration or
other information for the current (local) instance of a given database.
A list of the available methods and URL paths are provided below:
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | /db/_local/id | Returns the latest revision of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/_local/id | Inserts a new version of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/_local/id | Deletes the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| COPY | /db/_local/id | Copies the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
++--------+------------------------+--------------------------------------------+
+| Method | Path | Description |
++========+========================+============================================+
+| GET, | /db/_local_docs | Returns a list of all the |
+| POST | | non-replicated documents in the database |
++--------+------------------------+--------------------------------------------+
+| GET | /db/_local/id | Returns the latest revision of the |
+| | | non-replicated document |
++--------+------------------------+--------------------------------------------+
+| PUT | /db/_local/id | Inserts a new version of the |
+| | | non-replicated document |
++--------+------------------------+--------------------------------------------+
+| DELETE | /db/_local/id | Deletes the non-replicated document |
++--------+------------------------+--------------------------------------------+
+| COPY | /db/_local/id | Copies the non-replicated document |
++--------+------------------------+--------------------------------------------+
.. _api/local/doc:
+========================
+``/db/_local_docs``
+========================
+
+.. http:get:: /{db}/_local_docs
+ :synopsis: Returns a built-in view of all local (non-replicating) documents
+ in this database
+
+ Returns a JSON structure of all of the local 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 local
+ documents and basic contents, consisting the ID, revision and key. The key
+ is the from the local document's ``_id``.
+
+ :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 design 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
+ design 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 design
+ 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 design documents that match the specified
+ key. *Optional*.
+ :query string keys: Return only design documents that match the specified
+ keys. *Optional*.
+ :query number limit: Limit the number of the returned design 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 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
+ design 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 design document list started
+ :>json array rows: Array of view row objects. By default the information
+ returned contains only the design document ID and revision.
+ :>json number total_rows: Number of design documents in the database. 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**:
+
+ .. code-block:: http
+
+ GET /db/_local_docs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 23 Dec 2017 16:22:56 GMT
+ ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "offset": 0,
+ "rows": [
+ {
+ "id": "_local/localdoc01",
+ "key": "_local/localdoc01",
+ "value": {
+ "rev": "0-1"
+ }
+ },
+ {
+ "id": "_local/localdoc02",
+ "key": "_local/localdoc02",
+ "value": {
+ "rev": "0-1"
+ }
+ },
+ {
+ "id": "_local/localdoc03",
+ "key": "_local/localdoc03",
+ "value": {
+ "rev": "0-1"
+ }
+ },
+ {
+ "id": "_local/localdoc04",
+ "key": "_local/localdoc04",
+ "value": {
+ "rev": "0-1"
+ }
+ },
+ {
+ "id": "_local/localdoc05",
+ "key": "_local/localdoc05",
+ "value": {
+ "rev": "0-1"
+ }
+ }
+ ],
+ "total_rows": 5
+ }
+
+.. http:post:: /{db}/_local_docs
+ :synopsis: Returns certain rows from the built-in view of all local
+ documents
+
+ The ``POST`` to ``_local_docs`` allows to specify multiple keys to be
+ selected from the database. This enables you to request multiple
+ local documents in a single request, in place of multiple
+ :get:`/{db}/_local/{docid}` requests.
+
+ The request body should contain a list of the keys to be returned as an
+ array to a ``keys`` object. For example:
+
+ .. code-block:: http
+
+ POST /db/_local_docs HTTP/1.1
+ Accept: application/json
+ Content-Length: 70
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "keys" : [
+ "_local/localdoc02",
+ "_local/localdoc05"
+ ]
+ }
+
+ The returned JSON is the all documents structure, but with only the
+ selected keys in the output:
+
+ .. code-block:: javascript
+
+ {
+ "total_rows" : 5,
+ "rows" : [
+ {
+ "value" : {
+ "rev" : "0-1"
+ },
+ "id" : "_local/localdoc02",
+ "key" : "_local/localdoc02"
+ },
+ {
+ "value" : {
+ "rev" : "0-1"
+ },
+ "id" : "_local/localdoc05",
+ "key" : "_local/localdoc05"
+ }
+ ],
+ "offset" : 0
+ }
+
``/db/_local/id``
========================
--
To stop receiving notification emails like this one, please contact
wohali@apache.org.