Skip to content

Commit a9401cc

Browse files
mballard-mdbmballard-mdb
authored
DOCSP-50497 Node Aggregation Standardization (#1176) (#1180)
* DOCSP-50497 fixing git rebases and uploading changes to agg pages * DOCSP-50497 fix errors * DOCSP-50497 fix errors * DOCSP-50497 fix errors * DOCSP-50497 final changes * DOCSP-41784 Support for Explicit Resource Management (#1165) * DOCSP-41784 add support for explicit resource management note where applicable resources are declared * DOCSP-41784 fix note format * DOCSP-41784 change to tip and move pages around * DOCSP-41784 reword tip for clarity * DOCSP-41784 update backport file and move tips to below code examples * Add redirect for quick start landing page (#1171) * DOCSP-50497 suggestions * DOCSP=50497 final changes * revert "Add redirect for quick start landing page (#1171)" This reverts commit e7a22e5. revert commit * Revert "DOCSP-41784 Support for Explicit Resource Management (#1165)" This reverts commit 8f0f343. * DOCSP-50497 removing commits * DOCSP-50497 remove capital in aggregate method * DOCSP-50497 edits * DOCSP-50497 tweaks * DOCSP-50497 tech review comments * DOCSP-50497 edits (cherry picked from commit 35a4f2f)
1 parent 2b15cb2 commit a9401cc

File tree

3 files changed

+402
-120
lines changed

3 files changed

+402
-120
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ toc_landing_pages = [
1313
"/security/authentication",
1414
"/data-formats",
1515
"/connect/connection-options",
16+
"/aggregation",
1617
"/crud",
1718
"/crud/update",
1819
"/crud/transactions",

‎source/aggregation.txt

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

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

88
.. meta::
99
:description: Learn to use aggregation operations in the MongoDB Node.js Driver to create pipelines for data transformation and summarization.
@@ -15,18 +15,27 @@ Aggregation
1515
:depth: 2
1616
:class: singlecol
1717

18+
.. toctree::
19+
:titlesonly:
20+
:maxdepth: 1
21+
22+
Pipeline Stages </aggregation/pipeline-stages>
23+
1824
.. _nodejs-aggregation-overview:
1925

2026
Overview
2127
--------
2228

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

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

3140
.. _node-aggregation-tutorials:
3241

@@ -39,114 +48,67 @@ each of which performs a specific operation on your data.
3948
Analogy
4049
~~~~~~~
4150

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

0 commit comments

Comments
 (0)