From 4d83043bb17484b84a333209ba417599b88d60b5 Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 7 Mar 2013 19:13:51 -0500 Subject: [PATCH] DOCS-949 aggregation operator concat --- source/reference/aggregation.txt | 4 + source/reference/aggregation/concat.txt | 196 ++++++++++++++++++++++++ source/release-notes/2.4.txt | 8 + 3 files changed, 208 insertions(+) create mode 100644 source/reference/aggregation/concat.txt diff --git a/source/reference/aggregation.txt b/source/reference/aggregation.txt index ce3ec374f45..05ed14044f6 100644 --- a/source/reference/aggregation.txt +++ b/source/reference/aggregation.txt @@ -210,6 +210,10 @@ String Operators These operators manipulate strings within projection expressions. +.. include:: aggregation/concat.txt + :start-after: default-domain:: agg + :end-before: .. begin-examples + .. include:: aggregation/strcasecmp.txt :start-after: default-domain:: agg diff --git a/source/reference/aggregation/concat.txt b/source/reference/aggregation/concat.txt new file mode 100644 index 00000000000..51ac0475205 --- /dev/null +++ b/source/reference/aggregation/concat.txt @@ -0,0 +1,196 @@ +===================== +$concat (aggregation) +===================== + +.. default-domain:: agg + +.. expression:: $concat + + .. versionadded:: 2.4 + + Takes an array of strings, concatenates the strings, and returns the + concatenated string. :expression:`$concat` can only accept an array + of strings. + + Use :expression:`$concat` with the following syntax: + + .. code-block:: javascript + + { $concat: [ , , ... ] } + + If array element has a value of ``null`` or refers to a field that + is missing, :expression:`$concat` will return ``null``. + + .. begin-examples + + .. example:: Project new concatenated values. + + A collection ``menu`` contains the documents that stores + information on menu items separately in the ``section``, the + ``category`` and the ``type`` fields, as in the following: + + .. code-block:: javascript + + { _id: 1, item: { sec: "dessert", category: "pie", type: "apple" } } + { _id: 2, item: { sec: "dessert", category: "pie", type: "cherry" } } + { _id: 3, item: { sec: "main", category: "pie", type: "shepherd's" } } + { _id: 4, item: { sec: "main", category: "pie", type: "chicken pot" } } + + The following operation uses :expression:`$concat` to concatenate + the ``type`` field from the sub-document ``item``, a space `` ``, + and the ``category`` field from the sub-document ``item`` to + project a new ``food`` field: + + .. code-block:: javascript + + db.menu.aggregate( { $project: { food: + { $concat: [ "$item.type", + " ", + "$item.category" + ] + } + } + } + ) + + The operation returns the following result set where the ``food`` + field contains the concatenated strings: + + .. code-block:: javascript + + { + "result" : [ + { "_id" : 1, "food" : "apple pie" }, + { "_id" : 2, "food" : "cherry pie" }, + { "_id" : 3, "food" : "shepherd's pie" }, + { "_id" : 4, "food" : "chicken pot pie" } + ], + "ok" : 1 + } + + .. example:: Group by a concatenated string. + + A collection ``menu`` contains the documents that stores + information on menu items separately in the ``section``, the + ``category`` and the ``type`` fields, as in the following: + + .. code-block:: javascript + + { _id: 1, item: { sec: "dessert", category: "pie", type: "apple" } } + { _id: 2, item: { sec: "dessert", category: "pie", type: "cherry" } } + { _id: 3, item: { sec: "main", category: "pie", type: "shepherd's" } } + { _id: 4, item: { sec: "main", category: "pie", type: "chicken pot" } } + + The following aggregation uses :expression:`$concat` to + concatenate the ``sec`` field from the sub-document ``item``, the + string ``": "``, and the ``category`` field from the sub-document + ``item`` to group by the new concatenated string and perform a + count: + + .. code-block:: javascript + + db.menu.aggregate( { $group: { _id: + { $concat: [ "$item.sec", + ": ", + "$item.category" + ] + }, + count: { $sum: 1 } + } + } + ) + + The aggregation returns the following document: + + .. code-block:: javascript + + { + "result" : [ + { "_id" : "main: pie", "count" : 2 }, + { "_id" : "dessert: pie", "count" : 2 } + ], + "ok" : 1 + } + + .. example:: Concatenate ``null`` or missing values. + + A collection ``menu`` contains the documents that stores + information on menu items separately in the ``section``, the + ``category`` and the ``type`` fields. Not all documents have the + all three fields. For example, the document with ``_id`` equal to + ``5`` is missing the ``category`` field: + + .. code-block:: javascript + + { _id: 1, item: { sec: "dessert", category: "pie", type: "apple" } } + { _id: 2, item: { sec: "dessert", category: "pie", type: "cherry" } } + { _id: 3, item: { sec: "main", category: "pie", type: "shepherd's" } } + { _id: 4, item: { sec: "main", category: "pie", type: "chicken pot" } } + { _id: 5, item: { sec: "beverage", type: "coffee" } } + + The following aggregation uses the :expression:`$concat` to + concatenate the ``type`` field from the sub-document ``item``, a + space, and the ``category`` field from the sub-document ``item``: + + .. code-block:: javascript + + db.menu.aggregate( { $project: { food: + { $concat: [ "$item.type", + " ", + "$item.category" + ] + } + } + } + ) + + Because the document with ``_id`` equal to ``5`` is missing the + ``type`` field in the ``item`` sub-document, + :expression:`$concat` returns the value ``null`` as the + concatenated value for the document: + + .. code-block:: javascript + + { + "result" : [ + { "_id" : 1, "food" : "apple pie" }, + { "_id" : 2, "food" : "cherry pie" }, + { "_id" : 3, "food" : "shepherd's pie" }, + { "_id" : 4, "food" : "chicken pot pie" }, + { "_id" : 5, "food" : null } + ], + "ok" : 1 + } + + To handle possible missing fields, you can use + :expression:`$ifNull` with :expression:`$concat`, as in the + following example which substitutes ```` if the + field ``type`` is ``null`` or missing, and ```` + if the field ``category`` is ``null`` or is missing: + + .. code-block:: javascript + + db.menu.aggregate( { $project: { food: + { $concat: [ { $ifNull: ["$item.type", ""] }, + " ", + { $ifNull: ["$item.category", ""] } + ] + } + } + } + ) + + The aggregation returns the following result set: + + .. code-block:: javascript + + { + "result" : [ + { "_id" : 1, "food" : "apple pie" }, + { "_id" : 2, "food" : "cherry pie" }, + { "_id" : 3, "food" : "shepherd's pie" }, + { "_id" : 4, "food" : "chicken pot pie" }, + { "_id" : 5, "food" : "coffee " } + ], + "ok" : 1 + } diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt index f55f50a6209..6b7abf69d42 100644 --- a/source/release-notes/2.4.txt +++ b/source/release-notes/2.4.txt @@ -1442,3 +1442,11 @@ background at the same time. See :ref:`building indexes in the background ` for more information on background index builds. Foreground index builds hold a database lock and must proceed one at a time. + +Aggregation Updates +~~~~~~~~~~~~~~~~~~~~ + +- Addition of :agg:expression:`$concat` to concatenate array of strings. + +.. Need to merge this with other code-review updates regarding new agg + once they and this pass code review