To create a new design document with one or more views, you can upload the corresponding design document using the REST API with the definition in place. The format of this command is as shown in the table below:
| Method | PUT /bucket/_design/design-doc |
| Request Data | Design document definition (JSON) |
| Response Data | Success and stored design document ID |
| Authentication Required | optional |
| Return Codes | |
| 201 | Document created successfully. |
| 401 | The item requested was not available using the supplied authorization, or authorization was not supplied. |
When creating a design document through the REST API it is
recommended that you create a development
(dev) view. It is recommended that you
create a dev design document and views first, and then check
the output of the configured views in your design document. To
create a dev view you must explicitly use
the dev_ prefix for the design document
name.
For example, using curl, you can create a
design document, byfield, by creating a text
file (with the name byfield.ddoc) with the
design document content using the following command:
shell> curl -X PUT -H 'Content-Type: application/json' \ http://user:password@localhost:8092/sales/_design/dev_byfield' \ -d @byfield.ddoc
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 will
be rejected.
http://
user:password@localhost:8092/sales/_design/dev_byfield'
The URL, including authentication information, of the bucket
where you want the design document uploaded. The
user and password
should either be the Administration privileges, or for SASL
protected buckets, the bucket name and bucket password. If
the bucket does not have a password, then the authentication
information is not required.
The view being accessed in this case is a development
view. To create a development view, you
must use the dev_
prefix to the view name.
As a PUT command, the URL is also
significant, in that the location designes 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 that will be created
dev_byfield.
-d @byfield.ddoc
Specifes that the data payload should be loaded from the
file byfield.ddoc.
If successful, the HTTP response code will be 201 (created). The
returned JSON will contain the field ok and
the ID of the design document created:
{ "ok":true, "id":"_design/dev_byfield" }
The design document will be validated before it is 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.
In the event of an error, the returned JSON will include the
field error with a short description, and the
field reason with a longer description of the
problem.
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. For example:
{"views":{"byloc":{"map":"function (doc, meta) {\n if (meta.type == \"json\") {\n emit(doc.city, doc.sales);\n } else {\n emit([\"blob\"]);\n }\n}"}}}Formatted, the design document looks like this:
{ "views" : { "byloc" : { "map" : "function (doc, meta) {\n if (meta.type == \"json\") {\n emit(doc.city, doc.sales);\n } else {\n emit([\"blob\"]);\n }\n}" } } }
The top-level views field lists one or more
view definitions (the byloc view in this
example), and for each view, a corresponding
map() function.