Finalizers can be used to minimize the amount of data that needs to be transferred from the database to the user, which is important, because the group command’s output needs to fit in a single database response. To demonstrate this, we’ll take the example of a blog where each post has tags. We want to find the most popular tag for each day. We can group by day (again) and keep a count for each tag. This might look something like this:

> db.posts.group({
... "key" : {"tags" : true},
... "initial" : {"tags" : {}},
... "$reduce" : function(doc, prev) {
...     for (i in doc.tags) {
...         if (doc.tags[i] in prev.tags) {
...             prev.tags[doc.tags[i]]++;
...         } else {
...             prev.tags[doc.tags[i]] = 1;
...         }
...     }
... }})

This will return something like this:

[
    {"day" : "2010/01/12", "tags" : {"nosql" : 4, "winter" : 10, "sledding" : 2}},
    {"day" : "2010/01/13", "tags" : {"soda" : 5, "php" : 2}},
    {"day" : "2010/01/14", "tags" : {"python" : 6, "winter" : 4, "nosql": 15}}
]

Then we could find the largest value in the "tags" document on the client side. However, sending the entire tags document for every day is a lot of extra overhead to send to the client: an entire set of key/value pairs for each day, when all we want is a single string. This is why group takes an optional "finalize" key. "finalize" can contain a function that is run on each group once, right before the result is sent back to the client. We can use a "finalize" function to trim out all of the cruft from our results:

