You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:45 UTC
[12/26] documentation commit: updated refs/heads/master to 5a81ace
src/couchapp now follows the style
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/8d0d0495
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/8d0d0495
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/8d0d0495
Branch: refs/heads/master
Commit: 8d0d04952ba8ee3e1d67dcb45aa99966fdd3b212
Parents: 0bda0f2
Author: Maria Andersson <ma...@dualpose.com>
Authored: Fri Feb 6 22:22:06 2015 +0100
Committer: Maria Andersson <ma...@dualpose.com>
Committed: Fri Feb 6 22:22:06 2015 +0100
----------------------------------------------------------------------
src/couchapp/ddocs.rst | 517 ++++++++++++++++-----------------
src/couchapp/index.rst | 7 +-
src/couchapp/views/collation.rst | 185 ++++++------
src/couchapp/views/index.rst | 11 +-
src/couchapp/views/intro.rst | 299 +++++++++----------
src/couchapp/views/joins.rst | 364 ++++++++++++-----------
src/couchapp/views/nosql.rst | 308 ++++++++++----------
src/couchapp/views/pagination.rst | 140 +++++----
8 files changed, 907 insertions(+), 924 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/ddocs.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/ddocs.rst b/src/couchapp/ddocs.rst
index 52d411c..7e2828b 100644
--- a/src/couchapp/ddocs.rst
+++ b/src/couchapp/ddocs.rst
@@ -48,8 +48,8 @@ Map functions
:param doc: Processed document object.
-Map functions accept a single document as the argument and (optionally) :func:`emit`
-key/value pairs that are stored in a view.
+Map functions accept a single document as the argument and (optionally)
+:func:`emit` key/value pairs that are stored in a view.
.. code-block:: javascript
@@ -85,12 +85,12 @@ Reduce and rereduce functions
.. function:: redfun(keys, values[, rereduce])
- :param keys: Array of pairs docid-key for related map function result.
- Always ``null`` if rereduce is running (has ``true`` value).
- :param values: Array of map function result values.
- :param rereduce: Boolean sign of rereduce run.
+ :param keys: Array of pairs docid-key for related map function result.
+ Always ``null`` if rereduce is running (has ``true`` value).
+ :param values: Array of map function result values.
+ :param rereduce: Boolean sign of rereduce run.
- :return: Reduces `values`
+ :return: Reduces `values`
Reduce functions takes two required arguments of keys and values lists - the
result of the related map function - and optional third one which indicates if
@@ -104,15 +104,14 @@ could be disabled by setting ``reduce_limit`` config option to ``false``:
.. code-block:: ini
- [query_server_config]
- reduce_limit = false
+ [query_server_config]
+ reduce_limit = false
While disabling ``reduce_limit`` might be useful for debug proposes, remember,
that main task of reduce functions is to *reduce* mapped result, not to make it
even bigger. Generally, your reduce function should converge rapidly to a single
value - which could be an array or similar object.
-
.. _reducefun/builtin:
Builtin reduce functions
@@ -127,80 +126,82 @@ JavaScript below:
// could be replaced by _sum
function(keys, values) {
- return sum(values);
+ return sum(values);
}
// could be replaced by _count
function(keys, values, rereduce) {
- if (rereduce) {
- return sum(values);
- } else {
- return values.length;
- }
+ if (rereduce) {
+ return sum(values);
+ } else {
+ return values.length;
+ }
}
// could be replaced by _stats
function(keys, values, rereduce) {
- if (rereduce) {
- return {
- 'sum': values.reduce(function(a, b) { return a + b.sum }, 0),
- 'min': values.reduce(function(a, b) { return Math.min(a, b.min) }, Infinity),
- 'max': values.reduce(function(a, b) { return Math.max(a, b.max) }, -Infinity),
- 'count': values.reduce(function(a, b) { return a + b.count }, 0),
- 'sumsqr': values.reduce(function(a, b) { return a + b.sumsqr }, 0)
- }
- } else {
- return {
- 'sum': sum(values),
- 'min': Math.min.apply(null, values),
- 'max': Math.max.apply(null, values),
- 'count': values.length,
- 'sumsqr': (function() {
- var sumsqr = 0;
-
- values.forEach(function (value) {
- sumsqr += value * value;
- });
+ if (rereduce) {
+ return {
+ 'sum': values.reduce(function(a, b) { return a + b.sum }, 0),
+ 'min': values.reduce(function(a, b) { return Math.min(a, b.min) }, Infinity),
+ 'max': values.reduce(function(a, b) { return Math.max(a, b.max) }, -Infinity),
+ 'count': values.reduce(function(a, b) { return a + b.count }, 0),
+ 'sumsqr': values.reduce(function(a, b) { return a + b.sumsqr }, 0)
+ }
+ } else {
+ return {
+ 'sum': sum(values),
+ 'min': Math.min.apply(null, values),
+ 'max': Math.max.apply(null, values),
+ 'count': values.length,
+ 'sumsqr': (function() {
+ var sumsqr = 0;
+
+ values.forEach(function (value) {
+ sumsqr += value * value;
+ });
- return sumsqr;
- })(),
+ return sumsqr;
+ })(),
+ }
}
- }
}
-.. note:: **Why don't reduce functions support CommonJS modules?**
-
- While `map` functions have limited access to stored modules through
- :func:`require` function there is no such feature for `reduce` functions.
- The reason lies deep inside in the mechanism how `map` and `reduce` functions
- are processed by the Query Server. Let's take a look on `map` functions first:
-
- #. CouchDB sends all `map` functions for a processed design document to
- Query Server.
- #. Query Server handles them one by one, compiles and puts them onto an
- internal stack.
- #. After all `map` functions had been processed, CouchDB will send the
- remaining documents to index one by one.
- #. Query Server receives the document object and applies it to every function
- from the stack. The emitted results are then joined into a single array and sent
- back to CouchDB.
-
- Now let's see how `reduce` functions are handled:
-
- #. CouchDB sends *as single command* list of available `reduce` functions
- with result list of key-value pairs that was previously received as
- result of `map` functions work.
- #. Query Server compiles reduce functions and applies them to key-value
- lists. Reduced result is sent back to CouchDB.
-
- As you may note, `reduce` functions are applied in a single shot to the map results
- while the `map` functions are applied in an iterative way to one document at a time.
- This means that it's possible for `map` functions to precompile CommonJS libraries
- and use them during the entire view processing, but for `reduce` functions they
- would be compiled again and again for each view result reduction, which would lead
- to performance degradation (`reduce` function are already working hard to make large
- results smaller).
-
+.. note::
+ **Why don't reduce functions support CommonJS modules?**
+
+ While `map` functions have limited access to stored modules through
+ :func:`require` function there is no such feature for `reduce` functions.
+ The reason lies deep inside in the mechanism how `map` and `reduce`
+ functions are processed by the Query Server. Let's take a look on `map`
+ functions first:
+
+ #. CouchDB sends all `map` functions for a processed design document to
+ Query Server.
+ #. Query Server handles them one by one, compiles and puts them onto an
+ internal stack.
+ #. After all `map` functions had been processed, CouchDB will send the
+ remaining documents to index one by one.
+ #. Query Server receives the document object and applies it to every
+ function from the stack. The emitted results are then joined into a
+ single array and sent back to CouchDB.
+
+ Now let's see how `reduce` functions are handled:
+
+ #. CouchDB sends *as single command* list of available `reduce` functions
+ with result list of key-value pairs that was previously received as
+ result of `map` functions work.
+ #. Query Server compiles reduce functions and applies them to key-value
+ lists. Reduced result is sent back to CouchDB.
+
+ As you may note, `reduce` functions are applied in a single shot to the map
+ results while the `map` functions are applied in an iterative way to one
+ document at a time. This means that it's possible for `map` functions to
+ precompile CommonJS libraries and use them during the entire view
+ processing, but for `reduce` functions they would be compiled again and
+ again for each view result reduction, which would lead to performance
+ degradation (`reduce` function are already working hard to make large
+ results smaller).
.. _showfun:
@@ -209,26 +210,26 @@ Show functions
.. function:: showfun(doc, req)
- :param doc: Processed document, may be omitted.
- :param req: :ref:`Request object <request_object>`.
+ :param doc: Processed document, may be omitted.
+ :param req: :ref:`Request object <request_object>`.
- :return: :ref:`Response object <response_object>`
- :rtype: object or string
+ :return: :ref:`Response object <response_object>`
+ :rtype: object or string
Show functions are used to represent documents in various formats, commonly as
-HTML page with nicer formatting. They can also be used to run server-side functions
-without requiring a pre-existing document.
+HTML page with nicer formatting. They can also be used to run server-side
+functions without requiring a pre-existing document.
Basic example of show function could be:
.. code-block:: javascript
function(doc, req){
- if (doc) {
- return "Hello from " + doc._id + "!";
- } else {
- return "Hello, world!";
- }
+ if (doc) {
+ return "Hello from " + doc._id + "!";
+ } else {
+ return "Hello, world!";
+ }
}
Also, there is more simple way to return json encoded data:
@@ -236,84 +237,83 @@ Also, there is more simple way to return json encoded data:
.. code-block:: javascript
function(doc, req){
- return {
- 'json': {
- 'id': doc['_id'],
- 'rev': doc['_rev']
+ return {
+ 'json': {
+ 'id': doc['_id'],
+ 'rev': doc['_rev']
+ }
}
- }
}
-
and even files (this one is CouchDB logo):
.. code-block:: javascript
function(doc, req){
- return {
- 'headers': {
- 'Content-Type' : 'image/png',
- },
- 'base64': ''.concat(
- 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAsV',
- 'BMVEUAAAD////////////////////////5ur3rEBn////////////////wDBL/',
- 'AADuBAe9EB3IEBz/7+//X1/qBQn2AgP/f3/ilpzsDxfpChDtDhXeCA76AQH/v7',
- '/84eLyWV/uc3bJPEf/Dw/uw8bRWmP1h4zxSlD6YGHuQ0f6g4XyQkXvCA36MDH6',
- 'wMH/z8/yAwX64ODeh47BHiv/Ly/20dLQLTj98PDXWmP/Pz//39/wGyJ7Iy9JAA',
- 'AADHRSTlMAbw8vf08/bz+Pv19jK/W3AAAAg0lEQVR4Xp3LRQ4DQRBD0QqTm4Y5',
- 'zMxw/4OleiJlHeUtv2X6RbNO1Uqj9g0RMCuQO0vBIg4vMFeOpCWIWmDOw82fZx',
- 'vaND1c8OG4vrdOqD8YwgpDYDxRgkSm5rwu0nQVBJuMg++pLXZyr5jnc1BaH4GT',
- 'LvEliY253nA3pVhQqdPt0f/erJkMGMB8xucAAAAASUVORK5CYII=')
- }
+ return {
+ 'headers': {
+ 'Content-Type' : 'image/png',
+ },
+ 'base64': ''.concat(
+ 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAsV',
+ 'BMVEUAAAD////////////////////////5ur3rEBn////////////////wDBL/',
+ 'AADuBAe9EB3IEBz/7+//X1/qBQn2AgP/f3/ilpzsDxfpChDtDhXeCA76AQH/v7',
+ '/84eLyWV/uc3bJPEf/Dw/uw8bRWmP1h4zxSlD6YGHuQ0f6g4XyQkXvCA36MDH6',
+ 'wMH/z8/yAwX64ODeh47BHiv/Ly/20dLQLTj98PDXWmP/Pz//39/wGyJ7Iy9JAA',
+ 'AADHRSTlMAbw8vf08/bz+Pv19jK/W3AAAAg0lEQVR4Xp3LRQ4DQRBD0QqTm4Y5',
+ 'zMxw/4OleiJlHeUtv2X6RbNO1Uqj9g0RMCuQO0vBIg4vMFeOpCWIWmDOw82fZx',
+ 'vaND1c8OG4vrdOqD8YwgpDYDxRgkSm5rwu0nQVBJuMg++pLXZyr5jnc1BaH4GT',
+ 'LvEliY253nA3pVhQqdPt0f/erJkMGMB8xucAAAAASUVORK5CYII=')
+ }
}
-But what if you need to represent data in different formats via a single function?
-Functions :func:`registerType` and :func:`provides` are your the best friends in
-that question:
+But what if you need to represent data in different formats via a single
+function? Functions :func:`registerType` and :func:`provides` are your the best
+friends in that question:
.. code-block:: javascript
function(doc, req){
- provides('json', function(){
- return {'json': doc}
- });
- provides('html', function(){
- return '<pre>' + toJSON(doc) + '</pre>'
- })
- provides('xml', function(){
- return {
- 'headers': {'Content-Type': 'application/xml'},
- 'body' : ''.concat(
- '<?xml version="1.0" encoding="utf-8"?>\n',
- '<doc>',
- (function(){
- escape = function(s){
- return s.replace(/"/g, '"')
- .replace(/>/g, '>')
- .replace(/</g, '<')
- .replace(/&/g, '&');
- };
- var content = '';
- for(var key in doc){
- if(!doc.hasOwnProperty(key)) continue;
- var value = escape(toJSON(doc[key]));
- var key = escape(key);
- content += ''.concat(
- '<' + key + '>',
- value
- '</' + key + '>'
+ provides('json', function(){
+ return {'json': doc}
+ });
+ provides('html', function(){
+ return '<pre>' + toJSON(doc) + '</pre>'
+ })
+ provides('xml', function(){
+ return {
+ 'headers': {'Content-Type': 'application/xml'},
+ 'body' : ''.concat(
+ '<?xml version="1.0" encoding="utf-8"?>\n',
+ '<doc>',
+ (function(){
+ escape = function(s){
+ return s.replace(/"/g, '"')
+ .replace(/>/g, '>')
+ .replace(/</g, '<')
+ .replace(/&/g, '&');
+ };
+ var content = '';
+ for(var key in doc){
+ if(!doc.hasOwnProperty(key)) continue;
+ var value = escape(toJSON(doc[key]));
+ var key = escape(key);
+ content += ''.concat(
+ '<' + key + '>',
+ value
+ '</' + key + '>'
+ )
+ }
+ return content;
+ })(),
+ '</doc>'
)
- }
- return content;
- })(),
- '</doc>'
- )
- }
- })
- registerType('text-json', 'text/json')
- provides('text-json', function(){
- return toJSON(doc);
- })
+ }
+ })
+ registerType('text-json', 'text/json')
+ provides('text-json', function(){
+ return toJSON(doc);
+ })
}
This function may return `html`, `json` , `xml` or our custom `text json` format
@@ -322,13 +322,12 @@ the `xml` provider in our function needs more care to handle nested objects
correctly, and keys with invalid characters, but you've got the idea!
.. seealso::
+ CouchDB Wiki:
+ - `Showing Documents
+ <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Showing_Documents>`_
- CouchDB Wiki:
- - `Showing Documents <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Showing_Documents>`_
-
- CouchDB Guide:
- - `Show Functions <http://guide.couchdb.org/editions/1/en/show.html>`_
-
+ CouchDB Guide:
+ - `Show Functions <http://guide.couchdb.org/editions/1/en/show.html>`_
.. _listfun:
@@ -337,52 +336,53 @@ List functions
.. function:: listfun(head, req)
- :param head: :ref:`view_head_info_object`
- :param req: :ref:`Request object <request_object>`.
+ :param head: :ref:`view_head_info_object`
+ :param req: :ref:`Request object <request_object>`.
- :return: Last chunk.
- :rtype: string
+ :return: Last chunk.
+ :rtype: string
While :ref:`showfun` are used to customize document presentation, :ref:`listfun`
are used for same purpose, but against :ref:`viewfun` results.
-The next list function formats view and represents it as a very simple HTML page:
+The next list function formats view and represents it as a very simple HTML
+page:
.. code-block:: javascript
function(head, req){
- start({
- 'headers': {
- 'Content-Type': 'text/html'
+ start({
+ 'headers': {
+ 'Content-Type': 'text/html'
+ }
+ });
+ send('<html><body><table>');
+ send('<tr><th>ID</th><th>Key</th><th>Value</th></tr>')
+ while(row = getRow()){
+ send(''.concat(
+ '<tr>',
+ '<td>' + toJSON(row.id) + '</td>',
+ '<td>' + toJSON(row.key) + '</td>',
+ '<td>' + toJSON(row.value) + '</td>',
+ '</tr>'
+ ));
}
- });
- send('<html><body><table>');
- send('<tr><th>ID</th><th>Key</th><th>Value</th></tr>')
- while(row = getRow()){
- send(''.concat(
- '<tr>',
- '<td>' + toJSON(row.id) + '</td>',
- '<td>' + toJSON(row.key) + '</td>',
- '<td>' + toJSON(row.value) + '</td>',
- '</tr>'
- ));
- }
- send('</table></body></html>');
+ send('</table></body></html>');
}
-Templates and styles could obviously be used to present data in a nicer
-fashion, but this is an excellent starting point. Note that you may also
-use :func:`registerType` and :func:`provides` functions in the same
-way as for :ref:`showfun`!
+Templates and styles could obviously be used to present data in a nicer fashion,
+but this is an excellent starting point. Note that you may also use
+:func:`registerType` and :func:`provides` functions in the same way as for
+:ref:`showfun`!
.. seealso::
+ CouchDB Wiki:
+ - `Listing Views with CouchDB 0.10 and later
+ <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Listing_Views_with_CouchDB_0.10_and_later>`_
- CouchDB Wiki:
- - `Listing Views with CouchDB 0.10 and later <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Listing_Views_with_CouchDB_0.10_and_later>`_
-
- CouchDB Guide:
- - `Transforming Views with List Functions <http://guide.couchdb.org/draft/transforming.html>`_
-
+ CouchDB Guide:
+ - `Transforming Views with List Functions
+ <http://guide.couchdb.org/draft/transforming.html>`_
.. _updatefun:
@@ -391,17 +391,17 @@ Update functions
.. function:: updatefun(doc, req)
- :param doc: Update function target document.
- :param req: :ref:`request_object`
+ :param doc: Update function target document.
+ :param req: :ref:`request_object`
- :returns: Two-element array: the first element is the (updated or new)
- document, which is committed to the database. If the first element
- is ``null`` no document will be committed to the database.
- If you are updating an existing, it should already have an ``_id``
- set, and if you are creating a new document, make sure to set its
- ``_id`` to something, either generated based on the input or the
- ``req.uuid`` provided. The second element is the response that will
- be sent back to the caller.
+ :returns: Two-element array: the first element is the (updated or new)
+ document, which is committed to the database. If the first element
+ is ``null`` no document will be committed to the database.
+ If you are updating an existing, it should already have an ``_id``
+ set, and if you are creating a new document, make sure to set its
+ ``_id`` to something, either generated based on the input or the
+ ``req.uuid`` provided. The second element is the response that will
+ be sent back to the caller.
Update handlers are functions that clients can request to invoke server-side
logic that will create or update a document. This feature allows a range of use
@@ -432,10 +432,9 @@ The basic example that demonstrates all use-cases of update handlers below:
}
.. seealso::
-
- CouchDB Wiki:
- - `Document Update Handlers <http://wiki.apache.org/couchdb/Document_Update_Handlers>`_
-
+ CouchDB Wiki:
+ - `Document Update Handlers
+ <http://wiki.apache.org/couchdb/Document_Update_Handlers>`_
.. _filterfun:
@@ -444,10 +443,10 @@ Filter functions
.. function:: filterfun(doc, req)
- :param doc: Processed document object.
- :param req: :ref:`request_object`
- :return: Boolean value: ``true`` means that `doc` passes the filter rules,
- ``false`` means that it does not.
+ :param doc: Processed document object.
+ :param req: :ref:`request_object`
+ :return: Boolean value: ``true`` means that `doc` passes the filter rules,
+ ``false`` means that it does not.
Filter functions mostly act like :ref:`showfun` and :ref:`listfun`: they
format, or *filter* the :ref:`changes feed<changes>`.
@@ -458,28 +457,28 @@ Classic filters
By default the changes feed emits all database documents changes. But if you're
waiting for some special changes, processing all documents is inefficient.
-Filters are special design document functions that allow the changes feed to emit
-only specific documents that pass filter rules.
+Filters are special design document functions that allow the changes feed to
+emit only specific documents that pass filter rules.
Let's assume that our database is a mailbox and we need to handle only new mail
events (documents with status `new`). Our filter function will look like this:
.. code-block:: javascript
- function(doc, req){
- // we need only `mail` documents
- if (doc.type != 'mail'){
- return false;
- }
- // we're interested only in `new` ones
- if (doc.status != 'new'){
- return false;
+ function(doc, req){
+ // we need only `mail` documents
+ if (doc.type != 'mail'){
+ return false;
+ }
+ // we're interested only in `new` ones
+ if (doc.status != 'new'){
+ return false;
+ }
+ return true; // passed!
}
- return true; // passed!
- }
-Filter functions must return ``true`` if a document passed all defined
-rules. Now, if you apply this function to the changes feed it will emit only changes
+Filter functions must return ``true`` if a document passed all defined rules.
+Now, if you apply this function to the changes feed it will emit only changes
about "new mails"::
GET /somedatabase/_changes?filter=mailbox/new_mail HTTP/1.1
@@ -497,9 +496,9 @@ Seems like any other changes were for documents that haven't passed our filter.
We probably need to filter the changes feed of our mailbox by more than a single
status value. We're also interested in statuses like "spam" to update
-spam-filter heuristic rules, "outgoing" to let a mail daemon actually send mails,
-and so on. Creating a lot of similar functions that actually do similar work
-isn't good idea - so we need a dynamic filter.
+spam-filter heuristic rules, "outgoing" to let a mail daemon actually send
+mails, and so on. Creating a lot of similar functions that actually do similar
+work isn't good idea - so we need a dynamic filter.
You may have noticed that filter functions take a second argument named
:ref:`request <request_object>` - it allows creating dynamic filters
@@ -509,20 +508,20 @@ The dynamic version of our filter looks like this:
.. code-block:: javascript
- function(doc, req){
- // we need only `mail` documents
- if (doc.type != 'mail'){
- return false;
- }
- // we're interested only in requested status
- if (doc.status != req.query.status){
- return false;
+ function(doc, req){
+ // we need only `mail` documents
+ if (doc.type != 'mail'){
+ return false;
+ }
+ // we're interested only in requested status
+ if (doc.status != req.query.status){
+ return false;
+ }
+ return true; // passed!
}
- return true; // passed!
- }
-and now we have passed the `status` query parameter in request to let our filter match
-only required documents::
+and now we have passed the `status` query parameter in request to let our filter
+match only required documents::
GET /somedatabase/_changes?filter=mailbox/by_status&status=new HTTP/1.1
@@ -545,7 +544,6 @@ and we can easily change filter behavior with::
],
"last_seq":27}
-
Combining filters with a `continuous` feed allows creating powerful event-driven
systems.
@@ -565,19 +563,18 @@ To use them just specify `_view` value for ``filter`` parameter and
GET /somedatabase/_changes?filter=_view&view=dname/viewname HTTP/1.1
.. note::
-
- Since view filters uses `map` functions as filters, they can't show any
- dynamic behavior since :ref:`request object<request_object>` is not
- available.
+ Since view filters uses `map` functions as filters, they can't show any
+ dynamic behavior since :ref:`request object<request_object>` is not
+ available.
.. seealso::
+ CouchDB Guide:
+ - `Guide to filter change notification
+ <http://guide.couchdb.org/draft/notifications.html#filters>`_
- CouchDB Guide:
- - `Guide to filter change notification <http://guide.couchdb.org/draft/notifications.html#filters>`_
-
- CouchDB Wiki:
- - `Filtered replication <http://wiki.apache.org/couchdb/Replication#Filtered_Replication>`_
-
+ CouchDB Wiki:
+ - `Filtered replication
+ <http://wiki.apache.org/couchdb/Replication#Filtered_Replication>`_
.. _vdufun:
@@ -586,14 +583,14 @@ Validate document update functions
.. function:: validatefun(newDoc, oldDoc, userCtx, secObj)
- :param newDoc: New version of document that will be stored.
- :param oldDoc: Previous version of document that is already stored.
- :param userCtx: :ref:`userctx_object`
- :param secObj: :ref:`security_object`
+ :param newDoc: New version of document that will be stored.
+ :param oldDoc: Previous version of document that is already stored.
+ :param userCtx: :ref:`userctx_object`
+ :param secObj: :ref:`security_object`
- :throws: ``forbidden`` error to gracefully prevent document storing.
- :throws: ``unauthorized`` error to prevent storage and allow the user to
- re-auth.
+ :throws: ``forbidden`` error to gracefully prevent document storing.
+ :throws: ``unauthorized`` error to prevent storage and allow the user to
+ re-auth.
A design document may contain a function named `validate_doc_update`
which can be used to prevent invalid or unauthorized document update requests
@@ -612,11 +609,11 @@ by throwing one of two error objects:
.. code-block:: javascript
- // user is not authorized to make the change but may re-authenticate
- throw({ unauthorized: 'Error message here.' });
+ // user is not authorized to make the change but may re-authenticate
+ throw({ unauthorized: 'Error message here.' });
- // change is not allowed
- throw({ forbidden: 'Error message here.' });
+ // change is not allowed
+ throw({ forbidden: 'Error message here.' });
Document validation is optional, and each design document in the database may
have at most one validation function. When a write request is received for
@@ -755,14 +752,14 @@ modified by a user with the ``_admin`` role:
}
.. note::
-
- The ``return`` statement used only for function, it has no impact on
- the validation process.
+ The ``return`` statement used only for function, it has no impact on
+ the validation process.
.. seealso::
+ CouchDB Guide:
+ - `Validation Functions
+ <http://guide.couchdb.org/editions/1/en/validation.html>`_
- CouchDB Guide:
- - `Validation Functions <http://guide.couchdb.org/editions/1/en/validation.html>`_
-
- CouchDB Wiki:
- - `Document Update Validation <http://wiki.apache.org/couchdb/Document_Update_Validation>`_
+ CouchDB Wiki:
+ - `Document Update Validation
+ <http://wiki.apache.org/couchdb/Document_Update_Validation>`_
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/index.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/index.rst b/src/couchapp/index.rst
index 0985d49..e0938f5 100644
--- a/src/couchapp/index.rst
+++ b/src/couchapp/index.rst
@@ -24,8 +24,7 @@ your app is as simple as replicating it to the production server).
.. _CouchApps: http://couchapp.org/
.. toctree::
- :maxdepth: 2
-
- ddocs
- views/index
+ :maxdepth: 2
+ ddocs
+ views/index
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/collation.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/collation.rst b/src/couchapp/views/collation.rst
index 9b11b15..d080473 100644
--- a/src/couchapp/views/collation.rst
+++ b/src/couchapp/views/collation.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views/collation:
===============
@@ -26,11 +25,11 @@ property serves as the key, thus the result will be sorted by ``LastName``:
.. code-block:: javascript
- function(doc) {
- if (doc.Type == "customer") {
- emit(doc.LastName, {FirstName: doc.FirstName, Address: doc.Address});
+ function(doc) {
+ if (doc.Type == "customer") {
+ emit(doc.LastName, {FirstName: doc.FirstName, Address: doc.Address});
+ }
}
- }
CouchDB allows arbitrary JSON structures to be used as keys. You can use JSON
arrays as keys for fine-grained control over sorting and grouping.
@@ -47,19 +46,23 @@ associated orders. The values 0 and 1 for the sorting token are arbitrary.
.. code-block:: javascript
- function(doc) {
- if (doc.Type == "customer") {
- emit([doc._id, 0], null);
- } else if (doc.Type == "order") {
- emit([doc.customer_id, 1], null);
+ function(doc) {
+ if (doc.Type == "customer") {
+ emit([doc._id, 0], null);
+ } else if (doc.Type == "order") {
+ emit([doc.customer_id, 1], null);
+ }
}
- }
-To list a specific customer with ``_id`` XYZ, and all of that customer's orders, limit the startkey and endkey ranges to cover only documents for that customer's ``_id``::
+To list a specific customer with ``_id`` XYZ, and all of that customer's orders,
+limit the startkey and endkey ranges to cover only documents for that customer's
+``_id``::
- startkey=["XYZ"]&endkey=["XYZ", {}]
+ startkey=["XYZ"]&endkey=["XYZ", {}]
-It is not recommended to emit the document itself in the view. Instead, to include the bodies of the documents when requesting the view, request the view with ``?include_docs=true``.
+It is not recommended to emit the document itself in the view. Instead, to
+include the bodies of the documents when requesting the view, request the view
+with ``?include_docs=true``.
Sorting by Dates
================
@@ -72,14 +75,14 @@ the following emit function would sort by date:
.. code-block:: javascript
- emit(Date.parse(doc.created_at).getTime(), null);
+ emit(Date.parse(doc.created_at).getTime(), null);
Alternatively, if you use a date format which sorts lexicographically,
such as ``"2013/06/09 13:52:11 +0000"`` you can just
.. code-block:: javascript
- emit(doc.created_at, null);
+ emit(doc.created_at, null);
and avoid the conversion. As a bonus, this date format is compatible with the
JavaScript date parser, so you can use ``new Date(doc.created_at)`` in your
@@ -94,11 +97,11 @@ suffix.
That is, rather than::
- startkey="abc"&endkey="abcZZZZZZZZZ"
+ startkey="abc"&endkey="abcZZZZZZZZZ"
You should use::
- startkey="abc"&endkey="abc\ufff0"
+ startkey="abc"&endkey="abc\ufff0"
Collation Specification
=======================
@@ -109,47 +112,47 @@ This section is based on the view_collation function in `view_collation.js`_:
.. code-block:: javascript
- // special values sort before all other types
- null
- false
- true
-
- // then numbers
- 1
- 2
- 3.0
- 4
-
- // then text, case sensitive
- "a"
- "A"
- "aa"
- "b"
- "B"
- "ba"
- "bb"
-
- // then arrays. compared element by element until different.
- // Longer arrays sort after their prefixes
- ["a"]
- ["b"]
- ["b","c"]
- ["b","c", "a"]
- ["b","d"]
- ["b","d", "e"]
-
- // then object, compares each key value in the list until different.
- // larger objects sort after their subset objects.
- {a:1}
- {a:2}
- {b:1}
- {b:2}
- {b:2, a:1} // Member order does matter for collation.
- // CouchDB preserves member order
- // but doesn't require that clients will.
- // this test might fail if used with a js engine
- // that doesn't preserve order
- {b:2, c:2}
+ // special values sort before all other types
+ null
+ false
+ true
+
+ // then numbers
+ 1
+ 2
+ 3.0
+ 4
+
+ // then text, case sensitive
+ "a"
+ "A"
+ "aa"
+ "b"
+ "B"
+ "ba"
+ "bb"
+
+ // then arrays. compared element by element until different.
+ // Longer arrays sort after their prefixes
+ ["a"]
+ ["b"]
+ ["b","c"]
+ ["b","c", "a"]
+ ["b","d"]
+ ["b","d", "e"]
+
+ // then object, compares each key value in the list until different.
+ // larger objects sort after their subset objects.
+ {a:1}
+ {a:2}
+ {b:1}
+ {b:2}
+ {b:2, a:1} // Member order does matter for collation.
+ // CouchDB preserves member order
+ // but doesn't require that clients will.
+ // this test might fail if used with a js engine
+ // that doesn't preserve order
+ {b:2, c:2}
Comparison of strings is done using `ICU`_ which implements the
`Unicode Collation Algorithm`_, giving a dictionary sorting of keys.
@@ -172,50 +175,50 @@ You can demonstrate the collation sequence for 7-bit ASCII characters like this:
.. code-block:: ruby
- require 'rubygems'
- require 'restclient'
- require 'json'
+ require 'rubygems'
+ require 'restclient'
+ require 'json'
- DB="http://127.0.0.1:5984/collator"
+ DB="http://127.0.0.1:5984/collator"
- RestClient.delete DB rescue nil
- RestClient.put "#{DB}",""
+ RestClient.delete DB rescue nil
+ RestClient.put "#{DB}",""
- (32..126).each do |c|
- RestClient.put "#{DB}/#{c.to_s(16)}", {"x"=>c.chr}.to_json
- end
+ (32..126).each do |c|
+ RestClient.put "#{DB}/#{c.to_s(16)}", {"x"=>c.chr}.to_json
+ end
- RestClient.put "#{DB}/_design/test", <<EOS
- {
- "views":{
- "one":{
- "map":"function (doc) { emit(doc.x,null); }"
- }
+ RestClient.put "#{DB}/_design/test", <<EOS
+ {
+ "views":{
+ "one":{
+ "map":"function (doc) { emit(doc.x,null); }"
+ }
+ }
}
- }
- EOS
+ EOS
- puts RestClient.get("#{DB}/_design/test/_view/one")
+ puts RestClient.get("#{DB}/_design/test/_view/one")
This shows the collation sequence to be::
- ` ^ _ - , ; : ! ? . ' " ( ) [ ] { } @ * / \ & # % + < = > | ~ $ 0 1 2 3 4 5 6 7 8 9
- a A b B c C d D e E f F g G h H i I j J k K l L m M n N o O p P q Q r R s S t T u U v V w W x X y Y z Z
+ ` ^ _ - , ; : ! ? . ' " ( ) [ ] { } @ * / \ & # % + < = > | ~ $ 0 1 2 3 4 5 6 7 8 9
+ a A b B c C d D e E f F g G h H i I j J k K l L m M n N o O p P q Q r R s S t T u U v V w W x X y Y z Z
Key ranges
----------
Take special care when querying key ranges. For example: the query::
- startkey="Abc"&endkey="AbcZZZZ"
+ startkey="Abc"&endkey="AbcZZZZ"
will match "ABC" and "abc1", but not "abc". This is because UCA sorts as::
- abc < Abc < ABC < abc1 < AbcZZZZZ
+ abc < Abc < ABC < abc1 < AbcZZZZZ
For most applications, to avoid problems you should lowercase the `startkey`::
- startkey="abc"&endkey="abcZZZZZZZZ"
+ startkey="abc"&endkey="abcZZZZZZZZ"
will match all keys starting with ``[aA][bB][cC]``
@@ -232,12 +235,12 @@ _all_docs
The :ref:`_all_docs <api/db/all_docs>` view is a special case because it uses
ASCII collation for doc ids, not UCA::
- startkey="_design/"&endkey="_design/ZZZZZZZZ"
+ startkey="_design/"&endkey="_design/ZZZZZZZZ"
will not find ``_design/abc`` because `'Z'` comes before `'a'` in the ASCII
sequence. A better solution is::
- startkey="_design/"&endkey="_design0"
+ startkey="_design/"&endkey="_design0"
Raw collation
=============
@@ -249,13 +252,13 @@ sequence:
.. code-block:: javascript
- 1
- false
- null
- true
- {"a":"a"},
- ["a"]
- "a"
+ 1
+ false
+ null
+ true
+ {"a":"a"},
+ ["a"]
+ "a"
Beware that ``{}`` is no longer a suitable "high" key sentinel value. Use a
string like ``"\ufff0"`` instead.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/index.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/index.rst b/src/couchapp/views/index.rst
index 05f476d..701e443 100644
--- a/src/couchapp/views/index.rst
+++ b/src/couchapp/views/index.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views:
==============
@@ -23,8 +22,8 @@ applications with CouchDB
.. toctree::
- intro
- collation
- joins
- nosql
- pagination
+ intro
+ collation
+ joins
+ nosql
+ pagination
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/intro.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/intro.rst b/src/couchapp/views/intro.rst
index 30ec97b..574c30d 100644
--- a/src/couchapp/views/intro.rst
+++ b/src/couchapp/views/intro.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views/intro:
===========================
@@ -40,36 +39,36 @@ documents as we walk through how views work:
.. code-block:: javascript
- {
- "_id":"biking",
- "_rev":"AE19EBC7654",
+ {
+ "_id":"biking",
+ "_rev":"AE19EBC7654",
- "title":"Biking",
- "body":"My biggest hobby is mountainbiking. The other day...",
- "date":"2009/01/30 18:04:11"
- }
+ "title":"Biking",
+ "body":"My biggest hobby is mountainbiking. The other day...",
+ "date":"2009/01/30 18:04:11"
+ }
.. code-block:: javascript
- {
- "_id":"bought-a-cat",
- "_rev":"4A3BBEE711",
+ {
+ "_id":"bought-a-cat",
+ "_rev":"4A3BBEE711",
- "title":"Bought a Cat",
- "body":"I went to the the pet store earlier and brought home a little kitty...",
- "date":"2009/02/17 21:13:39"
- }
+ "title":"Bought a Cat",
+ "body":"I went to the the pet store earlier and brought home a little kitty...",
+ "date":"2009/02/17 21:13:39"
+ }
.. code-block:: javascript
- {
- "_id":"hello-world",
- "_rev":"43FBA4E7AB",
+ {
+ "_id":"hello-world",
+ "_rev":"43FBA4E7AB",
- "title":"Hello World",
- "body":"Well hello and welcome to my new blog...",
- "date":"2009/01/15 15:52:20"
- }
+ "title":"Hello World",
+ "body":"Well hello and welcome to my new blog...",
+ "date":"2009/01/15 15:52:20"
+ }
Three will do for the example. Note that the documents are sorted by "_id",
which is how they are stored in the database. Now we define a view.
@@ -77,11 +76,11 @@ Bear with us without an explanation while we show you some code:
.. code-block:: javascript
- function(doc) {
- if(doc.date && doc.title) {
- emit(doc.date, doc.title);
+ function(doc) {
+ if(doc.date && doc.title) {
+ emit(doc.date, doc.title);
+ }
}
- }
This is a `map function`, and it is written in JavaScript. If you are not
familiar with JavaScript but have used C or any other C-like language such as
@@ -123,7 +122,6 @@ Table 1. View results:
| "2009/02/17 21:13:39" | "Bought a Cat" |
+-----------------------+------------------+
-
When you query your view, CouchDB takes the source code and runs it for you on
every document in the database. If you have a lot of documents, that takes
quite a bit of time and you might wonder if it is not horribly inefficient
@@ -147,30 +145,30 @@ The actual result is JSON-encoded and contains a little more metadata:
.. code-block:: javascript
- {
- "total_rows": 3,
- "offset": 0,
- "rows": [
- {
- "key": "2009/01/15 15:52:20",
- "id": "hello-world",
- "value": "Hello World"
- },
-
- {
- "key": "2009/01/30 18:04:11",
- "id": "biking",
- "value": "Biking"
- },
-
- {
- "key": "2009/02/17 21:13:39",
- "id": "bought-a-cat",
- "value": "Bought a Cat"
- }
-
- ]
- }
+ {
+ "total_rows": 3,
+ "offset": 0,
+ "rows": [
+ {
+ "key": "2009/01/15 15:52:20",
+ "id": "hello-world",
+ "value": "Hello World"
+ },
+
+ {
+ "key": "2009/01/30 18:04:11",
+ "id": "biking",
+ "value": "Biking"
+ },
+
+ {
+ "key": "2009/02/17 21:13:39",
+ "id": "bought-a-cat",
+ "value": "Bought a Cat"
+ }
+
+ ]
+ }
Now, the actual result is not as nicely formatted and doesn’t include any
superfluous whitespace or newlines, but this is better for you (and us!)
@@ -243,15 +241,15 @@ to change the format of our date field. Instead of a string, we are going to use
an array, where individual members are part of a timestamp in decreasing
significance. This sounds fancy, but it is rather easy. Instead of::
- {
- "date": "2009/01/31 00:00:00"
- }
+ {
+ "date": "2009/01/31 00:00:00"
+ }
we use::
- {
- "date": [2009, 1, 31, 0, 0, 0]
- }
+ {
+ "date": [2009, 1, 31, 0, 0, 0]
+ }
Our map function does not have to change for this, but our view result looks
a little different:
@@ -268,8 +266,8 @@ Table 2. New view results:
| [2009, 1, 30, 18, 4, 11] | "Bought a Cat" |
+---------------------------+------------------+
-
-And our queries change to ``/blog/_design/docs/_view/by_date?startkey=[2010, 1, 1, 0, 0, 0]&endkey=[2010, 2, 1, 0, 0, 0]``.
+And our queries change to
+``/blog/_design/docs/_view/by_date?startkey=[2010, 1, 1, 0, 0, 0]&endkey=[2010, 2, 1, 0, 0, 0]``.
For all you care, this is just a change in syntax, not meaning. But it shows
you the power of views. Not only can you construct an index with scalar values
like strings and integers, you can also use JSON structures as keys for your
@@ -278,30 +276,29 @@ but we don’t care for documents that have not been tagged.
.. code-block:: javascript
- {
- ...
- tags: ["cool", "freak", "plankton"],
- ...
- }
+ {
+ ...
+ tags: ["cool", "freak", "plankton"],
+ ...
+ }
.. code-block:: javascript
- {
- ...
- tags: [],
- ...
- }
+ {
+ ...
+ tags: [],
+ ...
+ }
.. code-block:: javascript
- function(doc) {
- if(doc.tags.length > 0) {
- for(var idx in doc.tags) {
- emit(doc.tags[idx], null);
- }
+ function(doc) {
+ if(doc.tags.length > 0) {
+ for(var idx in doc.tags) {
+ emit(doc.tags[idx], null);
+ }
+ }
}
- }
-
This shows a few new things. You can have conditions on structure
(``if(doc.tags.length > 0)``) instead of just values. This is also an example of
@@ -395,9 +392,9 @@ the reduce view:
.. code-block:: javascript
- function(keys, values, rereduce) {
- return sum(values)
- }
+ function(keys, values, rereduce) {
+ return sum(values)
+ }
returns the total number of rows between the start and end key.
So with ``startkey=["a","b"]&endkey=["b"]`` (which includes the first three of
@@ -407,26 +404,24 @@ on the ``rereduce`` parameter:
.. code-block:: javascript
- function(keys, values, rereduce) {
- if (rereduce) {
- return sum(values);
- } else {
- return values.length;
+ function(keys, values, rereduce) {
+ if (rereduce) {
+ return sum(values);
+ } else {
+ return values.length;
+ }
}
- }
.. note::
-
- JavaScript function about could be effectively replaced by builtin ``_count``
- one.
+ JavaScript function about could be effectively replaced by builtin
+ ``_count`` one.
.. figure:: ../../../images/views-intro-01.png
- :align: center
- :scale: 50 %
- :alt: Comments map function
-
- Figure 1. Comments map function
+ :align: center
+ :scale: 50 %
+ :alt: Comments map function
+ Figure 1. Comments map function
This is the reduce view used by the example app to count comments, while
utilizing the map to output the comments, which are more useful than just
@@ -442,16 +437,16 @@ Let’s reprint the key list from earlier, grouped at level ``1``:
.. code-block:: javascript
- ["a"] 3
- ["b"] 2
+ ["a"] 3
+ ["b"] 2
And at ``group_level=2``:
.. code-block:: javascript
- ["a","b"] 2
- ["a","c"] 1
- ["b","a"] 2
+ ["a","b"] 2
+ ["a","c"] 1
+ ["b","a"] 2
Using the parameter ``group=true`` makes it behave as though it were
``group_level=999``, so in the case of our current example, it would give the
@@ -470,18 +465,18 @@ Consider the map result are:
.. code-block:: javascript
- "afrikan", 1
- "afrikan", 1
- "chinese", 1
- "chinese", 1
- "chinese", 1
- "chinese", 1
- "french", 1
- "italian", 1
- "italian", 1
- "spanish", 1
- "vietnamese", 1
- "vietnamese", 1
+ "afrikan", 1
+ "afrikan", 1
+ "chinese", 1
+ "chinese", 1
+ "chinese", 1
+ "chinese", 1
+ "french", 1
+ "italian", 1
+ "italian", 1
+ "spanish", 1
+ "vietnamese", 1
+ "vietnamese", 1
Example 1. Example view result (mmm, food)
@@ -490,18 +485,18 @@ the simple reduce function shown earlier:
.. code-block:: javascript
- function(keys, values, rereduce) {
- return sum(values);
- }
+ function(keys, values, rereduce) {
+ return sum(values);
+ }
Figure 2, “The B-tree index” shows a simplified version of what the B-tree index
looks like. We abbreviated the key strings.
.. figure:: ../../../images/views-intro-02.png
- :align: center
- :alt: The B-tree index
+ :align: center
+ :alt: The B-tree index
- Figure 2. The B-tree index
+ Figure 2. The B-tree index
The view result is what computer science grads call a “pre-order” walk through
the tree. We look at each element in each node starting from the left. Whenever
@@ -518,21 +513,20 @@ inside the parent node along with the edge to the subnode. In our case, each
edge has a 3 representing the reduce value for the node it points to.
.. note::
-
- In reality, nodes have more than 1,600 elements in them. CouchDB computes
- the result for all the elements in multiple iterations over the elements in
- a single node, not all at once (which would be disastrous for memory
- consumption).
+ In reality, nodes have more than 1,600 elements in them. CouchDB computes
+ the result for all the elements in multiple iterations over the elements in
+ a single node, not all at once (which would be disastrous for memory
+ consumption).
Now let’s see what happens when we run a query. We want to know how many
"chinese" entries we have. The query option is simple: ``?key="chinese"``.
See Figure 3, “The B-tree index reduce result”.
.. figure:: ../../../images/views-intro-03.png
- :align: center
- :alt: The B-tree index reduce result
+ :align: center
+ :alt: The B-tree index reduce result
- Figure 3. The B-tree index reduce result
+ Figure 3. The B-tree index reduce result
CouchDB detects that all values in the subnode include the "chinese" key.
It concludes that it can take just the 3 values associated with that node to
@@ -548,10 +542,9 @@ invocation of the reduce function with actual values:
.. code-block:: javascript
- function(null, [3, 1], true) {
- return sum([3, 1]);
- }
-
+ function(null, [3, 1], true) {
+ return sum([3, 1]);
+ }
Now, we said your reduce function must actually reduce your values. If you see
the B-tree, it should become obvious what happens when you don’t reduce your
@@ -560,35 +553,34 @@ want to get a list of all the unique labels in our view:
.. code-block:: javascript
- "abc", "afrikan"
- "cef", "afrikan"
- "fhi", "chinese"
- "hkl", "chinese"
- "ino", "chinese"
- "lqr", "chinese"
- "mtu", "french"
- "owx", "italian"
- "qza", "italian"
- "tdx", "spanish"
- "xfg", "vietnamese"
- "zul", "vietnamese"
+ "abc", "afrikan"
+ "cef", "afrikan"
+ "fhi", "chinese"
+ "hkl", "chinese"
+ "ino", "chinese"
+ "lqr", "chinese"
+ "mtu", "french"
+ "owx", "italian"
+ "qza", "italian"
+ "tdx", "spanish"
+ "xfg", "vietnamese"
+ "zul", "vietnamese"
We don’t care for the key here and only list all the labels we have. Our reduce
function removes duplicates:
.. code-block:: javascript
- function(keys, values, rereduce) {
- var unique_labels = {};
- values.forEach(function(label) {
- if(!unique_labels[label]) {
- unique_labels[label] = true;
- }
- });
-
- return unique_labels;
- }
+ function(keys, values, rereduce) {
+ var unique_labels = {};
+ values.forEach(function(label) {
+ if(!unique_labels[label]) {
+ unique_labels[label] = true;
+ }
+ });
+ return unique_labels;
+ }
This translates to Figure 4, “An overflowing reduce index”.
@@ -603,11 +595,10 @@ To help with that, CouchDB since version 0.10.0 will throw an error if your
reduce function does not reduce its input values.
.. figure:: ../../../images/views-intro-04.png
- :align: center
- :alt: An overflowing reduce index
-
- Figure 4. An overflowing reduce index
+ :align: center
+ :alt: An overflowing reduce index
+ Figure 4. An overflowing reduce index
Lessons Learned
===============
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/joins.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/joins.rst b/src/couchapp/views/joins.rst
index 3b95427..0a9ffb4 100644
--- a/src/couchapp/views/joins.rst
+++ b/src/couchapp/views/joins.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views/json:
================
@@ -33,117 +32,117 @@ For example, if you have the following hierarchically-linked documents:
.. code-block:: javascript
- [
- { "_id": "11111" },
- { "_id": "22222", "ancestors": ["11111"], "value": "hello" },
- { "_id": "33333", "ancestors": ["22222","11111"], "value": "world" }
- ]
+ [
+ { "_id": "11111" },
+ { "_id": "22222", "ancestors": ["11111"], "value": "hello" },
+ { "_id": "33333", "ancestors": ["22222","11111"], "value": "world" }
+ ]
You can emit the values with the ancestor documents adjacent to them in the view
like this:
.. code-block:: javascript
- function(doc) {
- if (doc.value) {
- emit([doc.value, 0], null);
- if (doc.ancestors) {
- for (var i in doc.ancestors) {
- emit([doc.value, Number(i)+1], {_id: doc.ancestors[i]});
+ function(doc) {
+ if (doc.value) {
+ emit([doc.value, 0], null);
+ if (doc.ancestors) {
+ for (var i in doc.ancestors) {
+ emit([doc.value, Number(i)+1], {_id: doc.ancestors[i]});
+ }
+ }
}
- }
}
- }
The result you get is:
.. code-block:: javascript
- {
- "total_rows": 5,
- "offset": 0,
- "rows": [
- {
- "id": "22222",
- "key": [
- "hello",
- 0
- ],
- "value": null,
- "doc": {
- "_id": "22222",
- "_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
- "ancestors": [
- "11111"
- ],
- "value": "hello"
- }
- },
- {
- "id": "22222",
- "key": [
- "hello",
- 1
- ],
- "value": {
- "_id": "11111"
- },
- "doc": {
- "_id": "11111",
- "_rev": "1-967a00dff5e02add41819138abb3284d"
- }
- },
- {
- "id": "33333",
- "key": [
- "world",
- 0
- ],
- "value": null,
- "doc": {
- "_id": "33333",
- "_rev": "1-11e42b44fdb3d3784602eca7c0332a43",
- "ancestors": [
- "22222",
- "11111"
- ],
- "value": "world"
- }
- },
- {
- "id": "33333",
- "key": [
- "world",
- 1
- ],
- "value": {
- "_id": "22222"
- },
- "doc": {
- "_id": "22222",
- "_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
- "ancestors": [
- "11111"
- ],
- "value": "hello"
- }
- },
- {
- "id": "33333",
- "key": [
- "world",
- 2
- ],
- "value": {
- "_id": "11111"
- },
- "doc": {
- "_id": "11111",
- "_rev": "1-967a00dff5e02add41819138abb3284d"
- }
- }
- ]
- }
+ {
+ "total_rows": 5,
+ "offset": 0,
+ "rows": [
+ {
+ "id": "22222",
+ "key": [
+ "hello",
+ 0
+ ],
+ "value": null,
+ "doc": {
+ "_id": "22222",
+ "_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
+ "ancestors": [
+ "11111"
+ ],
+ "value": "hello"
+ }
+ },
+ {
+ "id": "22222",
+ "key": [
+ "hello",
+ 1
+ ],
+ "value": {
+ "_id": "11111"
+ },
+ "doc": {
+ "_id": "11111",
+ "_rev": "1-967a00dff5e02add41819138abb3284d"
+ }
+ },
+ {
+ "id": "33333",
+ "key": [
+ "world",
+ 0
+ ],
+ "value": null,
+ "doc": {
+ "_id": "33333",
+ "_rev": "1-11e42b44fdb3d3784602eca7c0332a43",
+ "ancestors": [
+ "22222",
+ "11111"
+ ],
+ "value": "world"
+ }
+ },
+ {
+ "id": "33333",
+ "key": [
+ "world",
+ 1
+ ],
+ "value": {
+ "_id": "22222"
+ },
+ "doc": {
+ "_id": "22222",
+ "_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
+ "ancestors": [
+ "11111"
+ ],
+ "value": "hello"
+ }
+ },
+ {
+ "id": "33333",
+ "key": [
+ "world",
+ 2
+ ],
+ "value": {
+ "_id": "11111"
+ },
+ "doc": {
+ "_id": "11111",
+ "_rev": "1-967a00dff5e02add41819138abb3284d"
+ }
+ }
+ ]
+ }
which makes it very cheap to fetch a document plus all its ancestors in one
query.
@@ -157,7 +156,6 @@ is added later, it will appear in view queries even though the view itself
hasn't changed. To force a specific revision of a linked document to be used,
emit a ``"_rev"`` property as well as ``"_id"``.
-
Using View Collation
====================
@@ -183,21 +181,21 @@ comments inside that document:
.. code-block:: javascript
- {
- "_id": "myslug",
- "_rev": "123456",
- "author": "john",
- "title": "My blog post",
- "content": "Bla bla bla …",
- "comments": [
- {"author": "jack", "content": "…"},
- {"author": "jane", "content": "…"}
- ]
- }
+ {
+ "_id": "myslug",
+ "_rev": "123456",
+ "author": "john",
+ "title": "My blog post",
+ "content": "Bla bla bla …",
+ "comments": [
+ {"author": "jack", "content": "…"},
+ {"author": "jane", "content": "…"}
+ ]
+ }
.. note::
- Of course the model of an actual blogging system would be more extensive,
- you'd have tags, timestamps, etc etc. This is just to demonstrate the basics.
+ Of course the model of an actual blogging system would be more extensive,
+ you'd have tags, timestamps, etc etc. This is just to demonstrate the basics.
The obvious advantage of this approach is that the data that belongs together
is stored in one place. Delete the post, and you automatically delete the
@@ -210,11 +208,11 @@ all blog posts, keyed by author:
.. code-block:: javascript
- function(doc) {
- for (var i in doc.comments) {
- emit(doc.comments[i].author, doc.comments[i].content);
+ function(doc) {
+ for (var i in doc.comments) {
+ emit(doc.comments[i].author, doc.comments[i].content);
+ }
}
- }
Now you could list all comments by a particular user by invoking the view and
passing it a ``?key="username"`` query string parameter.
@@ -248,14 +246,14 @@ can tell the difference between posts and comments:
.. code-block:: javascript
- {
- "_id": "myslug",
- "_rev": "123456",
- "type": "post",
- "author": "john",
- "title": "My blog post",
- "content": "Bla bla bla …"
- }
+ {
+ "_id": "myslug",
+ "_rev": "123456",
+ "type": "post",
+ "author": "john",
+ "title": "My blog post",
+ "content": "Bla bla bla …"
+ }
The comments themselves are stored in separate documents, which also have a type
property (this time with the value “comment”), and in addition feature a post
@@ -263,36 +261,36 @@ property containing the ID of the post document they belong to:
.. code-block:: javascript
- {
- "_id": "ABCDEF",
- "_rev": "123456",
- "type": "comment",
- "post": "myslug",
- "author": "jack",
- "content": "…"
- }
+ {
+ "_id": "ABCDEF",
+ "_rev": "123456",
+ "type": "comment",
+ "post": "myslug",
+ "author": "jack",
+ "content": "…"
+ }
.. code-block:: javascript
- {
- "_id": "DEFABC",
- "_rev": "123456",
- "type": "comment",
- "post": "myslug",
- "author": "jane",
- "content": "…"
- }
+ {
+ "_id": "DEFABC",
+ "_rev": "123456",
+ "type": "comment",
+ "post": "myslug",
+ "author": "jane",
+ "content": "…"
+ }
To list all comments per blog post, you'd add a simple view, keyed by blog post
ID:
.. code-block:: javascript
- function(doc) {
- if (doc.type == "comment") {
- emit(doc.post, {author: doc.author, content: doc.content});
+ function(doc) {
+ if (doc.type == "comment") {
+ emit(doc.post, {author: doc.author, content: doc.content});
+ }
}
- }
And you'd invoke that view passing it a ``?key="post_id"`` query string
parameter.
@@ -301,11 +299,11 @@ Viewing all comments by author is just as easy as before:
.. code-block:: javascript
- function(doc) {
- if (doc.type == "comment") {
- emit(doc.author, {post: doc.post, content: doc.content});
+ function(doc) {
+ if (doc.type == "comment") {
+ emit(doc.author, {post: doc.post, content: doc.content});
+ }
}
- }
So this is better in some ways, but it also has a disadvantage.
Imagine you want to display a blog post with all the associated comments on the
@@ -334,13 +332,13 @@ some use of that:
.. code-block:: javascript
- function(doc) {
- if (doc.type == "post") {
- emit([doc._id, 0], doc);
- } else if (doc.type == "comment") {
- emit([doc.post, 1], doc);
+ function(doc) {
+ if (doc.type == "post") {
+ emit([doc._id, 0], doc);
+ } else if (doc.type == "comment") {
+ emit([doc.post, 1], doc);
+ }
}
- }
Okay, this may be confusing at first. Let's take a step back and look at what
views in CouchDB are really about.
@@ -362,7 +360,7 @@ This feature enables a whole class of tricks that are rather non-obvious...
.. seealso::
- :ref:`views/collation`
+ :ref:`views/collation`
With that in mind, let's return to the view function above. First note that,
unlike the previous view functions we've used here, this view handles both
@@ -378,39 +376,39 @@ the following:
.. code-block:: javascript
- {
- "total_rows": 5, "offset": 0, "rows": [{
- "id": "myslug",
- "key": ["myslug", 0],
- "value": {...}
- }, {
- "id": "ABCDEF",
- "key": ["myslug", 1],
- "value": {...}
- }, {
- "id": "DEFABC",
- "key": ["myslug", 1],
- "value": {...}
- }, {
- "id": "other_slug",
- "key": ["other_slug", 0],
- "value": {...}
- }, {
- "id": "CDEFAB",
- "key": ["other_slug", 1],
- "value": {...}
- },
- ]
- }
+ {
+ "total_rows": 5, "offset": 0, "rows": [{
+ "id": "myslug",
+ "key": ["myslug", 0],
+ "value": {...}
+ }, {
+ "id": "ABCDEF",
+ "key": ["myslug", 1],
+ "value": {...}
+ }, {
+ "id": "DEFABC",
+ "key": ["myslug", 1],
+ "value": {...}
+ }, {
+ "id": "other_slug",
+ "key": ["other_slug", 0],
+ "value": {...}
+ }, {
+ "id": "CDEFAB",
+ "key": ["other_slug", 1],
+ "value": {...}
+ },
+ ]
+ }
.. note::
- The ``...`` placeholder here would contain the complete JSON encoding of the
- corresponding document
+ The ``...`` placeholder here would contain the complete JSON encoding of the
+ corresponding document
Now, to get a specific blog post and all associated comments, we'd invoke that
view with the query string::
- ?startkey=["myslug"]&endkey;=["myslug", 2]
+ ?startkey=["myslug"]&endkey;=["myslug", 2]
We'd get back the first three rows, those that belong to the ``myslug`` post,
but not the others. Et voila, we now have the data we need to display a post
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/nosql.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/nosql.rst b/src/couchapp/views/nosql.rst
index 876d985..efbe8f3 100644
--- a/src/couchapp/views/nosql.rst
+++ b/src/couchapp/views/nosql.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views/nosql:
=============================
@@ -28,11 +27,11 @@ Using Views
How you would do this in SQL::
- CREATE TABLE
+ CREATE TABLE
or::
- ALTER TABLE
+ ALTER TABLE
How you can do this in CouchDB?
@@ -52,16 +51,16 @@ format. Here is an example:
.. code-block:: javascript
- {
- "_id": "_design/application",
- "_rev": "1-C1687D17",
- "views": {
- "viewname": {
- "map": "function(doc) { ... }",
- "reduce": "function(keys, values) { ... }"
- }
+ {
+ "_id": "_design/application",
+ "_rev": "1-C1687D17",
+ "views": {
+ "viewname": {
+ "map": "function(doc) { ... }",
+ "reduce": "function(keys, values) { ... }"
+ }
+ }
}
- }
We are defining a view `viewname`. The definition of the view consists of two
functions: the map function and the reduce function. Specifying a reduce
@@ -74,20 +73,20 @@ identified by a unique name:
.. code-block:: javascript
- {
- "_id": "_design/application",
- "_rev": "1-C1687D17",
- "views": {
- "viewname": {
- "map": "function(doc) { ... }",
- "reduce": "function(keys, values) { ... }"
- },
- "anotherview": {
- "map": "function(doc) { ... }",
- "reduce": "function(keys, values) { ... }"
- }
+ {
+ "_id": "_design/application",
+ "_rev": "1-C1687D17",
+ "views": {
+ "viewname": {
+ "map": "function(doc) { ... }",
+ "reduce": "function(keys, values) { ... }"
+ },
+ "anotherview": {
+ "map": "function(doc) { ... }",
+ "reduce": "function(keys, values) { ... }"
+ }
+ }
}
- }
Querying a View
---------------
@@ -96,7 +95,7 @@ The name of the design document and the name of the view are significant for
querying the view. To query the view `viewname`, you perform an HTTP ``GET``
request to the following URI::
- /database/_design/application/_view/viewname
+ /database/_design/application/_view/viewname
database is the name of the database you created your design document in. Next
up is the design document name, and then the view name prefixed with ``_view/``.
@@ -131,11 +130,11 @@ The map result looks like this:
.. code-block:: javascript
- {"total_rows":3,"offset":0,"rows":[
- {"id":"fc2636bf50556346f1ce46b4bc01fe30","key":"Lena","value":5},
- {"id":"1fb2449f9b9d4e466dbfa47ebe675063","key":"Lisa","value":4},
- {"id":"8ede09f6f6aeb35d948485624b28f149","key":"Sarah","value":6}
- ]}
+ {"total_rows":3,"offset":0,"rows":[
+ {"id":"fc2636bf50556346f1ce46b4bc01fe30","key":"Lena","value":5},
+ {"id":"1fb2449f9b9d4e466dbfa47ebe675063","key":"Lisa","value":4},
+ {"id":"8ede09f6f6aeb35d948485624b28f149","key":"Sarah","value":6}
+ ]}
It is a list of rows sorted by the value of key. The id is added automatically
and refers back to the document that created this row. The value is the data
@@ -145,11 +144,11 @@ The map function that produces this result is:
.. code-block:: javascript
- function(doc) {
- if(doc.name && doc.age) {
- emit(doc.name, doc.age);
+ function(doc) {
+ if(doc.name && doc.age) {
+ emit(doc.name, doc.age);
+ }
}
- }
It includes the if statement as a sanity check to ensure that we’re operating
on the right fields and calls the emit function with the name and age as the key
@@ -160,7 +159,7 @@ Look Up by Key
How you would do this in SQL::
- SELECT field FROM table WHERE value="searchterm"
+ SELECT field FROM table WHERE value="searchterm"
How you can do this in CouchDB?
@@ -176,40 +175,40 @@ view. All we need is a simple map function:
.. code-block:: javascript
- function(doc) {
- if(doc.value) {
- emit(doc.value, null);
+ function(doc) {
+ if(doc.value) {
+ emit(doc.value, null);
+ }
}
- }
This creates a list of documents that have a value field sorted by the data in
the value field. To find all the records that match "searchterm", we query the
view and specify the search term as a query parameter::
- /database/_design/application/_view/viewname?key="searchterm"
+ /database/_design/application/_view/viewname?key="searchterm"
Consider the documents from the previous section, and say we’re indexing on the
age field of the documents to find all the five-year-olds:
.. code-block:: javascript
- function(doc) {
- if(doc.age && doc.name) {
- emit(doc.age, doc.name);
+ function(doc) {
+ if(doc.age && doc.name) {
+ emit(doc.age, doc.name);
+ }
}
- }
Query::
- /ladies/_design/ladies/_view/age?key=5
+ /ladies/_design/ladies/_view/age?key=5
Result:
.. code-block:: javascript
- {"total_rows":3,"offset":1,"rows":[
- {"id":"fc2636bf50556346f1ce46b4bc01fe30","key":5,"value":"Lena"}
- ]}
+ {"total_rows":3,"offset":1,"rows":[
+ {"id":"fc2636bf50556346f1ce46b4bc01fe30","key":5,"value":"Lena"}
+ ]}
Easy.
@@ -223,7 +222,7 @@ Look Up by Prefix
How you would do this in SQL::
- SELECT field FROM table WHERE value LIKE "searchterm%"
+ SELECT field FROM table WHERE value LIKE "searchterm%"
How you can do this in CouchDB?
@@ -238,12 +237,12 @@ document:
.. code-block:: javascript
- {
- "_id": "Hugh Laurie",
- "_rev": "1-9fded7deef52ac373119d05435581edf",
- "mime-type": "image/jpg",
- "description": "some dude"
- }
+ {
+ "_id": "Hugh Laurie",
+ "_rev": "1-9fded7deef52ac373119d05435581edf",
+ "mime-type": "image/jpg",
+ "description": "some dude"
+ }
The clue lies in extracting the prefix that we want to search for from our
document and putting it into our view index. We use a regular expression to
@@ -251,28 +250,28 @@ match our prefix:
.. code-block:: javascript
- function(doc) {
- if(doc["mime-type"]) {
- // from the start (^) match everything that is not a slash ([^\/]+) until
- // we find a slash (\/). Slashes needs to be escaped with a backslash (\/)
- var prefix = doc["mime-type"].match(/^[^\/]+\//);
- if(prefix) {
- emit(prefix, null);
- }
+ function(doc) {
+ if(doc["mime-type"]) {
+ // from the start (^) match everything that is not a slash ([^\/]+) until
+ // we find a slash (\/). Slashes needs to be escaped with a backslash (\/)
+ var prefix = doc["mime-type"].match(/^[^\/]+\//);
+ if(prefix) {
+ emit(prefix, null);
+ }
+ }
}
- }
We can now query this view with our desired MIME type prefix and not only find
all images, but also text, video, and all other formats::
- /files/_design/finder/_view/by-mime-type?key="image/"
+ /files/_design/finder/_view/by-mime-type?key="image/"
Aggregate Functions
===================
How you would do this in SQL::
- SELECT COUNT(field) FROM table
+ SELECT COUNT(field) FROM table
How you can do this in CouchDB?
@@ -293,30 +292,29 @@ Here’s what our summing reduce function looks like:
.. code-block:: javascript
- function(keys, values) {
- var sum = 0;
- for(var idx in values) {
- sum = sum + values[idx];
+ function(keys, values) {
+ var sum = 0;
+ for(var idx in values) {
+ sum = sum + values[idx];
+ }
+ return sum;
}
- return sum;
- }
Here’s an alternate, more idiomatic JavaScript version:
.. code-block:: javascript
- function(keys, values) {
- var sum = 0;
- values.forEach(function(element) {
- sum = sum + element;
- });
- return sum;
- }
+ function(keys, values) {
+ var sum = 0;
+ values.forEach(function(element) {
+ sum = sum + element;
+ });
+ return sum;
+ }
.. note::
-
- Don't miss effective builtin :ref:`reduce functions <reducefun>` like ``_sum``
- and ``_count``
+ Don't miss effective builtin :ref:`reduce functions <reducefun>` like
+ ``_sum`` and ``_count``
This reduce function takes two arguments: a list of keys and a list of values.
For our summing purposes we can ignore the keys-list and consider only the value
@@ -337,9 +335,9 @@ The reduce function to calculate the total age of all girls is:
.. code-block:: javascript
- function(keys, values) {
- return sum(values);
- }
+ function(keys, values) {
+ return sum(values);
+ }
Note that, instead of the two earlier versions, we use CouchDB’s predefined
:js:func:`sum` function. It does the same thing as the other two, but it is such
@@ -349,9 +347,9 @@ The result for our reduce view now looks like this:
.. code-block:: javascript
- {"rows":[
- {"key":null,"value":15}
- ]}
+ {"rows":[
+ {"key":null,"value":15}
+ ]}
The total sum of all age fields in all our documents is 15. Just what we wanted.
The key member of the result object is null, as we can’t know anymore which
@@ -366,17 +364,17 @@ if you try to use reduce “the wrong way”:
.. code-block:: javascript
- {
- "error":"reduce_overflow_error",
- "message":"Reduce output must shrink more rapidly: Current output: ..."
- }
+ {
+ "error":"reduce_overflow_error",
+ "message":"Reduce output must shrink more rapidly: Current output: ..."
+ }
Get Unique Values
=================
How you would do this in SQL::
- SELECT DISTINCT field FROM table
+ SELECT DISTINCT field FROM table
How you can do this in CouchDB?
@@ -389,52 +387,52 @@ attributes here:
.. code-block:: javascript
- {
- "name":"Chris",
- "tags":["mustache", "music", "couchdb"]
- }
+ {
+ "name":"Chris",
+ "tags":["mustache", "music", "couchdb"]
+ }
.. code-block:: javascript
- {
- "name":"Noah",
- "tags":["hypertext", "philosophy", "couchdb"]
- }
+ {
+ "name":"Noah",
+ "tags":["hypertext", "philosophy", "couchdb"]
+ }
.. code-block:: javascript
- {
- "name":"Jan",
- "tags":["drums", "bike", "couchdb"]
- }
+ {
+ "name":"Jan",
+ "tags":["drums", "bike", "couchdb"]
+ }
Next, we need a list of all tags. A map function will do the trick:
.. code-block:: javascript
- function(doc) {
- if(doc.name && doc.tags) {
- doc.tags.forEach(function(tag) {
- emit(tag, null);
- });
+ function(doc) {
+ if(doc.name && doc.tags) {
+ doc.tags.forEach(function(tag) {
+ emit(tag, null);
+ });
+ }
}
- }
The result will look like this:
.. code-block:: javascript
- {"total_rows":9,"offset":0,"rows":[
- {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"bike","value":null},
- {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"couchdb","value":null},
- {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"couchdb","value":null},
- {"id":"da5ea89448a4506925823f4d985aabbd","key":"couchdb","value":null},
- {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"drums","value":null},
- {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"hypertext","value":null},
- {"id":"da5ea89448a4506925823f4d985aabbd","key":"music","value":null},
- {"id":"da5ea89448a4506925823f4d985aabbd","key":"mustache","value":null},
- {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"philosophy","value":null}
- ]}
+ {"total_rows":9,"offset":0,"rows":[
+ {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"bike","value":null},
+ {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"couchdb","value":null},
+ {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"couchdb","value":null},
+ {"id":"da5ea89448a4506925823f4d985aabbd","key":"couchdb","value":null},
+ {"id":"3525ab874bc4965fa3cda7c549e92d30","key":"drums","value":null},
+ {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"hypertext","value":null},
+ {"id":"da5ea89448a4506925823f4d985aabbd","key":"music","value":null},
+ {"id":"da5ea89448a4506925823f4d985aabbd","key":"mustache","value":null},
+ {"id":"53f82b1f0ff49a08ac79a9dff41d7860","key":"philosophy","value":null}
+ ]}
As promised, these are all the tags, including duplicates. Since each document
gets run through the map function in isolation, it cannot know if the same key
@@ -443,28 +441,28 @@ uniqueness, we need a reduce:
.. code-block:: javascript
- function(keys, values) {
- return true;
- }
+ function(keys, values) {
+ return true;
+ }
This reduce doesn’t do anything, but it allows us to specify a special query
parameter when querying the view::
- /dudes/_design/dude-data/_view/tags?group=true
+ /dudes/_design/dude-data/_view/tags?group=true
CouchDB replies:
.. code-block:: javascript
- {"rows":[
- {"key":"bike","value":true},
- {"key":"couchdb","value":true},
- {"key":"drums","value":true},
- {"key":"hypertext","value":true},
- {"key":"music","value":true},
- {"key":"mustache","value":true},
- {"key":"philosophy","value":true}
- ]}
+ {"rows":[
+ {"key":"bike","value":true},
+ {"key":"couchdb","value":true},
+ {"key":"drums","value":true},
+ {"key":"hypertext","value":true},
+ {"key":"music","value":true},
+ {"key":"mustache","value":true},
+ {"key":"philosophy","value":true}
+ ]}
In this case, we can ignore the value part because it is always true, but the
result includes a list of all our tags and no duplicates!
@@ -476,43 +474,43 @@ we emit a 1 instead of null:
.. code-block:: javascript
- function(doc) {
- if(doc.name && doc.tags) {
- doc.tags.forEach(function(tag) {
- emit(tag, 1);
- });
+ function(doc) {
+ if(doc.name && doc.tags) {
+ doc.tags.forEach(function(tag) {
+ emit(tag, 1);
+ });
+ }
}
- }
In the reduce function, we return the sum of all values:
.. code-block:: javascript
- function(keys, values) {
- return sum(values);
- }
+ function(keys, values) {
+ return sum(values);
+ }
Now, if we query the view with the ``?group=true`` parameter, we get back the
count for each tag:
.. code-block:: javascript
- {"rows":[
- {"key":"bike","value":1},
- {"key":"couchdb","value":3},
- {"key":"drums","value":1},
- {"key":"hypertext","value":1},
- {"key":"music","value":1},
- {"key":"mustache","value":1},
- {"key":"philosophy","value":1}
- ]}
+ {"rows":[
+ {"key":"bike","value":1},
+ {"key":"couchdb","value":3},
+ {"key":"drums","value":1},
+ {"key":"hypertext","value":1},
+ {"key":"music","value":1},
+ {"key":"mustache","value":1},
+ {"key":"philosophy","value":1}
+ ]}
Enforcing Uniqueness
====================
How you would do this in SQL::
- UNIQUE KEY(column)
+ UNIQUE KEY(column)
How you can do this in CouchDB?
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8d0d0495/src/couchapp/views/pagination.rst
----------------------------------------------------------------------
diff --git a/src/couchapp/views/pagination.rst b/src/couchapp/views/pagination.rst
index 6f3b34e..6cae038 100644
--- a/src/couchapp/views/pagination.rst
+++ b/src/couchapp/views/pagination.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _views/pagination:
=================
@@ -33,27 +32,27 @@ Example Data
To have some data to work with, we’ll create a list of bands,
one document per band::
- { "name":"Biffy Clyro" }
+ { "name":"Biffy Clyro" }
- { "name":"Foo Fighters" }
+ { "name":"Foo Fighters" }
- { "name":"Tool" }
+ { "name":"Tool" }
- { "name":"Nirvana" }
+ { "name":"Nirvana" }
- { "name":"Helmet" }
+ { "name":"Helmet" }
- { "name":"Tenacious D" }
+ { "name":"Tenacious D" }
- { "name":"Future of the Left" }
+ { "name":"Future of the Left" }
- { "name":"A Perfect Circle" }
+ { "name":"A Perfect Circle" }
- { "name":"Silverchair" }
+ { "name":"Silverchair" }
- { "name":"Queens of the Stone Age" }
+ { "name":"Queens of the Stone Age" }
- { "name":"Kerub" }
+ { "name":"Kerub" }
A View
=======
@@ -64,12 +63,12 @@ and “A” in front of band names to put them into the right position:
.. code-block:: javascript
- function(doc) {
- if(doc.name) {
- var name = doc.name.replace(/^(A|The) /, "");
- emit(name, null);
+ function(doc) {
+ if(doc.name) {
+ var name = doc.name.replace(/^(A|The) /, "");
+ emit(name, null);
+ }
}
- }
The views result is an alphabetical list of band names. Now say we want to
display band names five at a time and have a link pointing to the next five
@@ -82,19 +81,19 @@ the full result set:
.. code-block:: javascript
- {"total_rows":11,"offset":0,"rows":[
- {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
- {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
- {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
- {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
- {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null},
- {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
- {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
- {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
- {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age","value":null},
- {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null},
- {"id":"fd590d4ad53771db47b0406054f02243","key":"Tool","value":null}
- ]}
+ {"total_rows":11,"offset":0,"rows":[
+ {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
+ {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
+ {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
+ {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
+ {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null},
+ {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
+ {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
+ {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
+ {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age","value":null},
+ {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null},
+ {"id":"fd590d4ad53771db47b0406054f02243","key":"Tool","value":null}
+ ]}
Setup
=====
@@ -111,19 +110,18 @@ Or in a pseudo-JavaScript snippet:
.. code-block:: javascript
+ var result = new Result();
+ var page = result.getPage();
- var result = new Result();
- var page = result.getPage();
-
- page.display();
+ page.display();
- if(result.hasPrev()) {
- page.display_link('prev');
- }
+ if(result.hasPrev()) {
+ page.display_link('prev');
+ }
- if(result.hasNext()) {
- page.display_link('next');
- }
+ if(result.hasNext()) {
+ page.display_link('next');
+ }
Paging
======
@@ -131,19 +129,19 @@ Paging
To get the first five rows from the view result, you use the ``?limit=5``
query parameter::
- curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5
+ curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5
The result:
.. code-block:: javascript
- {"total_rows":11,"offset":0,"rows":[
- {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
- {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
- {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
- {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
- {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null}
- ]}
+ {"total_rows":11,"offset":0,"rows":[
+ {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
+ {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
+ {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
+ {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
+ {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null}
+ ]}
By comparing the ``total_rows`` value to our ``limit`` value,
we can determine if there are more pages to display. We also know by the
@@ -152,13 +150,13 @@ we can determine if there are more pages to display. We also know by the
.. code-block:: javascript
- var rows_per_page = 5;
- var page = (offset / rows_per_page) + 1; // == 1
- var skip = page * rows_per_page; // == 5 for the first page, 10 for the second ...
+ var rows_per_page = 5;
+ var page = (offset / rows_per_page) + 1; // == 1
+ var skip = page * rows_per_page; // == 5 for the first page, 10 for the second ...
So we query CouchDB with::
- curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5&skip=5'
+ curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5&skip=5'
Note we have to use ``'`` (single quotes) to escape the ``&`` character that is
special to the shell we execute curl in.
@@ -167,31 +165,31 @@ The result:
.. code-block:: javascript
- {"total_rows":11,"offset":5,"rows":[
- {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
- {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
- {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
- {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age",
- "value":null},
- {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null}
- ]}
+ {"total_rows":11,"offset":5,"rows":[
+ {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
+ {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
+ {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
+ {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age",
+ "value":null},
+ {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null}
+ ]}
Implementing the ``hasPrev()`` and ``hasNext()`` method is pretty
straightforward:
.. code-block:: javascript
- function hasPrev()
- {
- return page > 1;
- }
-
- function hasNext()
- {
- var last_page = Math.floor(total_rows / rows_per_page) +
- (total_rows % rows_per_page);
- return page != last_page;
- }
+ function hasPrev()
+ {
+ return page > 1;
+ }
+
+ function hasNext()
+ {
+ var last_page = Math.floor(total_rows / rows_per_page) +
+ (total_rows % rows_per_page);
+ return page != last_page;
+ }
Paging (Alternate Method)
=========================