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:47 UTC
[couchdb-documentation] branch feat/mangofy-tutorial created (now
e999585)
This is an automated email from the ASF dual-hosted git repository.
jan pushed a change to branch feat/mangofy-tutorial
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.
at e999585 feat(mango): updated intro tutorial to use mango isntead of MapReduce
This branch includes the following new commits:
new e999585 feat(mango): updated intro tutorial to use mango isntead of MapReduce
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb-documentation] 01/01: feat(mango): updated intro tutorial
to use mango isntead of MapReduce
Posted by ja...@apache.org.
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.