1.7. Local (non-replicating) Documents — Apache CouchDB® 3.4 Documentation

# 1.7. 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
POST | /{db}/_local_docs/queries | Returns a list of specified non-replicated documents in the database
GET | /{db}/_local/{docid} | Returns the latest revision of the non-replicated document
PUT | /{db}/_local/{docid} | Inserts a new version of the non-replicated document
DELETE | /{db}/_local/{docid} | Deletes the non-replicated document
COPY | /{db}/_local/{docid} | Copies the non-replicated document

## 1.7.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`.

  Parameters:

    - db – Database name

  Request Headers:

    - 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 local 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 local document ID is reached. Optional.

    - end_key_doc_id (string) – Alias for `endkey_docid` param.

    - include_docs (boolean) – Include the full content of the local 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 local documents that match the specified key. Optional.

    - keys (string) – Return only local documents that match the specified keys. Optional.

    - limit (number) – Limit the number of the returned local 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 local 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 local document list started

    - rows (array) – Array of view row objects. By default the information returned contains only the local document ID and revision.

    - total_rows (number) – Number of local 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

  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:

      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.7.2. `/{db}/_local_docs/queries`

POST /{db}/_local_docs/queries

  Querying with specified `keys` will return local documents only. You can also combine `keys` with other query parameters, such as `limit` and `skip`.

  Parameters:

    - db – Database name

  Request Headers:

    - Content-Type –

      - application/json

    - Accept –

      - application/json

  Request JSON Object:

    - queries – An array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular _local_docs request.

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - Transfer-Encoding – `chunked`

  Response JSON Object:

    - results (array) – An array of result objects - one for each query. Each result object contains the same fields as the response to a regular _local_docs request.

  Status Codes:

    - 200 OK – Request completed successfully

    - 400 Bad Request – Invalid request

    - 401 Unauthorized – Read permission required

    - 404 Not Found – Specified database is missing

    - 500 Internal Server Error – Query execution error

Request:

    POST /db/_local_docs/queries HTTP/1.1
    Content-Type: application/json
    Accept: application/json
    Host: localhost:5984

    {
        "queries": [
            {
                "keys": [
                    "_local/localdoc05",
                    "_local/not-exist",
                    "_design/recipe",
                    "spaghetti"
                ]
            }
        ]
    }

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Type: application/json
    Date: Thu, 20 Jul 2023 21:45:37 GMT
    Server: CouchDB (Erlang/OTP)
    Transfer-Encoding: chunked

    {
        "results": [
            {
                "total_rows": null,
                "offset": null,
                "rows": [
                    {
                        "id": "_local/localdoc05",
                        "key": "_local/localdoc05",
                        "value": {
                          "rev": "0-1"
                        }
                    },
                    {
                        "key": "_local/not-exist",
                        "error": "not_found"
                    }
                ]
            },
            {
                "total_rows": null,
                "offset": null,
                "rows": [
                    {
                      "id": "_local/localdoc04",
                      "key": "_local/localdoc04",
                      "value": {
                          "rev": "0-1"
                        }
                    }
                ]
            }
        ]
    }

Note

Similar to _design_docs/queries, /{db}/_local_docs/queries will only return local documents. The difference is `total_rows` and `offset` are always `null`.

## 1.7.3. `/{db}/_local/{docid}`

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