Creating Design Documents

Creating Design Documents

To create a new design document, use the PUT /[bucket-name]/_design/[ddoc-name] HTTP method and URI on the 8092 port.

Description

Design documents are used to store one or more view definitions. Views can be defined within a design document and uploaded to Couchbase Server.

Design documents are validated before being created or updated in the system. The validation checks for valid JavaScript and for the use of valid built-in reduce functions. Any validation failure is reported as an error.

The format of the design document should include all the views defined in the design document, incorporating both the map and reduce functions for each named view.

Note: When creating a design document, first create a dev design document and views and then check the output of the configured views in your design document. To create a development view, you must explicitly use the dev_ prefix for the design document name.

HTTP method and URI

PUT /[bucket-name]/_design/[ddoc-name]
Request data Design document definition (JSON)
Response data Success and stored design document ID
Authentication required Optional

Syntax

Curl request syntax:

curl -X PUT
  -u [admin]:[password]
  -H "Content-Type: application/json"
  http://[localhost]:8092/[bucket-name]/_design/[ddoc-name]			

Example

A design document, byfield can be created using a text file (byfield.ddoc ) with the design document content. In this example, the view is a development view. Development view names must have the dev_.

Curl request example:

curl -X PUT
  -H "Content-Type: application/json" \
  http://Administrator:password@10.5.2.117:8092/sales/_design/dev_byfield \
  -d @byfield.ddoc 

As a PUT command, the URL is also significant,since the location designates the name of the design document. In the example, the URL includes the name of the bucket ( sales ) and the name of the design document being created is dev_byfield.

In the above example:

  • -X PUT

    Indicates that an HTTP PUT operation is requested.

  • -H "Content-Type: application/json"

    Specifies the HTTP header information. Couchbase Server requires the information to be sent and identified as the application/json datatype. Information not supplied with the content-type set in this manner is rejected.

  • http://user:password@10.5.2.117:8092/sales/_design/dev_byfield

    Specifies the URL, including the authentication information of the bucket where you want the design document uploaded. The user and password are either the administration privileges or the bucket name and bucket password for SASL protected buckets. If the bucket does not have a password, then authentication information is not required.

  • -d @byfield.ddoc

    Specifies that the data payload should be loaded from the file byfield.ddoc.

Response

If successful, the HTTP response code is 201 OK (created) and the returned JSON fields are ok and ID.

{
    "ok":true,
    "id":"_design/dev_byfield"
}

The top-level views field lists one or more view definitions, and for each view, a corresponding map() function. For example:

{
   "views" : {
      "byfield" : {
         "map" : "function (doc, meta) {\n  if (meta.type == \"json\") 
         	{\n    emit(doc.city, doc.sales);\n  } else 
         	{\n    emit([\"blob\"]);\n  }\n}"
      }
   }
}

Response codes

Response codes Description
201 Document created successfully.
401 The item requested not available using the supplied authorization or authorization not supplied.

In the event of an error, the returned JSON includes the field error with a short description and the field reason with a longer description of the problem.