Skip to content

Commit aaddbf3

Browse files
mcmorisimcmorisi
authored
Merge standardization branch into master (#70)
1 parent d62e856 commit aaddbf3

File tree

281 files changed

+11379
-13727
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

281 files changed

+11379
-13727
lines changed

‎.gitignore

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Binaries for programs and plugins
2+
*.exe
3+
*.exe~
4+
*.dll
5+
*.so
6+
*.dylib
7+
8+
# Dependency directories (remove the comment below to include it)
9+
# vendor/
10+
11+
# Editor
12+
.vscode
13+
.idea
14+
15+
# System
16+
17+
.DS_Store

‎snooty.toml

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,23 @@
11
name = "c"
22
title = "C Driver"
33

4-
intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
5-
"https://www.mongodb.com/docs/atlas/objects.inv",
6-
"https://www.mongodb.com/docs/drivers/objects.inv",
7-
]
4+
intersphinx = [
5+
"https://www.mongodb.com/docs/manual/objects.inv",
6+
"https://www.mongodb.com/docs/atlas/objects.inv",
7+
"https://www.mongodb.com/docs/drivers/objects.inv",
8+
]
89

910
toc_landing_pages = [
10-
"/libbson",
11-
"/libbson/tutorials",
12-
"/libbson/guides",
13-
"/libbson/cross-platform-notes",
14-
"/libbson/tutorial",
15-
"/libmongoc",
16-
"/libmongoc/guides",
17-
"/libmongoc/howto",
18-
"/libmongoc/ref",
19-
"/libmongoc/tutorials",
20-
"/libmongoc/tutorials/obtaining-libraries",
21-
]
11+
"/databases-collections",
12+
"/read",
13+
"/get-started",
14+
"/indexes",
15+
"/work-with-indexes",
16+
"/connect",
17+
"/write",
18+
"/security"
19+
]
20+
2221
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
2322

2423
[constants]
@@ -31,3 +30,10 @@ api-is-experimental = "This API {+is-experimental+}"
3130
opt-is-experimental = "This option {+is-experimental+}"
3231
api-libbson = "https://mongoc.org/libbson/current"
3332
api-libmongoc = "https://mongoc.org/libmongoc/current"
33+
driver-long = "MongoDB C Driver"
34+
driver-short = "C driver"
35+
language = "C"
36+
mdb-server = "MongoDB Server"
37+
stable-api = "Stable API"
38+
libmongoc = "libmongoc"
39+
libbson = "libbson"

‎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>`__

0 commit comments

Comments
 (0)