DOCS-9338: $in agg operator

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
 ...

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
+   <agg-quick-ref-operator-expressions>`:
+
+   .. code-block:: javascript
+
+      { $in: [ <expression>, <array expression> ] }
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 40 60
+
+      * - Operand
+        - Description
+
+      * - ``<expression>`` 
+
+        - Any valid expression :ref:`expression
+          <aggregation-expressions>`.
+
+      * - ``<array expression>`` 
+
+        - Any valid :ref:`expression <aggregation-expressions>` that
+          resolves to an array.
+
+   Unlike the :query:`$in` query operator, the aggregation
+   :expression:`$in` operator does not support matching by
+   :ref:`regular expressions <query-in-regex>`.
+
+   .. 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 }