Aggregation Framework - $unwind

Overview
Specification
Notes

Overview

$unwind peels off the elements of an array one by one, returning a stream of documents. For each source document, for each member of the specified array within it, a new document emerges, but with the specified array replaced by one of its elements.

Specification

$unwind takes a single string argument, that is the path to the array element to be unwound. The path must be prefixed with a dollar sign ('$').

For the examples that follow, imagine an article collection made up of documents that look like this:

{
    title : "this is my title" ,
    author : "bob" ,
    posted : new Date() ,
    pageViews : 5 ,
    tags : [ "fun" , "good" , "fun" ] ,
    comments : [
        { author :"joe" , text : "this is cool" } ,
        { author :"sam" , text : "this is bad" }
    ],
    other : { foo : 5 }
}

Here is an example that demonstrates the effect of $unwind:

db.article.aggregate(
    { $project : {
	author : 1 , /* include this field */
        title : 1 , /* include this field */
        tags : 1 /* include this field */
    }},
    { $unwind : "$tags" }
);

Note the dollar sign ('$') in front of the name of the field to be unwound.

If this pipeline were to be run on the single article above, this would be the result:

{
        "result" : [
                {
                        "_id" : ObjectId("4e6e4ef557b77501a49233f6"),
                        "title" : "this is my title",
                        "author" : "bob",
                        "tags" : "fun"
                },
                {
                        "_id" : ObjectId("4e6e4ef557b77501a49233f6"),
                        "title" : "this is my title",
                        "author" : "bob",
                        "tags" : "good"
                },
                {
                        "_id" : ObjectId("4e6e4ef557b77501a49233f6"),
                        "title" : "this is my title",
                        "author" : "bob",
                        "tags" : "fun"
                }
        ],
        "ok" : 1
}

Note that the single document has become three documents: each is identical except for the value of the "tags" field. Each value of tags is one of the values in the original "tags" array.

Notes

$unwind is most useful when combined with $group or [$filter].

The effects of an unwind can be undone with the $push $group aggregation function.

If the target field does not exist within an input document, the document is passed through unchanged.

If the target field within an input document is not an array, an error is generated.

If the target field within an input document is an empty array ("[]"), then the document is passed through unchanged.

Aggregation Framework - $unwind

Overview

Specification

Notes

Labels