[Couchdb Wiki] Update of "HTTP_view_API" by SebastianCohnen

[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 "HTTP_view_API" page has been changed by SebastianCohnen.
The comment on this change is: Added TOC; cleanup; fixed some references; fixed some minor stuff at query options.
http://wiki.apache.org/couchdb/HTTP_view_API?action=diff&rev1=28&rev2=29

--------------------------------------------------

+ = HTTP View API =
+ <<TableOfContents(2)>>
+ 
  An introduction to the CouchDB HTTP view API.
  
  == Basics ==
  
- Views are the primary tool used for querying and reporting on Couch documents.
+ Views are the primary tool used for querying and reporting on CouchDB databases. They are defined in !JavaScript (although there are other query servers available). For a more detailed introduction to views see [[Introduction_to_CouchDB_views]].
  
- Views are defined with Javascript functions. Here is the very simplest function:
  
- {{{
- function(doc) {
-   emit(null, null);
- }
- }}}
- 
- See [[Views]] for more information.
- 
- <<Anchor(creating_views)>>
  == Creating Views ==
  
  To create a permanent view, the functions must first be saved into special ''design documents'' (well, they are not really special, we just call them special but in reality, they are regular documents, just with a special ID). The IDs of design documents must begin with ''_design/'' and have a special views attribute that have a ''map'' member and an optional ''reduce'' member to hold the view functions. All the views in one design document are indexed whenever any of them gets queried.
@@ -46, +39 @@

  
  The ''language'' property tells CouchDB the language of the view functions, which it uses to select the appropriate ViewServer (as specified in your couch.ini file). 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.
+ To change a view or multiple view just alter the design document (see HttpDocumentApi) they are stored in and save it as a new revision.
  
- <<Anchor(querying)>>
+ 
  == Access/Query ==
  
  Once this document is saved into a database, then the ''all'' view can be retrieved at the URL:
@@ -109, +103 @@

  }}}
  
  
- <<Anchor(view_parameters)>>
  == 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.
@@ -128, +121 @@

      * skip=number of rows to skip
      * group=true ''Version 0.8.0 and forward''
      * group_level=int
-     * reduce=false ''Trunk only (0.9)''
+     * reduce=false ''(since 0.9)''
-     * include_docs=true ''Trunk only (0.9)''
+     * include_docs=true ''(since 0.9)''
      * inclusive_end=true
    * POST
-     * {"keys": ["key1", "key2", ...]} ''Trunk only (0.9)''
+     * {"keys": ["key1", "key2", ...]} ''(since 0.9)''
  
- ''key'', ''startkey'', and ''endkey'' need to be properly JSON encoded values (for example, startkey="string" for a string value). 
+ ''key'', ''startkey'', and ''endkey'' need to be properly JSON encoded values. For example, startkey="string" for a string value or startkey=["foo", 1, {}]. Be aware that you have to do proper URL encoding on complex values. 
  
  A JSON structure of ''{"keys": ["key1", "key2", ...]}'' can be posted to any user defined view or ''_all_docs'' to retrieve just the view rows matching that set of keys. Rows are returned in the order of the keys specified. Combining this feature with ''include_docs=true'' results in the so-called ''multi-document-fetch'' feature. 
  
@@ -153, +146 @@

  The ''include_docs'' option will include the associated document. Although, the user should keep in mind that there is a race condition when using this option. It is possible that between reading the view data and fetching the corresponding document that the document has changed. If you want to alleviate such concerns you should emit an object with a _rev attribute as in ''emit(key, {"_rev": doc._rev})''. This alleviates the race condition but leaves the possiblity that the returned document has been deleted (in which case, it includes the ''"_deleted": true'' attribute).
  
  The ''inclusive_end'' option controls whether the ''endkey'' is included in the result. It defaults to true.
+ 
  
  == Debugging Views ==
  
@@ -177, +171 @@

   * Keep in mind that the the Futon Web-Client silently adds ''group=true'' to your views.
  
  
- <<Anchor(view_share_code)>>
+ 
  == Sharing Code Between Views ==
  
  There are no development plans to share code/functions between views.  Each view function is stored according to a hash of their byte representation, so it is important that a function does not load any additional code, changing its behavior without changing its byte-string.  Hence the use-case for [[http://github.com/couchapp/couchapp|CouchApp]].
  
+ 
  == View Cleanup ==
  
  Old view output remains on disk until you explicitly run cleanup. To run cleanup for a particular database;
@@ -199, +194 @@

  }}}
  
  In my case, views that were 26G, 27G, 39G, and 40G, shrank to 2.8G, 2.8G, 3.4G, and 3.5G, respectively.  
+ 
  
  ==== Temporary Views ====