> db.runCommand({"group" : {
... "ns" : "posts",
... "key" : {"tags" : true},
... "initial" : {"tags" : {}},
... "$reduce" : function(doc, prev) {
...     for (i in doc.tags) {
...         if (doc.tags[i] in prev.tags) {
...             prev.tags[doc.tags[i]]++;
...         } else {
...             prev.tags[doc.tags[i]] = 1;
...         }
...     },
... "finalize" : function(prev) {
...     var mostPopular = 0;
...     for (i in prev.tags) {
...         if (prev.tags[i] > mostPopular) {
...             prev.tag = i;
...             mostPopular = prev.tags[i];
...         }
...     }
...     delete prev.tags
... }}})

Now, we’re only getting the information we want; the server will send back something like this:

[
    {"day" : "2010/01/12", "tag" : "winter"},
    {"day" : "2010/01/13", "tag" : "soda"},
    {"day" : "2010/01/14", "tag" : "nosql"}
]

finalize can either modify the argument passed in or return a new value.

Sometimes you may have more complicated criteria that you want to group by, not just a single key. Suppose you are using group to count how many blog posts are in each category. (Each blog post is in a single category.) Post authors were inconsistent, though, and categorized posts with haphazard capitalization. So, if you group by category name, you’ll end up with separate groups for “MongoDB” and “mongodb.” To make sure any variation of capitalization is treated as the same key, you can define a function to determine documents’ grouping key.

To define a grouping function, you must use a $keyf key (instead of "key"). Using "$keyf" makes the group command look something like this:

> db.posts.group({"ns" : "posts",
... "$keyf" : function(x) { return x.category.toLowerCase(); },
... "initializer" : ... })

"$keyf" allows you can group by arbitrarily complex criteria.

Using MapReduce for this problem might be overkill, but it is a good way to get familiar with how MapReduce works. If you already understand MapReduce, feel free to skip ahead to the last part of this section, where we cover MongoDB-specific MapReduce considerations.

MongoDB is schemaless, so it does not keep track of the keys in each document. The best way, in general, to find all the keys across all the documents in a collection is to use MapReduce. In this example, we’ll also get a count of how many times each key appears in the collection. This example doesn’t include keys for embedded documents, but it would be a simple addition to the map function to do so.

For the mapping step, we want to get every key of every document in the collection. The map function uses a special function to “return” values that we want to process later: emit. emit gives MapReduce a key (like the one used by group earlier) and a value. In this case, we emit a count of how many times a given key appeared in the document (once: {count : 1}). We want a separate count for each key, so we’ll call emit for every key in the document. this is a reference to the current document we are mapping:

> map = function() {
... for (var key in this) {
...     emit(key, {count : 1});
... }};

Now we have a ton of little {count : 1} documents floating around, each associated with a key from the collection. An array of one or more of these {count : 1} documents will be passed to the reduce function. The reduce function is passed two arguments: key, which is the first argument from emit, and an array of one or more {count : 1} documents that were emitted for that key:

> reduce = function(key, emits) {
... total = 0;
... for (var i in emits) {
...     total += emits[i].count;
... }
... return {"count" : total};
... }

reduce must be able to be called repeatedly on results from either the map phase or previous reduce phases. Therefore, reduce must return a document that can be re-sent to reduce as an element of its second argument. For example, say we have the key x mapped to three documents: {count : 1, id : 1}, {count : 1, id : 2}, and {count : 1, id : 3}. (The ID keys are just for identification purposes.) MongoDB might call reduce in the following pattern:

> r1 = reduce("x", [{count : 1, id : 1}, {count : 1, id : 2}])
{count : 2}
> r2 = reduce("x", [{count : 1, id : 3}])
{count : 1}
> reduce("x", [r1, r2])
{count : 3}

You cannot depend on the second argument always holding one of the initial documents ({count : 1} in this case) or being a certain length. reduce should be able to be run on any combination of emit documents and reduce return values.

Altogether, this MapReduce function would look like this:

> mr = db.runCommand({"mapreduce" : "foo", "map" : map, "reduce" : reduce})
{
    "result" : "tmp.mr.mapreduce_1266787811_1",
    "timeMillis" : 12,
    "counts" : {
        "input" : 6
        "emit" : 14
        "output" : 5
    },
    "ok" : true
}

The document MapReduce returns gives you a bunch of metainformation about the operation:

If we do a find on the resulting collection, we can see all of the keys and their counts from our original collection:

> db[mr.result].find()
{ "_id" : "_id", "value" : { "count" : 6 } }
{ "_id" : "a", "value" : { "count" : 4 } }
{ "_id" : "b", "value" : { "count" : 2 } }
{ "_id" : "x", "value" : { "count" : 1 } }
{ "_id" : "y", "value" : { "count" : 1 } }

Each of the key values becomes an "_id", and the final result of the reduce step(s) becomes the "value".

Suppose we have a site where people can submit links to other pages, such as reddit.com. Submitters can tag a link as related to certain popular topics, e.g., “politics,” “geek,” or “icanhascheezburger.” We can use MapReduce to figure out which topics are the most popular, as a combination of recent and most-voted-for.

First, we need a map function that emits tags with a value based on the popularity and recency of a document:

map = function() {
    for (var i in this.tags) {
        var recency = 1/(new Date() - this.date);
        var score = recency * this.score;

        emit(this.tags[i], {"urls" : [this.url], "score" : score});
    }
};

Now we need to reduce all of the emitted values for a tag into a single score for that tag:

reduce = function(key, emits) {
    var total = {urls : [], score : 0}
    for (var i in emits) {
        emits[i].urls.forEach(function(url) {
            total.urls.push(url);
        }
        total.score += emits[i].score;
    }
    return total;
};

The final collection will end up with a full list of URLs for each tag and a score showing how popular that particular tag is.

Both of the previous examples used only the mapreduce, map, and reduce keys. These three keys are required, but there are many optional keys that can be passed to the MapReduce command.

> db.runCommand({"mapreduce" : "analytics", "map" : map, "reduce" : reduce, 
                 "query" : {"date" : {"$gt" : week_ago}}})

> db.runCommand({"mapreduce" : "analytics", "map" : map, "reduce" : reduce, 
                 "limit" : 10000, "sort" : {"date" : -1}})

> db.runCommand({"mapreduce" : "webpages", "map" : map, "reduce" : reduce, 
                 "scope" : {now : new Date()}})