src/api/local.rst - couchdb-documentation - Git at Google

 .. 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}`.
	.. 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}`.