couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Couchdb Wiki] Update of "HTTP_view_API" by SebastianCohnen
Date Sun, 28 Feb 2010 18:42:56 GMT
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 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
@@ -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 [[|CouchApp]].
  == View Cleanup ==
  Old view output remains on disk until you explicitly run cleanup. To run cleanup for a particular
@@ -199, +194 @@

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

View raw message