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.
    • descending (boolean) – Return the local documents in descending by key order. Default is false.
    • 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.
    • startkey (string) – Return records starting with the specified key. Optional.
    • 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:
     
    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:

      Response:

      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:

      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}

      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 .

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