Skip to content

Commit 46bb6d5

Browse files
mcmorisimcmorisi
authored
DOCSP-43088: Aggregations (#38)
1 parent a294fdc commit 46bb6d5

File tree

4 files changed

+278
-11
lines changed

4 files changed

+278
-11
lines changed

‎source/aggregation.txt‎

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

‎source/get-started.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _c-get-started:
22

33
=============================
4-
Get Started with the {+driver-short+}
4+
Get Started with the C Driver
55
=============================
66

77
.. contents:: On this page

‎source/includes/aggregation/aggregation.c‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
#include <bson/bson.h>
2+
#include <mongoc/mongoc.h>
3+
#include <stdio.h>
4+
5+
int
6+
main (int argc, char *argv[])
7+
{
8+
mongoc_client_t *client;
9+
mongoc_collection_t *collection;
10+
mongoc_init ();
11+
12+
client =
13+
mongoc_client_new ("<connection string URI>");
14+
collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants");
15+
16+
{
17+
// Executes an aggregation pipeline containing the $match and $group stages and prints the results
18+
// start-aggregation-pipeline
19+
const bson_t *doc;
20+
bson_t *pipeline = BCON_NEW ("pipeline",
21+
"[",
22+
"{", "$match", "{", "cuisine", BCON_UTF8 ("Bakery"), "}", "}",
23+
"{", "$group", "{",
24+
"_id", BCON_UTF8 ("$borough"), "count", "{", "$sum", BCON_INT32 (1), "}", "}",
25+
"}",
26+
"]");
27+
28+
mongoc_cursor_t *results =
29+
mongoc_collection_aggregate (collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL);
30+
31+
bson_error_t error;
32+
if (mongoc_cursor_error (results, &error))
33+
{
34+
fprintf (stderr, "Aggregate failed: %s\n", error.message);
35+
} else {
36+
while (mongoc_cursor_next (results, &doc)) {
37+
char *str = bson_as_canonical_extended_json (doc, NULL);
38+
printf ("%s\n", str);
39+
bson_free (str);
40+
}
41+
}
42+
43+
bson_destroy (pipeline);
44+
mongoc_cursor_destroy (results);
45+
// end-aggregation-pipeline
46+
}
47+
48+
{
49+
// Runs a command to explain the logic behind the aggregation
50+
// start-aggregation-explain
51+
bson_t reply;
52+
bson_error_t error;
53+
54+
bson_t *command = BCON_NEW (
55+
"aggregate", BCON_UTF8 ("restaurants"),
56+
"explain", BCON_BOOL(true),
57+
"pipeline",
58+
"[",
59+
"{", "$match", "{", "cuisine", BCON_UTF8("Bakery"), "}", "}",
60+
"{", "$group", "{",
61+
"_id", BCON_UTF8("$borough"), "count", "{", "$sum", BCON_INT32(1), "}", "}",
62+
"}",
63+
"]");
64+
65+
if (mongoc_client_command_simple (client, "sample_restaurants", command, NULL, &reply, &error)) {
66+
char *str = bson_as_canonical_extended_json (&reply, NULL);
67+
printf ("%s\n", str);
68+
bson_free (str);
69+
} else {
70+
fprintf (stderr, "Command failed: %s\n", error.message);
71+
}
72+
73+
bson_destroy (command);
74+
bson_destroy (&reply);
75+
// end-aggregation-explain
76+
}
77+
78+
mongoc_collection_destroy (collection);
79+
mongoc_client_destroy (client);
80+
mongoc_cleanup ();
81+
82+
return EXIT_SUCCESS;
83+
}

‎source/index.txt‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@
66
:titlesonly:
77
:maxdepth: 1
88

9-
/get-started
9+
Get Started </get-started>
1010
/databases-collections
1111
/read
12+
/aggregation
1213
/whats-new
1314
libbson API Documentation <{+api-libbson+}>
1415
libmongoc API Documentation <{+api-libmongoc+}>
@@ -65,16 +66,11 @@ Learn how you can retrieve data from MongoDB in the :ref:`c-read` section.
6566
.. Learn how to work with common types of indexes in the :ref:`c-indexes`
6667
.. section.
6768

68-
.. TODO
69-
.. Transform Your Data with Aggregation
70-
.. ------------------------------------
71-
72-
.. Learn how to use the {+driver-short+} to perform aggregation operations in the
73-
.. :ref:`c-aggregation` section.
74-
75-
.. Learn how to use aggregation expression operations to build
76-
.. aggregation stages in the :ref:`c-aggregation-expression-operations` section.
69+
Transform Your Data with Aggregation
70+
------------------------------------
7771

72+
Learn how to use the {+driver-short+} to perform aggregation operations in the
73+
:ref:`c-aggregation` section.
7874

7975
.. TODO:
8076
.. FAQ

0 commit comments

Comments
 (0)