DOCSP-29681 bitOr Aggregation Operator (#3117) (#3135)

* DOCSP-29681 bitOr Aggregation Operator

* typo fix

* JA feedback

* rewording

* wording consistency

* DH feedback

Author: ajhuh-mdb

source/includes/fact-bitwise-integer-long-results.rst

@@ -0,0 +1,4 @@
+If the operands include both integers and long values, MongoDB sign-extends the 
+calculated integer result and returns a long value. Otherwise, if the operands 
+include only integers or only longs, MongoDB returns results with the 
+corresponding value type.

source/includes/fact-bitwise-type-error.rst

@@ -0,0 +1,2 @@
+If any arguments in the array are of a different data type such as a string, 
+double, or decimal, MongoDB returns an error.

source/meta/aggregation-quick-reference.txt

@@ -356,6 +356,7 @@ Index of Expression Operators
    - :group:`$avg`
    - :expression:`$binarySize`
    - :expression:`$bitAnd`
+   - :expression:`$bitOr`
    - :expression:`$bsonSize`
    - :expression:`$ceil`
    - :expression:`$cmp`

source/reference/operator/aggregation.txt

@@ -274,6 +274,13 @@ Alphabetical Listing of Expression Operators
 
        .. versionadded:: 6.3
 
+   * - :expression:`$bitOr`
+
+     - Returns the result of a bitwise ``or`` operation on an array of ``int`` 
+       or ``long`` values. 
+
+       .. versionadded:: 6.3
+
    * - :group:`$bottom`
 
      - Returns the bottom element within a group according to the specified 
@@ -1286,6 +1293,7 @@ Alphabetical Listing of Expression Operators
    /reference/operator/aggregation/avg
    /reference/operator/aggregation/binarySize
    /reference/operator/aggregation/bitAnd
+   /reference/operator/aggregation/bitOr
    /reference/operator/aggregation/bottom
    /reference/operator/aggregation/bottomN
    /reference/operator/aggregation/bsonSize

source/reference/operator/aggregation/bitAnd.txt

@@ -32,13 +32,12 @@ The :expression:`$bitAnd` operator has the following syntax:
 Behavior
 --------
 
-If the operands include both integers and long values, MongoDB sign-extends the 
-calculated integer result and returns a long value. Otherwise, if the operands 
-include only integers or only longs, MongoDB returns results with the 
-corresponding value type.
+.. include:: /includes/fact-bitwise-integer-long-results.rst
 
 .. include:: /includes/fact-mongosh-integer-long-constructors.rst
 
+.. include:: /includes/fact-bitwise-type-error.rst
+
 If any of the operands equate to ``null``, the operation returns ``null``. 
 
 Examples

source/reference/operator/aggregation/bitOr.txt

@@ -0,0 +1,123 @@
+====================
+$bitOr (aggregation)
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+  :local:
+  :backlinks: none
+  :depth: 1
+  :class: singlecol
+
+Definition
+----------
+
+.. versionadded:: 6.3
+
+.. expression:: $bitOr
+
+    Returns the result of a bitwise ``or`` operation on an array of ``int`` and 
+    ``long`` values. 
+
+Syntax 
+------
+
+The ``$bitOr`` operator has the following syntax: 
+
+.. code-block:: javascript
+
+      { $bitOr: { [ <expression1>, <expression2>, ... ] }
+
+Behavior
+--------
+
+.. include:: /includes/fact-bitwise-integer-long-results.rst
+
+.. include:: /includes/fact-mongosh-integer-long-constructors.rst
+
+.. include:: /includes/fact-bitwise-type-error.rst
+
+If the argument is an empty array, the operation returns ``NumberInt(0)``.
+
+If any of the arguments in the array equate to ``null``, the operation returns 
+``null``. 
+
+Examples
+--------
+
+The examples on this page use the ``switches`` collection, which contains the 
+following documents: 
+
+.. code-block:: javascript 
+
+    db.switches.insertMany( [
+        { _id: 0, a: NumberInt(0), b: NumberInt(127) },
+        { _id: 1, a: NumberInt(2), b: NumberInt(3) },
+        { _id: 2, a: NumberInt(3), b: NumberInt(5) }
+    ] )
+
+Bitwise ``OR`` with Two Integers 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following aggregation uses the ``$bitOr`` operator in the 
+:pipeline:`$project` stage:
+
+.. code-block:: javascript 
+
+    db.switches.aggregate( [
+      { 
+        $project: { 
+          result: { 
+            $bitOr: [ "$a", "$b" ]
+          }
+        }
+      }
+    ])
+
+The operation returns the following results:
+
+.. code-block:: javascript 
+  :copyable: false
+
+    [
+      { _id: 0, result: 127 },
+      { _id: 1, result: 3 },
+      { _id: 2, result: 7 }
+    ]
+
+Bitwise ``OR`` with a Long and Integer 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following aggregation uses the ``$bitOr`` operator in the 
+:pipeline:`$project` stage:
+
+.. code-block:: javascript 
+
+    db.switches.aggregate( [
+      { 
+        $project: { 
+          result: { 
+            $bitOr: [ "$a", NumberLong("63") ]
+          }
+        }
+      }
+    ])
+
+The operation returns the following results:
+
+.. code-block:: javascript 
+  :copyable: false
+    
+    [
+      { _id: 0, result: Long("0") },
+      { _id: 1, result: Long("2") },
+      { _id: 2, result: Long("3") }
+    ]
+
+Learn More 
+----------
+
+- :ref:`aggregation-pipeline-operators`
+
+- :ref:`update-bit`