Skip to content

Commit 14ae792

Browse files
mcmorisimcmorisi
committed
DOCSP-41145: Aggregation landing page (#30)
(cherry picked from commit 88f71b9)
1 parent 6891133 commit 14ae792

File tree

4 files changed

+275
-1
lines changed

4 files changed

+275
-1
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ toc_landing_pages = [
1010
"/read",
1111
"/indexes",
1212
"work-with-indexes",
13-
"/data-formats"
13+
"/data-formats",
14+
"/aggregation"
1415
]
1516

1617
[constants]

‎source/aggregation.txt

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
.. _kotlin-sync-aggregation:
2+
3+
====================================
4+
Transform Your Data with Aggregation
5+
====================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, transform, computed, pipeline
13+
:description: Learn how to use the Kotlin Sync driver to perform aggregation operations.
14+
15+
.. contents:: On this page
16+
:local:
17+
:backlinks: none
18+
:depth: 2
19+
:class: singlecol
20+
21+
.. .. toctree::
22+
.. :titlesonly:
23+
.. :maxdepth: 1
24+
25+
.. /aggregation/aggregation-tutorials
26+
27+
Overview
28+
--------
29+
30+
In this guide, you can learn how to use the {+driver-short+} to perform
31+
**aggregation operations**.
32+
33+
You can use aggregation operations to process data in your MongoDB collections and
34+
return computed results. The MongoDB Aggregation framework, which is
35+
part of the Query API, is modeled on the concept of a data processing
36+
pipeline. Documents enter a pipeline that contains one or more stages,
37+
and each stage transforms the documents to output a final aggregated result.
38+
39+
You can think of an aggregation operation as similar to a car factory. A car factory has
40+
an assembly line, which contains assembly stations with specialized
41+
tools to do specific jobs, like drills and welders. Raw parts enter the
42+
factory, and then the assembly line transforms and assembles them into a
43+
finished product.
44+
45+
The **aggregation pipeline** is the assembly line, **aggregation stages** are the
46+
assembly stations, and **operator expressions** are the
47+
specialized tools.
48+
49+
Compare Aggregation and Find Operations
50+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+
You can use find operations to perform the following actions:
53+
54+
- Select which documents to return
55+
- Select which fields to return
56+
- Sort the results
57+
58+
You can use aggregation operations to perform the following actions:
59+
60+
- Perform find operations
61+
- Rename fields
62+
- Calculate fields
63+
- Summarize data
64+
- Group values
65+
66+
Limitations
67+
~~~~~~~~~~~
68+
69+
The following limitations apply when using aggregation operations:
70+
71+
- Returned documents must not violate the
72+
:manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
73+
of 16 megabytes.
74+
- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
75+
limit by using the ``allowDiskUse()`` method from ``AggregateIterable`` class.
76+
77+
.. important:: $graphLookup exception
78+
79+
The :manual:`$graphLookup
80+
</reference/operator/aggregation/graphLookup/>` stage has a strict
81+
memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
82+
83+
Aggregation Example
84+
-------------------
85+
86+
The examples in this section use the ``restaurants`` collection in the ``sample_restaurants``
87+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
88+
free MongoDB Atlas cluster and load the sample datasets, see the
89+
:atlas:`Get Started with Atlas </getting-started>` guide.
90+
91+
The following {+language+} data class models the documents in this collection:
92+
93+
.. literalinclude:: /includes/aggregation/aggregation.kt
94+
:start-after: start-data-class
95+
:end-before: end-data-class
96+
:language: kotlin
97+
:copyable:
98+
99+
Build and Execute an Aggregation Pipeline
100+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101+
102+
To perform an aggregation on the documents in a collection, pass a list of aggregation
103+
stages to the ``aggregate()`` method.
104+
105+
This example outputs a count of the number of bakeries in each borough
106+
of New York City. The following code creates aggregation pipeline that contains the
107+
following stages:
108+
109+
- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
110+
in which the value of the ``cuisine`` field is ``"Bakery"``.
111+
112+
- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
113+
documents by the ``borough`` field, producing a count of documents for each distinct
114+
value of that field.
115+
116+
.. TODO: uncomment when Aggregates Builder page is created
117+
118+
.. .. note::
119+
120+
.. The following example uses the builders pattern to implement the stages of an
121+
.. aggregation pipeline. To learn more about how to use the builders pattern, see
122+
.. :ref:`<aggregates-builders>`
123+
124+
.. io-code-block::
125+
126+
.. input:: /includes/aggregation/aggregation.kt
127+
:language: kotlin
128+
:start-after: start-aggregation-pipeline
129+
:end-before: end-aggregation-pipeline
130+
:dedent:
131+
132+
.. output::
133+
:visible: false
134+
135+
Document{{_id=Bronx, count=71}}
136+
Document{{_id=Manhattan, count=221}}
137+
Document{{_id=Brooklyn, count=173}}
138+
Document{{_id=Queens, count=204}}
139+
Document{{_id=Staten Island, count=20}}
140+
Document{{_id=Missing, count=2}}
141+
142+
.. tip::
143+
144+
When specifying a group key for the ``$group`` aggregation stage, ensure that you
145+
escape any ``$`` characters by using the ``\`` character.
146+
147+
Explain an Aggregation
148+
~~~~~~~~~~~~~~~~~~~~~~
149+
150+
To view information about how MongoDB executes your operation, you can
151+
include the ``$explain`` aggregation stage in your pipeline. When MongoDB explains an
152+
operation, it returns **execution plans** and performance statistics. An execution
153+
plan is a potential way MongoDB can complete an operation.
154+
When you instruct MongoDB to explain an operation, it returns both the
155+
plan MongoDB selected for the operation and any rejected execution plans.
156+
157+
The following code example runs the same aggregation shown in the preceding section
158+
and adds the ``$explain`` stage to output the operation details:
159+
160+
.. io-code-block::
161+
162+
.. input:: /includes/aggregation/aggregation.kt
163+
:language: kotlin
164+
:start-after: start-aggregation-explain
165+
:end-before: end-aggregation-explain
166+
:dedent:
167+
168+
.. output::
169+
:visible: false
170+
171+
{
172+
"explainVersion": "2",
173+
"queryPlanner": {
174+
"namespace": "sample_restaurants.restaurants"
175+
"indexFilterSet": false,
176+
"parsedQuery": {
177+
"cuisine": {"$eq": "Bakery"}
178+
},
179+
"queryHash": "865F14C3",
180+
"planCacheKey": "0697561B",
181+
"optimizedPipeline": true,
182+
"maxIndexedOrSolutionsReached": false,
183+
"maxIndexedAndSolutionsReached": false,
184+
"maxScansToExplodeReached": false,
185+
"winningPlan": { ... }
186+
...
187+
}
188+
...
189+
}
190+
191+
Additional Information
192+
----------------------
193+
194+
To view a full list of expression operators, see :manual:`Aggregation
195+
Operators </reference/operator/aggregation/>` in the {+mdb-server+} manual.
196+
197+
To learn about assembling an aggregation pipeline and view examples, see
198+
:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the {+mdb-server+} manual.
199+
200+
To learn more about creating pipeline stages, see :manual:`Aggregation
201+
Stages </reference/operator/aggregation-pipeline/>` in the {+mdb-server+} manual.
202+
203+
To learn more about explaining MongoDB operations, see
204+
:manual:`Explain Output </reference/explain-results/>` and
205+
:manual:`Query Plans </core/query-plans/>` in the {+mdb-server+} manual.
206+
207+
.. Aggregation Tutorials
208+
.. ~~~~~~~~~~~~~~~~~~~~~
209+
210+
.. To view step-by-step explanations of common aggregation tasks, see
211+
.. :ref:`kotlin-sync-aggregation-tutorials`.
212+
213+
API Documentation
214+
~~~~~~~~~~~~~~~~~
215+
216+
For more information about executing aggregation operations with the {+driver-short+},
217+
see the following API documentation:
218+
219+
- `aggregate() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/aggregate.html>`__
220+
- `AggregateIterable <{+api+}/com.mongodb.kotlin.client/-aggregate-iterable/index.html>`__

‎source/includes/aggregation/aggregation.kt

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.client.model.Accumulators
4+
import com.mongodb.client.model.Aggregates
5+
import com.mongodb.client.model.Filters
6+
import com.mongodb.kotlin.client.MongoClient
7+
import org.bson.Document
8+
9+
// start-data-class
10+
data class Restaurant(
11+
val name: String,
12+
val cuisine: String,
13+
val borough: String
14+
)
15+
// end-data-class
16+
17+
fun main() {
18+
val uri = "<connection string URI>"
19+
20+
val settings = MongoClientSettings.builder()
21+
.applyConnectionString(ConnectionString(uri))
22+
.retryWrites(true)
23+
.build()
24+
25+
val mongoClient = MongoClient.create(settings)
26+
val database = mongoClient.getDatabase("sample_restaurants")
27+
val collection = database.getCollection<Restaurant>("restaurants")
28+
29+
// start-aggregation-pipeline
30+
val pipeline = listOf(
31+
Aggregates.match(Filters.eq(Restaurant::cuisine.name, "Bakery")),
32+
Aggregates.group("\$borough", Accumulators.sum("count", 1))
33+
)
34+
35+
val results = collection.aggregate<Document>(pipeline)
36+
37+
results.forEach { result ->
38+
println(result)
39+
}
40+
// end-aggregation-pipeline
41+
42+
// start-aggregation-explain
43+
print(collection.aggregate(pipeline).explain())
44+
// end-aggregation-explain
45+
}
46+

‎source/index.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
/write-operations
1717
/read
1818
/indexes
19+
/aggregation
1920
/data-formats
2021
/faq
2122
/connection-troubleshooting
@@ -75,6 +76,12 @@ Optimize Queries with Indexes
7576
Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes`
7677
section.
7778

79+
Transform Your Data with Aggregation
80+
------------------------------------
81+
82+
Learn how to use the {+driver-short+} to perform aggregation operations in the
83+
:ref:`kotlin-sync-aggregation` section.
84+
7885
Specialized Data Formats
7986
------------------------
8087

0 commit comments

Comments
 (0)