Skip to content

Commit c2fb128

Browse files
rustagirjordan-smith721
rustagir
and
jordan-smith721
authored
Aggregation tutorials feature branch (#840)
* DOCSP-33630 one-to-one aggregation tutorial (#816) * DOCSP-34038: agg tutorials landing (#830) * DOCSP-34038: agg tut landing * full first draft * match files * small fixes * reverse coll order * RM PR fixes 1 * DOCSP-33631: multi-field join tutorial (#834) * DOCSP-33631: multi field join tut * add to available tuts * vale fix * some fixes * procedure style * NR PR fixes 1 * small fix * DOCSP-33632 Filtered Subset (#835) * DOCSP-33633: group total tutorial (#836) * DOCSP-33633: group total tut * first pass fixes * CC PR fixes 1 * small fixes * move delete statement * learning obj: * structure fixes + learning obj * small fixes * capitalization * DOCSP-34718: unpack arrays tutorial (#838) * DOCSP-34718: unpack arrays tut * vale fix * RM PR fixes * DOCSP-34717: agg tutorial cleanup + standardization (#839) * DOCSP-34717: agg tutorial cleanup/standardization * small wording fix * MW PR fixes 1 * small fixes * add interpret results step * add link to agg guide --------- Co-authored-by: Jordan Smith <[email protected]>
1 parent 9cae6dc commit c2fb128

16 files changed

+2041
-18
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ toc_landing_pages = [
1414
"/fundamentals/bson",
1515
"/usage-examples",
1616
"/quick-start",
17+
"/aggregation-tutorials",
1718
]
1819
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1920

‎source/aggregation-tutorials.txt

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _node-aggregation-tutorials-landing:
2+
3+
=====================
4+
Aggregation Tutorials
5+
=====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: node.js, code example, runnable app
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
.. toctree::
21+
22+
/aggregation-tutorials/filtered-subset/
23+
/aggregation-tutorials/group-total/
24+
/aggregation-tutorials/unpack-arrays/
25+
/aggregation-tutorials/one-to-one-join/
26+
/aggregation-tutorials/multi-field-join/
27+
28+
Overview
29+
--------
30+
31+
Aggregation tutorials provide detailed explanations of common
32+
aggregation tasks in a step-by-step format. The tutorials are adapted
33+
from examples in the `Practical MongoDB Aggregations book
34+
<https://www.practical-mongodb-aggregations.com/>`__ by Paul Done.
35+
36+
Each tutorial includes the following sections:
37+
38+
- **Introduction**, which describes the purpose and common use cases of the
39+
aggregation type. This section also describes the example and desired
40+
outcome that the tutorial demonstrates.
41+
42+
- **Before You Get Started**, which describes the necessary databases,
43+
collections, and sample data that you must have before building the
44+
aggregation pipeline and performing the aggregation.
45+
46+
- **Tutorial**, which describes how to build and run the aggregation
47+
pipeline. This section describes each stage of the completed
48+
aggregation tutorial, and then explains how to run and interpret the
49+
output of the aggregation.
50+
51+
At the end of each aggregation tutorial, you can find a link to a fully
52+
runnable Node.js code file that you can run in your environment.
53+
54+
.. tip::
55+
56+
To learn more about performing aggregations, see the
57+
:ref:`node-aggregation` guide.
58+
59+
.. _node-agg-tutorial-template-app:
60+
61+
Aggregation Template App
62+
------------------------
63+
64+
Before you begin following an aggregation tutorial, you must set up a
65+
new Node.js app. You can use this app to connect to a MongoDB
66+
deployment, insert sample data into MongoDB, and run the aggregation
67+
pipeline in each tutorial.
68+
69+
.. tip::
70+
71+
To learn how to install the driver and connect to MongoDB,
72+
see the :ref:`node-quick-start-download-and-install` and
73+
:ref:`node-quick-start-create-deployment` steps of the
74+
Quick Start guide.
75+
76+
Once you install the driver, create a file called
77+
``agg_tutorial.js``. Paste the following code in this file to create an
78+
app template for the aggregation tutorials:
79+
80+
.. literalinclude:: /includes/aggregation/template-app.js
81+
:language: javascript
82+
:copyable: true
83+
84+
.. important::
85+
86+
In the preceding code, read the code comments to find the sections of
87+
the code that you must modify for the tutorial you are following.
88+
89+
If you attempt to run the code without making any changes, you will
90+
encounter a connection error.
91+
92+
For every tutorial, you must replace the connection string placeholder with
93+
your deployment's connection string.
94+
95+
.. tip::
96+
97+
To learn how to locate your deployment's connection string, see the
98+
:ref:`node-quick-start-connection-string` step of the Quick Start guide.
99+
100+
For example, if your connection string is
101+
``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles
102+
the following:
103+
104+
.. code-block:: javascript
105+
:copyable: false
106+
107+
const uri = "mongodb+srv://mongodb-example:27017";
108+
109+
To run the completed file after you modify the template for a
110+
tutorial, run the following command in your shell:
111+
112+
.. code-block:: bash
113+
114+
node agg_tutorial.js
115+
116+
Available Tutorials
117+
-------------------
118+
119+
- :ref:`node-aggregation-filtered-subset`
120+
- :ref:`node-aggregation-group-total`
121+
- :ref:`node-aggregation-arrays`
122+
- :ref:`node-aggregation-one-to-one`
123+
- :ref:`node-aggregation-multi-field`

‎source/aggregation-tutorials/filtered-subset.txt

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
.. _node-aggregation-filtered-subset:
2+
3+
===============
4+
Filtered Subset
5+
===============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. meta::
18+
:keywords: code example, node.js, sort, limit, aggregation
19+
20+
Introduction
21+
------------
22+
23+
In this tutorial, you can learn how to use the {+driver-short+} to
24+
construct an aggregation pipeline, perform the
25+
aggregation on a collection, and print the results by completing and
26+
running a sample app. This aggregation performs the following operations:
27+
28+
- Matches a subset of documents by a field value
29+
- Formats result documents
30+
31+
.. tip::
32+
33+
You can also query for a subset of documents in a collection by using the
34+
Query API. To learn how to specify a query, see the
35+
:ref:`Read Operations guides <node-read-operations>`.
36+
37+
Aggregation Task Summary
38+
~~~~~~~~~~~~~~~~~~~~~~~~
39+
40+
This tutorial demonstrates how to query a collection for a specific
41+
subset of documents in a collection. The results contain
42+
documents that describe the three youngest people who are engineers.
43+
44+
This example uses one collection, ``persons``, which contains
45+
documents describing people. Each document includes a person's name,
46+
date of birth, vocation, and other details.
47+
48+
Before You Get Started
49+
----------------------
50+
51+
Before you start this tutorial, complete the
52+
:ref:`node-agg-tutorial-template-app` instructions to set up a working
53+
Node.js application.
54+
55+
After you set up the app, access the ``persons`` collection by adding the
56+
following code to the application:
57+
58+
.. literalinclude:: /includes/aggregation/filtered-subset.js
59+
:language: javascript
60+
:copyable: true
61+
:start-after: start-collection
62+
:end-before: end-collection
63+
:dedent:
64+
65+
Delete any existing data in the collections and insert sample data into
66+
the ``persons`` collection as shown in the following code:
67+
68+
.. literalinclude:: /includes/aggregation/filtered-subset.js
69+
:language: javascript
70+
:copyable: true
71+
:start-after: start-insert-persons
72+
:end-before: end-insert-persons
73+
:dedent:
74+
75+
Tutorial
76+
--------
77+
78+
.. procedure::
79+
:style: connected
80+
81+
.. step:: Add a match stage for people who are engineers
82+
83+
First, add a :manual:`$match
84+
</reference/operator/aggregation/match>` stage that finds documents in which
85+
the value of the ``vocation`` field is ``"ENGINEER"``:
86+
87+
.. literalinclude:: /includes/aggregation/filtered-subset.js
88+
:language: javascript
89+
:copyable: true
90+
:start-after: start-match
91+
:end-before: end-match
92+
:dedent:
93+
94+
.. step:: Add a sort stage to sort from youngest to oldest
95+
96+
Next, add a :manual:`$sort
97+
</reference/operator/aggregation/sort>` stage that sorts the
98+
documents in descending order by the ``dateofbirth`` field to
99+
list the youngest people first:
100+
101+
.. literalinclude:: /includes/aggregation/filtered-subset.js
102+
:language: javascript
103+
:copyable: true
104+
:start-after: start-sort
105+
:end-before: end-sort
106+
:dedent:
107+
108+
.. step:: Add a limit stage to see only three results
109+
110+
Next, add a :manual:`$limit </reference/operator/aggregation/limit>`
111+
stage to the pipeline to output only the first three documents in
112+
the results.
113+
114+
.. literalinclude:: /includes/aggregation/filtered-subset.js
115+
:language: javascript
116+
:copyable: true
117+
:start-after: start-limit
118+
:end-before: end-limit
119+
:dedent:
120+
121+
.. step:: Add an unset stage to remove unneeded fields
122+
123+
Finally, add an :manual:`$unset
124+
</reference/operator/aggregation/unset>` stage. The
125+
``$unset`` stage removes unnecessary fields from the result documents:
126+
127+
.. literalinclude:: /includes/aggregation/filtered-subset.js
128+
:language: javascript
129+
:copyable: true
130+
:start-after: start-unset
131+
:end-before: end-unset
132+
:dedent:
133+
134+
.. tip::
135+
136+
Use the ``$unset`` operator instead of ``$project`` to avoid
137+
modifying the aggregation pipeline if documents with
138+
different fields are added to the collection.
139+
140+
.. step:: Run the aggregation pipeline
141+
142+
Add the following code to the end of your application to perform
143+
the aggregation on the ``persons`` collection:
144+
145+
.. literalinclude:: /includes/aggregation/filtered-subset.js
146+
:language: javascript
147+
:copyable: true
148+
:start-after: start-run-agg
149+
:end-before: end-run-agg
150+
:dedent:
151+
152+
Finally, run the following command in your shell to start your
153+
application:
154+
155+
.. code-block:: bash
156+
157+
node agg_tutorial.js
158+
159+
.. step:: Interpret results
160+
161+
The aggregated result contains three documents. The documents
162+
represent the three youngest people with the vocation of ``"ENGINEER"``,
163+
ordered from youngest to oldest. The results omit the ``_id`` and ``address``
164+
fields.
165+
166+
.. code-block:: javascript
167+
:copyable: false
168+
169+
{
170+
person_id: '7363626383',
171+
firstname: 'Carl',
172+
lastname: 'Simmons',
173+
dateofbirth: 1998-12-26T13:13:55.000Z,
174+
vocation: 'ENGINEER'
175+
}
176+
{
177+
person_id: '1723338115',
178+
firstname: 'Olive',
179+
lastname: 'Ranieri',
180+
dateofbirth: 1985-05-12T23:14:30.000Z,
181+
gender: 'FEMALE',
182+
vocation: 'ENGINEER'
183+
}
184+
{
185+
person_id: '6392529400',
186+
firstname: 'Elise',
187+
lastname: 'Smith',
188+
dateofbirth: 1972-01-13T09:32:07.000Z,
189+
vocation: 'ENGINEER'
190+
}
191+
192+
To view the complete code for this tutorial, see the `Completed Filtered Subset App
193+
<https://github.com/mongodb/docs-node/tree/master/source/includes/aggregation/filtered-subset.js>`__
194+
on GitHub.

0 commit comments

Comments
 (0)