[Couchdb Wiki] Update of "HttpViewApi" by NoahSlater

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The following page has been changed by NoahSlater:
http://wiki.apache.org/couchdb/HttpViewApi

The comment on the change is:
Copied from original CouchDB wiki

New page:
An introduction to the CouchDB HTTP view API.

== Basics ==

Views are the primary tool used for querying and reporting on Couch documents.

Views are defined with Javascript functions. Here is the very simplest function:

{{{
function(doc) {
  map(null, doc);
}
}}}

See ["Views"] for more information.

== Creating Views ==

To create a permanent view, the functions must first be saved into special ''design documents''. The IDs of design documents must begin with ''_design/'' and have a special views attribute that holds all the view functions.

A design document that defines ''all'' and ''by_lastname'' views might look like this:

{{{
{
  "_id":"_design/company",
  "_rev":"12345",
  "language": "text/javascript",
  "views":
  {
    "all": "function(doc) { if (doc.Type == 'customer')  map(null, doc) }"
    "by_lastname": "function(doc) { if (doc.Type == 'customer')  map(doc.LastName, doc) }"
  }
}
}}}

The ''language'' property tells CouchDB the content type of the view functions, which it uses to select the appropriate ViewServer. The default is to assume Javascript, so this property can be omitted for Javascript views.

== Altering/Changing Views ==

To change a view or multiple view just alter the document (see HttpDocumentApi) they are stored in and save it as a new revision.

== Access/Query ==

Once this document is saved into a database, then the ''all'' view can be retrieved at the URL:

  http://localhost:5984/database/_view/company/all

Example:

{{{
GET /some_database/_view/company/all HTTP/1.0
Date: Thu, 17 Aug 2006 05:39:28 +0000GMT
}}}

And will result in the following response:

{{{
 HTTP/1.1 200 OK
 Date: Thu, 17 Aug 2006 05:39:28 +0000GMT
 Content-Length: 318
 Connection: close

 {
    "total_rows": 3,
    "offset": 0,
    "rows": [{
        "id":"64ACF01B05F53ACFEC48C062A5D01D89",
        "key": null,
        "value": {
          "LastName":"Katz",
          "FirstName":"Damien",
          "Address":"2407 Sawyer drive, Charlotte NC",
          "Phone":012555754211
        }
      }, {
        "id":"5D01D8964ACF01B05F53ACFEC48C062A",
        "key": null,
        "value": {
          "LastName":"Kerr",
          "FirstName":"Wayne",
          "Address":"123 Fake st., such and such",
          "Phone":88721320939
        }
      }, {
        "id":"EC48C062A5D01D8964ACF01B05F53ACF",
        "key": null,
        "value":
        {
          "LastName":"McCracken",
          "FirstName":"Phil",
          "Address":"1234 Fake st., such and such",
          "Phone":7766552342
        }
      }
    ]
 }
}}}

== Ad Hoc Views ==

One-off queries (eg. views you don't want to save in the CouchDB database) can be done via the special ''view _temp_view'':

{{{
POST /some_database/_temp_view  HTTP/1.0
Content-Length: 48
Date: Mon, 10 Sep 2007 17:11:10 +0200
Content-Type: text/javascript

function(doc) { if (doc.foo=='bar') { map(null, doc.foo); } }
}}}

Could result in the following response:

{{{
{
  "total_rows": 1,
  "offset": 0,
  "rows": [{
      "id": "AE1AD84316B903AD46EF396CAFE8E50F",
      "key": null,
      "value": "bar"
    }
  ]
}
}}}

== Querying Options ==

Columns can be a list of values, there is no set limit to the number of values or amount of data that columns can hold.

The following URL query arguments are allowed:

  * key=keyvalue
  * startkey=keyvalue
  * startkey_docid=docid
  * endkey=keyvalue
  * count=max rows to return
  * update=false
  * descending=true
  * skip=rows to skip

''key'', ''startkey'', and ''endkey'' need to be properly JSON encoded values (for example, startkey="string" for a string value).

If you specify ''?count=0'' you don't get any data, but all meta-data for this View. The number of documents in this View for example.

The ''skip'' option should only be used with small values, as skipping a large range of documents this way is inefficient (it scans the index from the startkey and then skips N elements, but still needs to read all the index values to do that). For efficient paging use ''startkey'' and/or ''startkey_docid''.

The ''update'' option can be used for higher performance at the cost of possibly not seeing the all latest data. If you set the ''update'' option to ''false'', CouchDB will not perform any refreshing on the view that may be necessary.

View rows are sorted by the key; specifying ''descending=true'' will reverse their order. Note that the ''descending'' option is applied before any key filtering, so you may need to swap the values of the ''startkey'' and ''endkey'' options to get the expected results. The sorting itself is described in ViewCollation.

== Debugging Views ==

When creating views, CouchDB will check the syntax of the submitted JSON, but the view functions themselves will not be syntax checked by the Javascript interpreter. And if any one of the view functions has a syntax error, none of the view functions in that design document will execute. Perhaps test your functions in a temporary view before saving them in the database.