You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@couchdb.apache.org by GitBox <gi...@apache.org> on 2018/03/18 04:22:05 UTC
[GitHub] wohali closed pull request #260: Document _local_docs endpoint
wohali closed pull request #260: Document _local_docs endpoint
URL: https://github.com/apache/couchdb-documentation/pull/260
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
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``
========================
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services