feat(mango): updated intro tutorial to use mango isntead of MapReduce (#568)

Co-authored-by: Jonathan Hall <flimzy@flimzy.com>

Author: janl

src/intro/tour.rst

@@ -250,160 +250,109 @@ select Options, then check the Include Docs option. Finally, press the Run
 Query button. The full document should be displayed along with the ``_id``
 and ``_rev`` values.
 
-Running a Query Using MapReduce
-===============================
-
-Traditional relational databases allow you to run any queries you like as
-long as your data is structured correctly. In contrast,
-CouchDB uses predefined map and reduce functions in a style known as
-MapReduce. These functions provide great flexibility because they can adapt
-to variations in document structure, and indexes for each document can be
-computed independently and in parallel. The combination of a map and a reduce
-function is called a view in CouchDB terminology.
-
-For experienced relational database programmers, MapReduce can take some
-getting used to. Rather than declaring which rows from which tables to
-include in a result set and depending on the database to determine the most
-efficient way to run the query, reduce queries are based on simple range
-requests against the indexes generated by your map functions.
-
-Map functions are called once with each document as the argument.
-The function can choose to skip the document altogether or emit one or more
-view rows as key/value pairs. Map functions may not depend on any information
-outside of the document. This independence is what allows CouchDB views to be
-generated incrementally and in parallel.
-
-CouchDB views are stored as rows that are kept sorted by key. This makes
-retrieving data from a range of keys efficient even when there are thousands
-or millions of rows. When writing CouchDB map functions,
-your primary goal is to build an index that stores related data under nearby
-keys.
-
-Before we can run an example MapReduce view, we'll need some data to run it
-on. We'll create documents carrying the price of various supermarket items as
-found at different shops. Let's create documents for apples, oranges,
-and bananas. (Allow CouchDB to generate the _id and _rev fields.) Use Fauxton
-to create documents that have a final JSON structure that looks like this:
+Running a Mango Query
+=====================
+
+Now that we have stored documents successfully, we want to be able to query
+them. The easiest way to do this in CouchDB is running a Mango Query. There are
+always two parts to a Mango Query: the index and the selector.
+
+The index specifies which fields we want to be able to query on, and the
+selector includes the actual query parameters that define what we are looking
+for exactly.
+
+Indexes are stored as rows that are kept sorted by the fields you specify. This
+makes retrieving data from a range of keys efficient even when there are
+thousands or millions of rows.
+
+Before we can run an example query, we'll need some data to run it on. We'll
+create documents with information about movies. Let's create documents for
+three movies. (Allow CouchDB to generate the ``_id`` and ``_rev`` fields.) Use Fauxton
+to create documents that have a final JSON structure that look like this:
 
 .. code-block:: javascript
 
     {
         "_id": "00a271787f89c0ef2e10e88a0c0001f4",
-        "_rev": "1-2628a75ac8c3abfffc8f6e30c9949fd6",
-        "item": "apple",
-        "prices": {
-            "Fresh Mart": 1.59,
-            "Price Max": 5.99,
-            "Apples Express": 0.79
-        }
+        "type": "movie",
+        "title": "My Neighbour Totoro",
+        "year": 1988,
+        "director": "miyazaki",
+        "rating": 8.2
     }
 
-OK, now that that's done, let's create the document for oranges:
-
 .. code-block:: javascript
 
     {
         "_id": "00a271787f89c0ef2e10e88a0c0003f0",
-        "_rev": "1-e9680c5d9a688b4ff8dd68549e8e072c",
-        "item": "orange",
-        "prices": {
-            "Fresh Mart": 1.99,
-            "Price Max": 3.19,
-            "Citrus Circus": 1.09
-        }
+        "type": "movie",
+        "title": "Kikis Delivery Service",
+        "year": 1989,
+        "director": "miyazaki",
+        "rating": 7.8
     }
 
-And finally, the document for bananas:
-
 .. code-block:: javascript
 
     {
         "_id": "00a271787f89c0ef2e10e88a0c00048b",
-        "_rev": "1-60e25d93dc12884676d037400a6fa189",
-        "item": "banana",
-        "prices": {
-            "Fresh Mart": 1.99,
-            "Price Max": 0.79,
-            "Banana Montana": 4.22
-        }
+        "type": "movie",
+        "title": "Princess Mononoke",
+        "year": 1997,
+        "director": "miyazaki",
+        "rating": 8.4
     }
 
-Imagine we're catering a big luncheon, but the client is very price-sensitive.
-To find the lowest prices, we're going to create our first view,
-which shows each fruit sorted by price. Click "All Documents" to return to the
-hello-world overview, and then from the "All Documents" plus sign, click "New
-View" to create a new view.
+Now we want to be able to find a movie by its release year, we need to create a
+Mango Index. To do this, go to “Run A Query with Mango” in the Database
+overview. Then click on “manage indexes”, and change the index field on the
+left to look like this:
+
+.. code-block:: javascript
+
+    {
+       "index": {
+          "fields": [
+             "year"
+          ]
+       },
+       "name": "year-json-index",
+       "type": "json"
+    }
 
-Name the design document ``_design/myDesignDoc``, and set the Index name
-to ``prices``.
+This defines an index on the field ``year`` and allows us to send queries for
+documents from a specific year.
 
-Edit the map function, on the right, so that it looks like the following:
+Next, click on “edit query” and change the Mango Query to look like this:
 
 .. code-block:: javascript
 
-    function(doc) {
-        var shop, price, value;
-        if (doc.item && doc.prices) {
-            for (shop in doc.prices) {
-                price = doc.prices[shop];
-                value = [doc.item, shop];
-                emit(price, value);
-            }
+  {
+     "selector": {
+        "year": {
+           "$eq": 1988
         }
-    }
+     }
+  }
 
-This is a JavaScript function that CouchDB runs for each of our documents as
-it computes the view. We'll leave the reduce function blank for the time being.
+Then click on ”Run Query”.
 
-Click "Save Document and then Build Index" and you should see result rows,
-with the various items sorted by price. This map function could be even more
-useful if it grouped the items by type so that all the prices for bananas were
-next to each other in the result set. CouchDB's key sorting system allows any
-valid JSON object as a key. In this case, we'll emit an array of [item, price]
-so that CouchDB groups by item type and price.
+The result should be a single result, the movie “My Neighbour Toto” which
+has the year value of 1988. ``$eq`` here stands for “equal”.
 
-Let's modify the view function (click the wrench icon next to the Views >
-prices Design Document on the left, then select Edit) so that it looks like
-this:
+You can also query for all movies during the 1980s, with this selector:
 
 .. code-block:: javascript
 
-    function(doc) {
-        var shop, price, key;
-        if (doc.item && doc.prices) {
-            for (shop in doc.prices) {
-                price = doc.prices[shop];
-                key = [doc.item, price];
-                emit(key, shop);
-            }
+  {
+     "selector": {
+        "year": {
+           "$lt": 1990
         }
-    }
+     }
+  }
 
-Here, we first check that the document has the fields we want to use. CouchDB
-recovers gracefully from a few isolated map function failures,
-but when a map function fails regularly (due to a missing required field or
-other JavaScript exception), CouchDB shuts off its indexing to prevent any
-further resource usage. For this reason, it's important to check for the
-existence of any fields before you use them. In this case,
-our map function will skip the first "hello world" document we created
-without emitting any rows or encountering any errors. The result of this
-query should now be displayed.
-
-Once we know we've got a document with an item type and some prices,
-we iterate over the item's prices and emit key/values pairs. The key is an
-array of the item and the price, and forms the basis for CouchDB's sorted
-index. In this case, the value is the name of the shop where the item can be
-found for the listed price.
-
-View rows are sorted by their keys -- in this example, first by item,
-then by price. This method of complex sorting is at the heart of creating
-useful indexes with CouchDB.
-
-MapReduce can be challenging, especially if you've spent years working with
-relational databases. The important things to keep in mind are that map
-functions give you an opportunity to sort your data using any key you choose,
-and that CouchDB's design is focused on providing fast,
-efficient access to data within a range of keys.
+The result are the two movies from 1988 and 1998. ``$lt`` here means “lower than”.
 
 Triggering Replication
 ======================
@@ -416,7 +365,7 @@ through the examples.
 
 First we'll need to create an empty database to be the target of replication.
 Return to the Databases overview and create a database called
-``hello-replication``.  Now click "Replication" in the sidebar and choose
+``hello-replication``. Now click "Replication" in the sidebar and choose
 hello-world as the source and hello-replication as the target. Click
 "Replicate" to replicate your database.