Skip to content

Commit 1cf7cfb

Browse files
mcmorisimcmorisi
committed
DOCSP-41145: Aggregation landing page
1 parent ae8646c commit 1cf7cfb

File tree

4 files changed

+265
-1
lines changed

4 files changed

+265
-1
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ toc_landing_pages = [
1313
"/connect",
1414
"/indexes",
1515
"work-with-indexes",
16-
"/data-formats"
16+
"/data-formats",
17+
"/aggregation"
1718
]
1819

1920
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

‎source/aggregation.txt

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
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+
Aggregation operations 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 data processing
36+
pipelines. Documents enter a pipeline that contains one or more stages,
37+
and this pipeline transforms the documents into an aggregated result.
38+
39+
An aggregation operation is 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+
Aggregation Versus 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+
Keep the following limitations in mind 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 of the
76+
``AggregateIterable`` type.
77+
78+
.. important:: $graphLookup exception
79+
80+
The :manual:`$graphLookup
81+
</reference/operator/aggregation/graphLookup/>` stage has a strict
82+
memory limit of 100 megabytes and ignores the ``allowDiskUse`` parameter.
83+
84+
Aggregation Example
85+
-------------------
86+
87+
The examples in this section use the ``restaurants`` collection in the ``sample_restaurants``
88+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
89+
free MongoDB Atlas cluster and load the sample datasets, see the
90+
:atlas:`Get Started with Atlas </getting-started>` guide.
91+
92+
The following {+language+} data class models the documents in this collection:
93+
94+
.. literalinclude:: /includes/aggregation/aggregation.kt
95+
:start-after: start-data-class
96+
:end-before: end-data-class
97+
:language: kotlin
98+
:copyable:
99+
100+
Build and Execute an Aggregation Pipeline
101+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102+
103+
To perform an aggregation, pass a list of aggregation stages to the
104+
``collection.aggregate()`` method.
105+
106+
The following code example produces a count of the number of bakeries in each borough
107+
of New York. To do so, it uses an aggregation pipeline with the following stages:
108+
109+
- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
110+
whose ``cuisine`` field contains the value ``"Bakery"``.
111+
112+
- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
113+
documents by the ``borough`` field, accumulating a count of documents for each distinct
114+
value.
115+
116+
.. io-code-block::
117+
118+
.. input:: /includes/aggregation/aggregation.kt
119+
:language: kotlin
120+
:start-after: start-aggregation-pipeline
121+
:end-before: end-aggregation-pipeline
122+
:dedent:
123+
124+
.. output::
125+
:visible: false
126+
127+
Document{{_id=Bronx, count=71}}
128+
Document{{_id=Manhattan, count=221}}
129+
Document{{_id=Brooklyn, count=173}}
130+
Document{{_id=Queens, count=204}}
131+
Document{{_id=Staten Island, count=20}}
132+
Document{{_id=Missing, count=2}}
133+
134+
Explain an Aggregation
135+
~~~~~~~~~~~~~~~~~~~~~~
136+
137+
To view information about how MongoDB executes your operation, you can
138+
instruct MongoDB to **explain** it. When MongoDB explains an operation, it returns
139+
**execution plans** and performance statistics. An execution
140+
plan is a potential way MongoDB can complete an operation.
141+
When you instruct MongoDB to explain an operation, it returns both the
142+
plan MongoDB executed and any rejected execution plans.
143+
144+
The following code example runs the preceding aggregation example and prints the returned
145+
explanation:
146+
147+
.. io-code-block::
148+
149+
.. input:: /includes/aggregation/aggregation.kt
150+
:language: kotlin
151+
:start-after: start-aggregation-explain
152+
:end-before: end-aggregation-explain
153+
:dedent:
154+
155+
.. output::
156+
:visible: false
157+
158+
{
159+
"explain": {
160+
"aggregate": "restaurants",
161+
"pipeline": [
162+
{
163+
"$match": {
164+
"cuisine": "Bakery"
165+
}
166+
},
167+
{
168+
"$group": {
169+
"_id": "$borough",
170+
"count": {
171+
"$sum": 1
172+
}
173+
}
174+
}
175+
],
176+
"cursor": {}
177+
},
178+
...
179+
}
180+
181+
Additional Information
182+
----------------------
183+
184+
To view a full list of expression operators, see :manual:`Aggregation
185+
Operators. </reference/operator/aggregation/>`
186+
187+
To learn about assembling an aggregation pipeline and view examples, see
188+
:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>`
189+
190+
To learn more about creating pipeline stages, see :manual:`Aggregation
191+
Stages. </reference/operator/aggregation-pipeline/>`
192+
193+
To learn more about explaining MongoDB operations, see
194+
:manual:`Explain Output </reference/explain-results/>` and
195+
:manual:`Query Plans. </core/query-plans/>`
196+
197+
.. Aggregation Tutorials
198+
.. ~~~~~~~~~~~~~~~~~~~~~
199+
200+
.. To view step-by-step explanations of common aggregation tasks, see
201+
.. :ref:`kotlin-sync-aggregation-tutorials`.
202+
203+
API Documentation
204+
~~~~~~~~~~~~~~~~~
205+
206+
For more information about executing aggregation operations with the {+driver-short+},
207+
see the following API documentation:
208+
209+
- `aggregate() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/aggregate.html>`__
210+
- `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
@@ -18,6 +18,7 @@
1818
/write-operations
1919
/read
2020
/indexes
21+
/aggregation
2122
/data-formats
2223
/faq
2324
/connection-troubleshooting
@@ -78,6 +79,12 @@ Optimize Queries with Indexes
7879
Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes`
7980
section.
8081

82+
Transform Your Data with Aggregation
83+
------------------------------------
84+
85+
Learn how to use the {+driver-short+} to perform aggregation operatoins in the
86+
:ref:`kotlin-sync-aggregation` section.
87+
8188
Specialized Data Formats
8289
------------------------
8390

0 commit comments

Comments
 (0)