CouchDB - Creating a Document

CouchDB - Creating a Document

Documents are the core data structure in CouchDB, where data is stored as flexible JSON objects. Unlike tables in a relational database, documents in the same database do not need to share the same structure.

Each document requires a unique _id field within its database. You have two main approaches for creating a document:

• PUT Request: You specify the _id yourself. This is useful when the document ID has a natural meaning, like user:jane.doe.
• POST Request: You let CouchDB automatically generate a unique ID (a UUID). This is the most common and recommended approach to avoid ID collisions.

Creating a Document using the HTTP API (with cURL)

To create a document, you send a PUT or POST request to a database endpoint with the JSON data in the request body. It is crucial to set the Content-Type header to application/json.

Example 1: Let CouchDB Generate the ID (POST)

This is the preferred method for creating new documents. We POST our JSON object to the database’s URL.

$ curl -X POST http://127.0.0.1:5984/user_profiles -u admin:secret \
-H 'Content-Type: application/json' \
-d '{"name": "John Smith", "email": "john.smith@example.com", "plan": "premium", "registered_at": "2023-10-27T10:00:00Z"}'

{
    "ok": true,
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "rev": "1-a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4"
}

The response from CouchDB includes:

• "ok": true: Indicates the operation was successful.
• "id": The unique ID automatically generated by CouchDB for this new document.
• "rev": The first revision ID of the document. This _rev token is essential for updating or deleting the document later, as it is CouchDB’s mechanism for optimistic concurrency control.

Example 2: Specify Your Own ID (PUT)

If you need to define a specific ID, you can use a PUT request and include the ID in the URL.

$ curl -X PUT http://127.0.0.1:5984/user_profiles/user:jane.doe -u admin:secret \
-H 'Content-Type: application/json' \
-d '{"name": "Jane Doe", "email": "jane.doe@example.com", "plan": "free", "registered_at": "2023-10-27T11:30:00Z"}'

{
    "ok": true,
    "id": "user:jane.doe",
    "rev": "1-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1"
}

Verification

You can retrieve the document by sending a GET request to its URL to verify its creation.

$ curl -X GET http://127.0.0.1:5984/user_profiles/user:jane.doe -u admin:secret

{
    "_id": "user:jane.doe",
    "_rev": "1-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "plan": "free",
    "registered_at": "2023-10-27T11:30:00Z"
}

Creating a Document using Fauxton

Fauxton provides a convenient JSON editor for creating and modifying documents.

• In the Fauxton UI, click on the database you want to add a document to (e.g., user_profiles) from the list on the left.
• Click the + button in the top menu bar and select New Doc.
• An editor will appear with a template containing a randomly generated _id. You can either keep this ID or replace it with a custom string.
• Delete the template content and add your own valid JSON data in the editor area.
• Click the Create Document button on the right to save the document.

Common Errors

A common error is Document update conflict. This occurs if you use PUT with an _id that already exists in the database. Creating a new version of an existing document is an update, not a creation, and requires you to provide the latest _rev field in the JSON body. We will cover updates in a later chapter.