couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "HTTP_view_API" by BenjaminYoung
Date Mon, 22 Nov 2010 20:05:26 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 BenjaminYoung.
The comment on this change is: added note about "disappearing" total_rows & offset.
http://wiki.apache.org/couchdb/HTTP_view_API?action=diff&rev1=47&rev2=48

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

  An introduction to the CouchDB HTTP view API.
  
  == Basics ==
- 
  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]].
  
- 
  == 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.
  
  A design document that defines ''all'', ''by_lastname'', and ''total_purchases'' views might
look like this:
@@ -36, +33 @@

    }
  }
  }}}
- 
  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 design document (see HttpDocumentApi) they
are stored in and save it as a new revision. This causes all the views in that design document
to be rebuilt on the next access in case the view code has been changed.
  
- 
  == Access/Query ==
- 
  Once this document is saved into a database, then the ''all'' view can be retrieved at the
URL:
  
-   http://localhost:5984/database/_design/company/_view/all
+  . http://localhost:5984/database/_design/company/_view/all
  
  Example:
+ 
  {{{
  GET /some_database/_design/company/_view/all HTTP/1.0
  Date: Thu, 17 Aug 2006 05:39:28 +0000GMT
  }}}
- 
  And will result in the following response:
  
  {{{
@@ -100, +92 @@

      ]
   }
  }}}
- 
- 
  == 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 for '''GET/HEAD''' requests are allowed:
- 
- ||'''Parameter'''||'''Value'''||'''Default value'''||'''Description'''||
+ ||'''Parameter''' ||'''Value''' ||'''Default value''' ||'''Description''' ||
- ||'''key'''||''key-value''||''-''||'''Must''' be a proper URL encoded JSON value||
+ ||'''key''' ||''key-value'' ||''-'' ||'''Must''' be a proper URL encoded JSON value ||
- ||'''startkey'''||''key-value''||''-''||'''Must''' be a proper URL encoded JSON value||
+ ||'''startkey''' ||''key-value'' ||''-'' ||'''Must''' be a proper URL encoded JSON value
||
- ||'''startkey_docid'''||''document id''||''-''||document id to start with||
+ ||'''startkey_docid''' ||''document id'' ||''-'' ||document id to start with ||
- ||'''endkey'''||''key-value''||''-''||'''Must''' be a proper URL encoded JSON value||
+ ||'''endkey''' ||''key-value'' ||''-'' ||'''Must''' be a proper URL encoded JSON value ||
- ||'''endkey_docid'''||''endkey_docid''||''-''||last document id to include in the output||
+ ||'''endkey_docid''' ||''endkey_docid'' ||''-'' ||last document id to include in the output
||
- ||'''limit'''||''number of docs''||''-''||Limit the number of documents in the output||
+ ||'''limit''' ||''number of docs'' ||''-'' ||Limit the number of documents in the output
||
- ||'''stale'''||''ok''||''-''||If '''stale=ok''' is set CouchDB will not refresh the view
even if it is stalled.||
+ ||'''stale''' ||''ok'' ||''-'' ||If '''stale=ok''' is set CouchDB will not refresh the view
even if it is stalled. ||
- ||'''descending'''||''true / false''||''false''||reverse the output||
+ ||'''descending''' ||''true / false'' ||''false'' ||reverse the output ||
- ||'''skip'''||''number of docs''||''0''||skip ''n'' number of documents||
+ ||'''skip''' ||''number of docs'' ||''0'' ||skip ''n'' number of documents ||
- ||'''group'''||''true''||''false''||The group option controls whether the reduce function
reduces to a set of distinct keys or to a single result row.||
+ ||'''group''' ||''true'' ||''false'' ||The group option controls whether the reduce function
reduces to a set of distinct keys or to a single result row. ||
- ||'''group_level'''||''number''||''-''||''see below''||
+ ||'''group_level''' ||''number'' ||''-'' ||''see below'' ||
- ||'''reduce'''||''true / false''||''true''||use the reduce function of the view. It defaults
to true, if a reduce function is defined and to false otherwise.||
+ ||'''reduce''' ||''true / false'' ||''true'' ||use the reduce function of the view. It defaults
to true, if a reduce function is defined and to false otherwise. ||
- ||'''include_docs'''||''true / false''||''false''||automatically fetch and include the document
which emitted each view entry||
+ ||'''include_docs''' ||''true / false'' ||''false'' ||automatically fetch and include the
document which emitted each view entry ||
- ||'''inclusive_end'''||''true / false''||''true''||Controls whether the endkey is included
in the result. It defaults to true.||
+ ||'''inclusive_end''' ||''true / false'' ||''true'' ||Controls whether the endkey is included
in the result. It defaults to true. ||
+ 
+ 
+ 
  
  Since 0.9 you can also issue '''POST''' requests to views where you can send the following
