1.7. Local (non-replicating) Documents

    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:

    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

      • –

        • application/json

        • text/plain

      Query Parameters

      • conflicts (boolean) – Includes conflicts information in response. Ignored if include_docs isn’t true. Default is false.

      • endkey (string) – Stop returning records when the specified key is reached. Optional.

      • end_key (string) – Alias for 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.

      • start_key (string) – Alias for startkey param.

      • startkey_docid (string) – Return records starting with the specified local document ID. Optional.

      • 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.

      Status Codes

      • – Request completed successfully

    Request:

    Response:

    POST

    POST _local_docs functionality supports identical parameters and behavior as specified in the 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:

    The returned JSON is the all documents structure, but with only the selected keys in the output:

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

    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 .

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