Skip to content

Commit 76021ad

Browse files
mballard-mdbmballard-mdb
authored
Revert "DOCSP-50497 Node.js Aggregation Standardization (#1168)"
This reverts commit 4841edd.
1 parent 4841edd commit 76021ad

File tree

3 files changed

+121
-401
lines changed

3 files changed

+121
-401
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ toc_landing_pages = [
1111
"/connect",
1212
"/security",
1313
"/security/authentication",
14+
"/aggregation-tutorials",
1415
"/data-formats",
1516
"/connect/connection-options",
16-
"/aggregation",
1717
"/crud",
1818
"/crud/query",
1919
"crud/update",

‎source/aggregation.txt

Lines changed: 120 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
.. _node-aggregation:
22
.. _nodejs-aggregation:
33

4-
======================
5-
Aggregation Operations
6-
======================
4+
===========
5+
Aggregation
6+
===========
77

88
.. facet::
99
:name: genre
@@ -18,27 +18,18 @@ Aggregation Operations
1818
:depth: 2
1919
:class: singlecol
2020

21-
.. toctree::
22-
:titlesonly:
23-
:maxdepth: 1
24-
25-
Pipeline Stages </aggregation/pipeline-stages>
26-
2721
.. _nodejs-aggregation-overview:
2822

2923
Overview
3024
--------
3125

32-
In this guide, you can learn how to use the {+driver-long+} to perform
33-
**aggregation operations**.
34-
35-
Aggregation operations process data in your MongoDB collections and return
36-
computed results. The MongoDB Aggregation framework is modeled on the concept of
37-
data processing pipelines. Documents enter a pipeline comprised of one or more
38-
stages, and this pipeline transforms the documents into an aggregated result.
26+
In this guide, you can learn how to use **aggregation operations** in
27+
the MongoDB Node.js driver.
3928

40-
To learn more about the aggregation stages supported by the {+driver-short+},
41-
see :ref:`node-aggregation-pipeline-stages`.
29+
Aggregation operations are expressions you can use to produce reduced
30+
and summarized results in MongoDB. MongoDB's aggregation framework
31+
allows you to create a pipeline that consists of one or more stages,
32+
each of which performs a specific operation on your data.
4233

4334
.. _node-aggregation-tutorials:
4435

@@ -51,67 +42,114 @@ see :ref:`node-aggregation-pipeline-stages`.
5142
Analogy
5243
~~~~~~~
5344

54-
The aggregation pipeline is similar to an automobile factory assembly line. An
55-
assembly line has stations with specialized tools that are used to perform
56-
specific tasks. For example, when building a car, the assembly line begins with
57-
a frame. As the car frame moves though the assembly line, each station assembles
58-
a separate part. The result is a transformed final product, the finished car.
59-
60-
The *aggregation pipeline* is the assembly line, the *aggregation stages* are
61-
the assembly stations, the *expression operators* are the specialized tools, and
62-
the *aggregated result* is the finished product.
63-
64-
Compare Aggregation and Find Operations
65-
---------------------------------------
66-
67-
The following table lists the different tasks you can perform with find
68-
operations compared to what you can achieve with aggregation operations. The
69-
aggregation framework provides expanded functionality that allows you to
70-
transform and manipulate your data.
71-
72-
.. list-table::
73-
:header-rows: 1
74-
:widths: 50 50
75-
76-
* - Find Operations
77-
- Aggregation Operations
78-
79-
* - | Select *certain* documents to return
80-
| Select *which* fields to return
81-
| Sort the results
82-
| Limit the results
83-
| Count the results
84-
- | Select *certain* documents to return
85-
| Select *which* fields to return
86-
| Sort the results
87-
| Limit the results
88-
| Count the results
89-
| Group the results
90-
| Rename fields
91-
| Compute new fields
92-
| Summarize data
93-
| Connect and merge data sets
94-
95-
Server Limitations
96-
------------------
97-
98-
Consider the following :manual:`limitations
99-
</core/aggregation-pipeline-limits/>` when performing aggregation operations:
100-
101-
- Returned documents must not violate the :manual:`BSON document size limit
102-
</reference/limits/#mongodb-limit-BSON-Document-Size>` of 16 megabytes.
103-
- Pipeline stages have a memory limit of 100 megabytes by default. If required,
104-
you can exceed this limit by enabling the `AllowDiskUse
105-
<https://mongodb.github.io/node-mongodb-native/6.17/interfaces/AggregateOptions.html#allowDiskUse>`__
106-
property of the ``AggregateOptions`` object that you pass to the
107-
``aggregate()`` method.
108-
109-
Additional information
110-
----------------------
111-
112-
To view a full list of expression operators, see :manual:`Aggregation Operators
113-
</reference/operator/aggregation/>` in the {+mdb-server+} manual.
114-
115-
To learn about explaining MongoDB aggregation operations, see :manual:`Explain
116-
Results </reference/explain-results/>` and :manual:`Query Plans
117-
</core/query-plans/>` in the {+mdb-server+} manual.
45+
You can think of the aggregation pipeline as similar to an automobile factory.
46+
Automobile manufacturing requires the use of assembly stations organized
47+
into assembly lines. Each station has specialized tools, such as
48+
drills and welders. The factory transforms and
49+
assembles the initial parts and materials into finished products.
50+
51+
The **aggregation pipeline** is the assembly line, **aggregation
52+
stages** are the assembly stations, and **expression operators** are the
53+
specialized tools.
54+
55+
Comparing Aggregation and Query Operations
56+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
Using query operations, such as the ``find()`` method, you can perform the following actions:
59+
60+
- Select *which documents* to return
61+
- Select *which fields* to return
62+
- Sort the results
63+
64+
Using aggregation operations, you can perform the following actions:
65+
66+
- Perform all query operations
67+
- Rename fields
68+
- Calculate fields
69+
- Summarize data
70+
- Group values
71+
72+
Aggregation operations have some :manual:`limitations </core/aggregation-pipeline-limits/>`:
73+
74+
- Returned documents must not violate the :manual:`BSON-document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
75+
of 16 megabytes.
76+
77+
- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
78+
limit by setting the ``allowDiskUse`` property of ``AggregateOptions`` to ``true``. See
79+
the `AggregateOptions API documentation <{+api+}/interfaces/AggregateOptions.html>`__
80+
for more details.
81+
82+
.. important:: $graphLookup exception
83+
84+
The :manual:`$graphLookup
85+
</reference/operator/aggregation/graphLookup/>` stage has a strict
86+
memory limit of 100 megabytes and will ignore ``allowDiskUse``.
87+
88+
References
89+
~~~~~~~~~~
90+
91+
To view a full list of expression operators, see :manual:`Aggregation
92+
Operators </reference/operator/aggregation/>` in the Server manual.
93+
94+
To learn about assembling an aggregation pipeline and view examples, see
95+
:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the
96+
Server manual.
97+
98+
To learn more about creating pipeline stages, see :manual:`Aggregation
99+
Stages </reference/operator/aggregation-pipeline/>` in the Server manual.
100+
101+
Runnable Examples
102+
-----------------
103+
104+
The example uses sample data about restaurants. The following code
105+
inserts data into the ``restaurants`` collection of the ``aggregation``
106+
database:
107+
108+
.. literalinclude:: /code-snippets/aggregation/agg.js
109+
:start-after: begin data insertion
110+
:end-before: end data insertion
111+
:language: javascript
112+
:dedent:
113+
114+
.. tip::
115+
116+
For more information on connecting to your MongoDB deployment, see the :doc:`Connection Guide </connect>`.
117+
118+
Aggregation Example
119+
~~~~~~~~~~~~~~~~~~~
120+
121+
To perform an aggregation, pass a list of aggregation stages to the
122+
``collection.aggregate()`` method.
123+
124+
In the example, the aggregation pipeline uses the following aggregation stages:
125+
126+
- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents whose
127+
``categories`` array field contains the element ``Bakery``.
128+
129+
- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching documents by the ``stars``
130+
field, accumulating a count of documents for each distinct value of ``stars``.
131+
132+
.. literalinclude:: /code-snippets/aggregation/agg.js
133+
:start-after: begin aggregation
134+
:end-before: end aggregation
135+
:language: javascript
136+
:dedent:
137+
138+
This example produces the following output:
139+
140+
.. code-block:: json
141+
:copyable: false
142+
143+
{ _id: 4, count: 2 }
144+
{ _id: 3, count: 1 }
145+
{ _id: 5, count: 1 }
146+
147+
For more information, see the `aggregate() API documentation <{+api+}/classes/Collection.html#aggregate>`__.
148+
149+
Additional Examples
150+
~~~~~~~~~~~~~~~~~~~
151+
152+
You can find another aggregation pipeline example in the `Aggregation
153+
Framework with Node.js Tutorial
154+
<https://www.mongodb.com/blog/post/quick-start-nodejs--mongodb--how-to-analyze-data-using-the-aggregation-framework>`_
155+
blog post on the MongoDB website.

0 commit comments

Comments
 (0)