CouchDB – View/GET Document

To view or retrieve a document from a CouchDB database, you can send an HTTP GET request to the CouchDB REST API or open the document in the CouchDB Fauxton web interface. This tutorial demonstrates both methods.

CouchDB GET Document REST API Syntax

Send an HTTP GET request using the database name and document ID in the URL.

http://hostname/database_name/document_id/

The general request format is:

</>
Copy
GET /database_name/document_id

Replace hostname with the CouchDB server address, database_name with the database, and document_id with the exact ID of the document to retrieve.

GET Document 0005 from the tutorialkart Database

We have CouchDB running on the local computer. Therefore, we shall use 127.0.0.1:5984 as the hostname and port.

We will use an existing database named tutorialkart.

Let us retrieve the document whose ID is 0005.

The resulting URL for the GET request is:

http://127.0.0.1:5984/tutorialkart/0005/

In Postman, select the GET method, enter the URL, and send the request. You can also use another REST client or a command-line tool such as curl.

CouchDB - GET document

If the document exists and the request is authorized, CouchDB returns an HTTP 200 OK response containing the document as JSON. The response normally includes the reserved _id and _rev fields together with the document’s application data.

Retrieve a CouchDB Document with curl

The following command sends the same request from a terminal:

</>
Copy
curl http://127.0.0.1:5984/tutorialkart/0005

A successful response resembles the following example. The exact fields and revision value depend on the stored document.

{
  "_id": "0005",
  "_rev": "1-example-revision-value",
  "name": "Sample document"
}

If CouchDB requires authentication, provide valid credentials with the request. Avoid placing production credentials directly in scripts or shell history.

</>
Copy
curl -u username:password http://127.0.0.1:5984/tutorialkart/0005

CouchDB GET Document Response Codes

  • 200 OK: CouchDB found the document and returned its JSON content.
  • 400 Bad Request: The request URL or query parameters are invalid.
  • 401 Unauthorized: Authentication is required or the supplied credentials are invalid.
  • 403 Forbidden: The authenticated user does not have permission to read the database or document.
  • 404 Not Found: The database or document ID does not exist, or the document has been deleted.

For a missing document, CouchDB commonly returns a JSON error object similar to:

{
  "error": "not_found",
  "reason": "missing"
}

Retrieve Selected Document Fields

By default, CouchDB returns the complete document. When supported by the CouchDB version and endpoint configuration, you can use the fields query parameter to request selected fields. The parameter value is a JSON array and must be URL-encoded by the client.

</>
Copy
curl --get \
  --data-urlencode 'fields=["_id","name"]' \
  http://127.0.0.1:5984/tutorialkart/0005

Requesting only the required fields can reduce response size when documents contain many properties.

View a CouchDB Document in Fauxton

You can also view a document in a CouchDB database through the Fauxton web interface.

Open http://hostname/_utils/ in your browser. In this example, the URL is http://127.0.0.1:5984/_utils/.

Open the list of databases from the left panel and select the database that contains the document. Display the database documents using the available document or table view, and then select the required document ID.

When you select the document, Fauxton opens an editor that displays the JSON document, including its _id, current _rev, and stored fields.

CouchDB Document ID Encoding

A document ID is part of the request path. If the ID contains spaces, slashes, question marks, hash characters, or other reserved URL characters, encode the ID before placing it in the URL. Otherwise, CouchDB or the HTTP client may interpret part of the ID as a path separator or query string.

For example, an application should URL-encode the document ID customer/1001 before sending the request rather than inserting the slash directly into the path.

CouchDB GET Document FAQs

Does a GET request modify the CouchDB document?

No. A standard GET request reads the document and does not change its stored content or revision.

Why does CouchDB return 404 when the document ID appears correct?

Check the database name, letter case, document ID, URL encoding, and whether the document was deleted. A request to a missing database can also return a not-found response.

What is the _rev field in a CouchDB document?

The _rev value identifies the current revision of the document. CouchDB uses revisions for update conflict detection. Reading a document does not create a new revision.

Can I retrieve a deleted CouchDB document?

A normal document GET request does not return the previous content of a deleted document. CouchDB retains a deletion marker for replication and conflict handling, but applications should not treat it as a backup of the deleted data.

CouchDB GET Document Summary

In this CouchDB Tutorial, we learned how to retrieve a CouchDB document by sending an HTTP GET request to /database_name/document_id. We also used curl, reviewed common response codes, and viewed the same JSON document through the CouchDB Fauxton web interface.