DOCS-332 additional aggregation modifications.

Author: Sam Kleinman

source/applications/aggregation.txt

@@ -10,18 +10,18 @@ Overview
 --------
 
 The MongoDB aggregation framework provides a means to calculate
-aggregate values without having to use :term:`map-reduce`. While
-map-reduce is powerful, using map-reduce is more difficult than
+aggregated values without having to use :term:`map-reduce`. While
+map-reduce is powerful, it is often more difficult than
 necessary for many simple aggregation tasks, such as totaling or
 averaging field values.
 
 If you're familiar with :term:`SQL`, the aggregation framework
 provides similar functionality to ``GROUP BY`` and related SQL
 operators as well as simple forms of "self joins." Additionally, the
-aggregation framework provides projection capabilities to resultshape the
-returned data. Using projections and aggregation, you can add computed
-fields, create new virtual sub-objects, and extract sub-fields into
-the top-level of results.
+aggregation framework provides projection capabilities to reshape the
+returned data. Using the projections in the aggregation framework, you
+can add computed fields, create new virtual sub-objects, and extract
+sub-fields into the top-level of results.
 
 .. seealso:: A presentation from MongoSV 2011: `MongoDB's New
    Aggregation Framework <http://www.10gen.com/presentations/mongosv-2011/mongodbs-new-aggregation-framework>`_
@@ -74,28 +74,24 @@ through the pipeline.
    - :agg:pipeline:`$group`
    - :agg:pipeline:`$sort`
 
-   .. - :agg:pipeline:`$out`
-
 .. _aggregation-expressions:
 
 Expressions
 ~~~~~~~~~~~
 
-Expressions calculate values from documents as they pass through the
-pipeline and collect these results with calculated values from the
-other documents that have flowed through the pipeline.  The
-aggregation framework defines expressions in a :term:`JSON` like format using
-prefixes.
+:ref:`Expressions <aggregation-expression-operators>` produce output
+document based on calculations performed on input documents. The
+aggregation framework defines expressions using a document format
+using prefixes.
 
-Often, expressions are stateless and are only evaluated when seen by
-the aggregation process. Stateless expressions perform operations such
-as adding the values of two fields together or extracting the year
-from a date.
+Expressions are stateless and are only evaluated when seen by the
+aggregation process. All aggregation expressions can only operate on
+the current document, in the pipeline,  and cannot integrate data from
+other documents.
 
-The :term:`accumulator` expressions *do* retain state, and the
-:agg:pipeline:`$group` operator maintains that state (e.g.
-totals, maximums, minimums, and related data.) as documents progress
-through the :term:`pipeline`.
+The :term:`accumulator` expressions used in the :agg:pipeline:`$group`
+operator maintain that state (e.g.  totals, maximums, minimums, and
+related data) as documents progress through the :term:`pipeline`.
 
 .. seealso:: :ref:`Aggregation expressions
    <aggregation-expression-operators>` for additional examples of the
@@ -107,17 +103,15 @@ Use
 Invocation
 ~~~~~~~~~~
 
-Invoke an :term:`aggregation` operation with the :func:`aggregate`
+Invoke an :term:`aggregation` operation with the :func:`aggregate() <db.collection.aggregate()>`
 wrapper in the :program:`mongo` shell or the :dbcommand:`aggregate`
-:term:`database command`. Always call :func:`aggregate` on a
-collection object, which will determine the documents that contribute
-to the beginning of the aggregation :term:`pipeline`. The arguments to
-the :func:`aggregate` function specifies a sequence of :ref:`pipeline
+:term:`database command`. Always call :func:`aggregate() <db.collection.aggregate()>` on a
+collection object that determines the input documents to the aggregation :term:`pipeline`. 
+The arguments to the :func:`aggregate() <db.collection.aggregate()>` function specifies a sequence of :ref:`pipeline
 operators <aggregation-pipeline-operator-reference>`, where each
-:ref:`pipeline operator <aggregation-pipeline-operator-reference>` may
-have a number of operands.
+operator may have a number of operands.
 
-First, consider a :term:`collection` of documents named ``article``
+First, consider a :term:`collection` of documents named ``articles``
 using the following format:
 
 .. code-block:: javascript
@@ -142,7 +136,7 @@ command:
 
 .. code-block:: javascript
 
-   db.article.aggregate(
+   db.articles.aggregate(
      { $project : {
         author : 1,
         tags : 1,
@@ -154,12 +148,12 @@ command:
      } }
    );
 
-This operation uses the :func:`aggregate` wrapper around the
-:term:`database command` :dbcommand:`aggregate`. The aggregation
-pipleine begins with the :term:`collection` ``article`` and selects
-the ``author`` and ``tags`` fields using the :agg:pipeline:`$project`
-aggregation operator, and runs the :agg:expression:`$unwind` and
-:agg:expression:`$group` on these fields to pivot the data.
+The aggregation pipeline begins with the :term:`collection`
+``article`` and selects the ``author`` and ``tags`` fields using the
+:agg:pipeline:`$project` aggregation operator, and runs the
+:agg:expression:`$unwind` operator to produce one output document per
+tag finally uses the :agg:expression:`$group` operator on these fields
+to pivot the data.
 
 Result
 ~~~~~~
@@ -173,13 +167,7 @@ The aggregation operation in the previous section returns a
   if there was an error
 
 As a document, the result is subject to the current :ref:`BSON
-Document size <limit-bson-document-size>`.
-
-.. OMMITED: as $out will not be available in 2.2
-..
-.. If you expect the aggregation framework to return a larger result,
-.. consider using the use the :agg:pipeline:`$out` pipeline operator to
-.. write the output to a collection.
+Document size <limit-bson-document-size>`, which is 16 megabytes.
 
 Optimizing Performance
 ----------------------

source/includes/warning-aggregation-type.rst

@@ -1,5 +1,5 @@
 .. warning::
 
-   The pipeline cannot operate on collections with documents that contain
-   any of the following "special fields:" ``MinKey``, ``MaxKey``,
-   ``EOO``, ``Undefined``, ``DBRef``, ``Code``.
+   The pipeline cannot operate on values of the following types:
+   ``Binary``, ``Symbol``, ``MinKey``, ``MaxKey``, ``DBRef``,
+   ``Code``, and ``CodeWScope``.

source/reference/glossary.txt

@@ -751,7 +751,8 @@ Glossary
    accumulator
       An :term:`expression` in the :term:`aggregation framework` that
       maintains state between documents in the :term:`aggregation`
-      :term:`pipeline`.
+      :term:`pipeline`. See: :agg:pipeline:`$group` for a list of
+      accumulator operations.
 
    CRUD
       Create, read, update, and delete. The fundamental operations