1.6. 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 /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, POST	/db/_local_docs	Returns a list of all the 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

1.6.1. `/db/_local_docs`¶

GET /{db}/_local_docs¶

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.

Request Headers:
Parameters:	db – Database name
	Accept – application/json text/plain
Query Parameters:
	conflicts (boolean) – Includes conflicts information in response. Ignored if include_docs isn’t `true`. Default is `false`. descending (boolean) – Return the design documents in descending by key order. Default is `false`. endkey (string) – Stop returning records when the specified key is reached. Optional. end_key (string) – Alias for endkey param. endkey_docid (string) – Stop returning records when the specified design document ID is reached. Optional. end_key_doc_id (string) – Alias for endkey_docid param. include_docs (boolean) – Include the full content of the design documents in the return. Default is `false`. inclusive_end (boolean) – Specifies whether the specified end key should be included in the result. Default is `true`. key (string) – Return only design documents that match the specified key. Optional. keys (string) – Return only design documents that match the specified keys. Optional. limit (number) – Limit the number of the returned design documents to the specified number. Optional. skip (number) – Skip this number of records before starting to return the results. Default is `0`. startkey (string) – Return records starting with the specified key. Optional. start_key (string) – Alias for startkey param. startkey_docid (string) – Return records starting with the specified design document ID. Optional. start_key_doc_id (string) – Alias for startkey_docid param. update_seq (boolean) – Response includes an `update_seq` value indicating which sequence id of the underlying database the view reflects. Default is `false`.
Response Headers:
	Content-Type – application/json text/plain; charset=utf-8
Response JSON Object:
	offset (number) – Offset where the design document list started rows (array) – Array of view row objects. By default the information returned contains only the design document ID and revision. total_rows (number) – Number of design documents in the database. Note that this is not the number of rows returned in the actual query. update_seq (number) – Current update sequence for the database
Status Codes:	200 OK – Request completed successfully

Request:

GET /db/_local_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

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
}

POST /{db}/_local_docs¶

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:

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:

{
    "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
}

1.6.2. `/db/_local/id`¶

GET /{db}/_local/{docid}¶: 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}.

PUT /{db}/_local/{docid}¶: 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}.

DELETE /{db}/_local/{docid}¶: 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}.

COPY /{db}/_local/{docid}¶: 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}.

1.6. Local (non-replicating) Documents¶

1.6.1. /db/_local_docs¶

1.6.2. /db/_local/id¶

1.6.1. `/db/_local_docs`¶

1.6.2. `/db/_local/id`¶