diff --git a/source/includes/ref-toc-aggregation-array.yaml b/source/includes/ref-toc-aggregation-array.yaml index 79e4f99fdfc..3065851df73 100644 --- a/source/includes/ref-toc-aggregation-array.yaml +++ b/source/includes/ref-toc-aggregation-array.yaml @@ -58,4 +58,9 @@ name: :expression:`$zip` description: | Merge two lists together. file: /reference/operator/aggregation/zip +--- +name: :expression:`$in` +description: | + Returns a boolean indicating whether a specified value is in an array. +file: /reference/operator/aggregation/in ... diff --git a/source/reference/operator/aggregation/in.txt b/source/reference/operator/aggregation/in.txt new file mode 100644 index 00000000000..e351f7d90f5 --- /dev/null +++ b/source/reference/operator/aggregation/in.txt @@ -0,0 +1,122 @@ +================= +$in (aggregation) +================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. expression:: $in + + .. versionadded:: 3.4 + + Returns a boolean indicating whether a specified value is in an + array. + + :expression:`$in` has the following :ref:`operator expression syntax + `: + + .. code-block:: javascript + + { $in: [ , ] } + + .. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Operand + - Description + + * - ```` + + - Any valid expression :ref:`expression + `. + + * - ```` + + - Any valid :ref:`expression ` that + resolves to an array. + + Unlike the :query:`$in` query operator, the aggregation + :expression:`$in` operator does not support matching by + :ref:`regular expressions `. + + .. list-table:: + :header-rows: 1 + :widths: 95 5 + + * - Example + - Results + + * - ``{ $in: [ 2, [ 1, 2, 3 ] ] }`` + - ``true`` + + * - ``{ $in: [ "abc", [ "xyz", "abc" ] ] }`` + - ``true`` + + * - ``{ $in: [ "xy", [ "xyz", "abc" ] ] }`` + - ``false`` + + * - ``{ $in: [ [ "a" ], [ "a" ] ] }`` + - ``false`` + + * - ``{ $in: [ [ "a" ], [ [ "a" ] ] ] }`` + - ``true`` + + * - ``{ $in: [ /^a/, [ "a" ] ] }`` + - ``false`` + + * - ``{ $in: [ /^a/, [ /^a/ ] ] }`` + - ``true`` + +Behavior +-------- + +:expression:`$in` fails with an error in either of the +following cases: if the $in expression is not given exactly two +arguments, or if the second argument does not resolve to an array. + +Example +------- + +A collection named ``fruit`` has the following documents: + +.. code-block:: javascript + + { "_id" : 1, "location" : "24th Street", + "in_stock" : [ "apples", "oranges", "bananas" ] } + { "_id" : 2, "location" : "36th Street", + "in_stock" : [ "bananas", "pears", "grapes" ] } + { "_id" : 3, "location" : "82nd Street", + "in_stock" : [ "cantaloupes", "watermelons", "apples" ] } + +The following aggregation operation looks at the ``in_stock`` array in +each document and determines whether the string ``bananas`` is present. + +.. code-block:: javascript + + db.fruit.aggregate([ + { + $project: { + "store location" : "$location", + "has bananas" : { + $in: [ "bananas", "$in_stock" ] + } + } + } + ]) + +The operation returns the following results: + +.. code-block:: javascript + + { "_id" : 1, "store location" : "24th Street", "has bananas" : true } + { "_id" : 2, "store location" : "36th Street", "has bananas" : true } + { "_id" : 3, "store location" : "82nd Street", "has bananas" : false }