JSON structure in the body:
  
  {{{
  {"keys": ["key1", "key2", ...]}
  }}}
- 
- ''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. 
+ ''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. 
+ 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.
  
  If you specify ''?limit=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 you'll need
to use ''startkey'' and ''limit''. If you expect to have multiple documents emit identical
keys, you'll need to use ''startkey_docid'' in addition to ''startkey'' to paginate correctly.
The reason is that ''startkey'' alone will no longer be sufficient to uniquely identify a
row. 
+ 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 you'll need
to use ''startkey'' and ''limit''. If you expect to have multiple documents emit identical
keys, you'll need to use ''startkey_docid'' in addition to ''startkey'' to paginate correctly.
The reason is that ''startkey'' alone will no longer be sufficient to uniquely identify a
row.
  
  The ''stale'' option can be used for higher performance at the cost of possibly not seeing
the all latest data. If you set the ''stale'' option to ''ok'', CouchDB may not perform any
refreshing on the view that may be necessary. Using this option essentially tells CouchDB
that if a reference to the view index is available in memory (ie, if the view has been queried
at least once since couch was started), go ahead and use it, even if it may be out of date.
The result is that for a highly trafficked view, end users can see lower latency, although
they may not get the latest data. However, if there is no view index pointer in memory, the
behavior with this option is that same as the behavior without the option. If your application
use ''stale=ok'' for end-user queries, you'll need either a cron or a notification process
like the one described in [[Regenerating_views_on_update]], which queries without ''stale=ok''
to ensure that the view is kept reasonably up to date.
  
@@ -151, +141 @@

  The ''inclusive_end'' option controls whether the ''endkey'' is included in the result.
It defaults to true.
  
  In a reduced view result, you need to use `startkey` and `endkey` to match rows instead
