Documents are CouchDB’s central data structure. Contents of the database will be stored in the form of Documents instead of tables. You can create these documents using cURL utility provided by CouchDB, as well as Futon. This chapter covers the ways to create a document in a database.

Each document in CouchDB has a unique ID. You can choose your own ID that should be in the form of a string. Generally, UUID (Universally Unique IDentifier) is used, which are random numbers that have least chance of creating a duplicate. These are preferred to avoid collisions.

Creating a Document using cURL Utility

You can create a document in CouchDB by sending an HTTP request to the server using PUT method through cURL utility. Following is the syntax to create a document.

$ curl -X PUT http://127.0.0.1:5984/database name/"id" -d '' { document} ''

Using −X, we can specify a custom request method of HTTP we are using, while communicating with the HTTP server. In this case, we are using PUT method. When we use the PUT method, the content of the url specifies the object name we are creating using the HTTP request. Here we have to send the following −

• The name of the database name in which we are creating the document.

• The document id.

• The data of the document. −d option is used to send the data/document through HTTP request. While writing a document simply enter your Field-Value pairs separated by colon, within flower brackets as shown below −

{
   Name : Raju
   age : 23
   Designation : Designer
}

Example

Using the above given syntax if you want to create a document with id 001 in a database with name my_database, you can create it as shown below.

$ curl -X PUT http://127.0.0.1:5984/my_database/"001" -d
''{ " Name " : " Raju " , " age " :" 23 " , " Designation " : " Designer " }''

{"ok":true,"id":"001","rev":"1-1c2fae390fa5475d9b809301bbf3f25e"}

The response of CouchDB to this request contains three fields −

• “ok”, indicating the operation was successful.

• “id”, which stores the id of the document and

• “rev”, this indicates the revision id. Every time you revise (update or modify) a document a _rev value will be generated by CouchDB. If you want to update or delete a document, CouchDB expects you to include the _rev field of the revision you wish to change. When CouchDB accepts the change, it will generate a new revision number. This mechanism ensures concurrency control.

Verification

If you want to view the created document you can get it using the document as shown below.

$ curl -X GET http://127.0.0.1:5984/my_database/001
{
   "_id": "001",
   "_rev": "1-3fcc78daac7a90803f0a5e383f4f1e1e",
   "Name": "Raju",
   "age": 23,
   "Designation": "Designer"
}

Creating a Document using Futon

To Create a document open the http://127.0.0.1:5984/_utils/ url to get an Overview/index page of CouchDB as shown below.

Select the database in which you want to create the document. Open the Overview page of the database and select New Document option as shown below.

When you select the New Document option, CouchDB creates a new database document, assigning it a new id. You can edit the value of the id and can assign your own value in the form of a string. In the following illustration, we have created a new document with an id 001.

In this page, you can observe three options − save Document, Add Field and Upload Attachment.

Add Field to the Document

To add field to the document click on Add Field option. After creating a database, you can add a field to it using this option. Clicking on it will get you a pair of text boxes, namely, Field, value. You can edit these values by clicking on them. Edit those values and type your desired Field-Value pair. Click on the green button to save these values.

In the following illustration, we have created three fields Name, age and, Designation of the employee.

Save Document

You can save the changes made to the document by clicking on this option. After saving, a new id _rev will be generated as shown below.