DOCSP-12942 numeric array indexing project (#521)

* DOCSP-12942-numeric-array-indexing-project

* DOCSP-12942-numeric-array-indexing-project

* DOCSP-12942-numeric-array-indexing-project

* DOCSP-12942-numeric-array-indexing-project

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/includes/project-stage-and-array-index.rst

@@ -0,0 +1,2 @@
+You cannot use an array index with the :pipeline:`$project` stage.
+See :ref:`example-project-array-indexes`.

source/reference/operator/aggregation/project.txt

@@ -54,14 +54,9 @@ Definition
 
         - Adds a new field or resets the value of an existing field.
 
-          .. versionchanged:: 3.6
+          If the the expression evaluates to ``$$REMOVE``, the field is
+          excluded in the output. For details, see :ref:`remove-var`.
 
-             MongoDB 3.6 adds the variable :variable:`REMOVE`. If the
-             the expression evaluates to ``$$REMOVE``, the field is
-             excluded in the output. For details, see :ref:`remove-var`.
-
-
-         
       * - ``<field>:<0 or false>``
 
         - Specifies the exclusion of a field.
@@ -103,8 +98,6 @@ must explicitly specify the suppression of the ``_id`` field in
 Exclude Fields
 ~~~~~~~~~~~~~~
 
-.. versionadded:: 3.4
-
 If you specify the exclusion of a field or fields, all other fields are
 returned in the output documents.
 
@@ -126,11 +119,9 @@ See also the :pipeline:`$unset` stage to exclude fields.
 Exclude Fields Conditionally
 ````````````````````````````
 
-.. versionadded:: 3.6
-
-Starting in MongoDB 3.6, you can use the variable :variable:`REMOVE` in
-aggregation expressions to conditionally suppress a field. For an
-example, see :ref:`remove-example`.
+You can use the variable :variable:`REMOVE` in aggregation expressions
+to conditionally suppress a field. For an example, see
+:ref:`remove-example`.
 
 Add New Fields or Reset Existing Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -162,12 +153,13 @@ existing field, you can effectively rename a field.
 New Array Fields
 ````````````````
 
-Starting in MongoDB 3.2, :pipeline:`$project` stage supports using the
-square brackets ``[]`` to directly create new array fields. If array
-specification includes fields that are non-existent in a document, the
-operation substitutes ``null`` as the value for that field. For an
-example, see :ref:`example-project-new-array-fields`.
+The :pipeline:`$project` stage supports using the square brackets ``[]``
+to directly create new array fields. If you specify array fields that do
+not exist in a document, the operation substitutes ``null`` as the value
+for that field. For an example, see
+:ref:`example-project-new-array-fields`.
 
+.. include:: /includes/project-stage-and-array-index.rst
 
 Embedded Document Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -216,10 +208,10 @@ fails with the same error:
 Restrictions
 ~~~~~~~~~~~~
 
-.. versionchanged:: 3.4
+An error is returned if the :pipeline:`$project` specification is
+an empty document.
 
-MongoDB 3.4 and later produces an error if the :pipeline:`$project`
-specification is an empty document.
+.. include:: /includes/project-stage-and-array-index.rst
 
 Examples
 --------
@@ -289,9 +281,6 @@ The operation results in the following document:
 Exclude Fields from Output Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
-.. versionadded:: 3.4
-
 Consider a ``books`` collection with the following document:
 
 .. code-block:: javascript
@@ -317,8 +306,6 @@ See also the :pipeline:`$unset` stage to exclude fields.
 Exclude Fields from Embedded Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 3.4
-
 Consider a ``books`` collection with the following document:
 
 .. code-block:: javascript
@@ -366,10 +353,8 @@ See also the :pipeline:`$unset` stage to exclude fields.
 Conditionally Exclude Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 3.6
-
-Starting in MongoDB 3.6, you can use the variable :variable:`REMOVE` in
-aggregation expressions to conditionally suppress a field.
+You can use the variable :variable:`REMOVE` in aggregation expressions
+to conditionally suppress a field.
 
 Consider a ``books`` collection with the following document:
 
@@ -560,6 +545,53 @@ The operation returns the following document:
 
    { "_id" : ObjectId("55ad167f320c6be244eb3b95"), "myArray" : [ 1, 1, null ] }
 
+.. _example-project-array-indexes:
+
+Array Indexes are Unsupported
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You cannot use an array index with the :pipeline:`$project` stage. This
+section shows an example.
+
+Create the following ``pizzas`` collection:
+
+.. code-block:: javascript
+
+   db.pizzas.insert( [
+      { _id: 0, name: [ 'Pepperoni' ] },
+   ] )
+
+The following example returns the pizza:
+
+.. code-block:: javascript
+
+   db.pizzas.aggregate( [
+      { $project: { x: '$name', _id: 0 } },
+   ] )
+
+The pizza is returned in the example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [ { x: [ 'Pepperoni' ] } ]
+
+The following example uses an array index (``$name.0``) to attempt to
+return the pizza:
+
+.. code-block:: javascript
+
+   db.pizzas.aggregate( [
+      { $project: { x: '$name.0', _id: 0 } },
+   ] )
+
+The pizza is not returned in the example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [ { x: [] } ]
+
 .. seealso::
 
    - :doc:`/tutorial/aggregation-zip-code-data-set`