of the `key` parameter.
+ 
+ Note: If you use `group_level`, `total_rows` and `offset` will be omitted from the results
(this is done to avoid scanning the entire tree.
  
  == Getting Information about Design Documents (and their Views) ==
  You can query the design document (''_design/test'' in this case) by GET for some information
on the view:
+ 
  {{{
  curl -X GET http://localhost:5984/databasename/_design/test/_info
  }}}
  will produce something like this:
+ 
  {{{#!highlight javascript
  {
-     "name": "test", 
+     "name": "test",
      "view_index": {
-         "compact_running": false, 
+         "compact_running": false,
-         "disk_size": 4188, 
+         "disk_size": 4188,
-         "language": "javascript", 
+         "language": "javascript",
-         "purge_seq": 0, 
+         "purge_seq": 0,
-         "signature": "07ca32cf9b0de9c915c5d9ce653cdca3", 
+         "signature": "07ca32cf9b0de9c915c5d9ce653cdca3",
-         "update_seq": 4, 
+         "update_seq": 4,
-         "updater_running": false, 
+         "updater_running": false,
-         "waiting_clients": 0, 
+         "waiting_clients": 0,
          "waiting_commit": false
      }
  }
  }}}
- 
  === Meaning of the status hash ===
- ||'''Key'''||<-2>'''Description'''||
+ ||'''Key''' ||||<style="text-align: center;">'''Description''' ||
- ||''name''||<-2>Name of the design document without the ''_design'' prefix (string)||
+ ||''name'' ||||<style="text-align: center;">Name of the design document without the
''_design'' prefix (string) ||
- ||''view_index''||<-2>Contains information on the views (JSON object)||
+ ||''view_index'' ||||<style="text-align: center;">Contains information on the views
(JSON object) ||
- || ||'''Subkeys of''' '''''view_index'''''||'''Description'''||
+ || ||'''Subkeys of''' '''''view_index''''' ||'''Description''' ||
- || ||''signature''||The MD5 representation of the views of a design document (string)||
+ || ||''signature'' ||The MD5 representation of the views of a design document (string) ||
- || ||''language''||Language of the views used (string)||
+ || ||''language'' ||Language of the views used (string) ||
- || ||''disk_size''||Size in Bytes of the views on disk (int)||
+ || ||''disk_size'' ||Size in Bytes of the views on disk (int) ||
- || ||''updater_running''||Indicates if an update process is running (boolean)||
+ || ||''updater_running'' ||Indicates if an update process is running (boolean) ||
- || ||''compact_running''||Indicates if view compaction is running (boolean)||
+ || ||''compact_running'' ||Indicates if view compaction is running (boolean) ||
- || ||''waiting_commit''||Indicates if this view is ahead of db commits or not (boolean)||
+ || ||''waiting_commit'' ||Indicates if this view is ahead of db commits or not (boolean)
||
- || ||''waiting_clients''||How many clients are waiting on views of this design document
(int)||
+ || ||''waiting_clients'' ||How many clients are waiting on views of this design document
(int) ||
- || ||''update_seq''||The update sequence of the corresponding database that has been indexed
(int)||
+ || ||''update_seq'' ||The update sequence of the corresponding database that has been indexed
(int) ||
- || ||''purge_seq''||The purge sequence that has been processed (int)||
+ || ||''purge_seq'' ||The purge sequence that has been processed (int) ||
  
  
  == 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.
  
  As of r660140 there is a log function available in the views, which logs to the couch.log.
It can be helpful for debugging but hinders performance, so it should be used sparingly in
production systems.
@@ -202, +194 @@

    "map": "function(doc) { log(doc); }"
  }
  }}}
- 
- 
  Playing with (malformed) views is currently the best way to bring the couchdb server in
an unstable state. Also the Futon Web-Client does not interact very well with errors in views.
Some suggestions for view development:
  
   * Develop views on a separate server instance, not on your production systems
@@ -213, +203 @@

   * Work with only a few hundred documents for testing.
   * Keep in mind that the the Futon Web-Client silently adds ''group=true'' to your views.
  
- 
- 
  == 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]].
  
  Since CouchDB 0.11 it is possible to share code in {{{show}}}, {{{list}}}, {{{update}}},
and {{{validation}}} functions. See [[CommonJS_Modules]] for details.
  
- 
  == View Cleanup ==
- 
  Old view output remains on disk until you explicitly run cleanup. To run cleanup for a particular
database;
  
  {{{
  POST /some_database/_view_cleanup
  }}}
- 
  == View Compaction ==
- 
  If you have very large views or are tight on space, you might consider [[Compaction]] as
well. To run compact for a particular view on a particular database;
  
  {{{
  POST /some_database/_compact/designname
  }}}
- 
- In my case, views that were 26G, 27G, 39G, and 40G, shrank to 2.8G, 2.8G, 3.4G, and 3.5G,
respectively.  
+ 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 ====
- 
  One-off queries (eg. views you don't want to save in the CouchDB database) can be done via
the special view ''_temp_view''. Temporary views are only good during development. Final code
should not rely on them as they are very expensive to compute each time they get called and
they get increasingly slower the more data you have in a database. If you think you can't
solve something in a permanent view that you can solve in an ad-hoc view, you might want to
reconsider. (TODO: add typical examples and solutions).
  
  {{{
@@ -254, +234 @@

  {
    "map" : "function(doc) { if (doc.foo=='bar') { emit(null, doc.foo); } }"
  }
- 
  }}}
- 
  Could result in the following response:
  
  {{{#!highlight javascript
@@ -271, +249 @@

    ]
  }
  }}}
- 
  NOTE: couchdb 0.9.0 requires {{{Content-Type: application/json}}} on POSTs to _temp_view
  

Mime
View raw message