You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2020/07/10 11:26:48 UTC
[couchdb-documentation] 01/01: feat(mango): updated intro tutorial
to use mango isntead of MapReduce
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch feat/mangofy-tutorial
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit e99958590bd561b6aff21ecd2835f31a97ba79c6
Author: Jan Lehnardt <ja...@apache.org>
AuthorDate: Fri Jul 10 13:26:29 2020 +0200
feat(mango): updated intro tutorial to use mango isntead of MapReduce
---
src/intro/tour.rst | 193 ++++++++++++++++++++---------------------------------
1 file changed, 71 insertions(+), 122 deletions(-)
diff --git a/src/intro/tour.rst b/src/intro/tour.rst
index a7197ba..f6fbc7f 100644
--- a/src/intro/tour.rst
+++ b/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.