| .. Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| .. use this file except in compliance with the License. You may obtain a copy of |
| .. the License at |
| .. |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| .. |
| .. Unless required by applicable law or agreed to in writing, software |
| .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| .. License for the specific language governing permissions and limitations under |
| .. the License. |
| |
| .. _api/local: |
| |
| ================================= |
| Local (non-replicating) Documents |
| ================================= |
| |
| The Local (non-replicating) document interface allows you to create local |
| documents that are not replicated to other databases. These documents can be |
| used to hold configuration or other information that is required specifically |
| on the local CouchDB instance. |
| |
| Local documents have the following limitations: |
| |
| - Local documents are not replicated to other databases. |
| |
| - 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_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 local 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 |
| local 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 local |
| 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 local documents that match the specified |
| key. *Optional*. |
| :query string keys: Return only local documents that match the specified |
| keys. *Optional*. |
| :query number limit: Limit the number of the returned local 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 |
| local 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` |
| :>json number offset: Offset where the local document list started |
| :>json array rows: Array of view row objects. By default the information |
| returned contains only the local document ID and revision. |
| :>json number total_rows: Number of local 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 |
| Server: CouchDB (Erlang/OTP) |
| Transfer-Encoding: chunked |
| |
| { |
| "offset": null, |
| "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": null |
| } |
| |
| .. http:post:: /{db}/_local_docs |
| :synopsis: Returns a built-in view of all local (non-replicating) documents |
| in this database |
| |
| :method:`POST` `_local_docs` functionality supports identical parameters and behavior |
| as specified in the :get:`/{db}/_local_docs` API but allows for the query string |
| parameters to be supplied as keys in a JSON object in the body of the `POST` request. |
| |
| **Request**: |
| |
| .. 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" : null, |
| "rows" : [ |
| { |
| "value" : { |
| "rev" : "0-1" |
| }, |
| "id" : "_local/localdoc02", |
| "key" : "_local/localdoc02" |
| }, |
| { |
| "value" : { |
| "rev" : "0-1" |
| }, |
| "id" : "_local/localdoc05", |
| "key" : "_local/localdoc05" |
| } |
| ], |
| "offset" : null |
| } |
| |
| ``/db/_local/id`` |
| ================= |
| |
| .. http:get:: /{db}/_local/{docid} |
| :synopsis: Returns the latest revision of the local document |
| |
| Gets the specified local document. The semantics are identical to accessing |
| a standard document in the specified database, except that the document is |
| not replicated. See :get:`/{db}/{docid}`. |
| |
| .. http:put:: /{db}/_local/{docid} |
| :synopsis: Inserts a new version of the local document |
| |
| Stores the specified local document. The semantics are identical to storing |
| a standard document in the specified database, except that the document is |
| not replicated. See :put:`/{db}/{docid}`. |
| |
| .. http:delete:: /{db}/_local/{docid} |
| :synopsis: Deletes the local document |
| |
| Deletes the specified local document. The semantics are identical to |
| deleting a standard document in the specified database, except that the |
| document is not replicated. See :delete:`/{db}/{docid}`. |
| |
| .. http:copy:: /{db}/_local/{docid} |
| :synopsis: Copies the local document within the same database |
| |
| Copies the specified local document. The semantics are identical to copying |
| a standard document in the specified database, except that the document is |
| not replicated. See :copy:`/{db}/{docid}`. |