Skip to content

Commit 8629e29

Browse files
mongoKartmongoKart
authored
Merge cpp-standardization into master (#52)
1 parent 9b14279 commit 8629e29

File tree

90 files changed

+8265
-248
lines changed

Some content is hidden

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

90 files changed

+8265
-248
lines changed

‎snooty.toml

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,15 @@ intersphinx = [
99

1010
toc_landing_pages = [
1111
"/installation",
12-
"/api-abi-versioning"
13-
]
12+
"/api-abi-versioning",
13+
"/get-started",
14+
"/connect",
15+
"/read",
16+
"/write",
17+
"/indexes",
18+
"/security",
19+
"/data-formats",
20+
]
1421

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

@@ -20,4 +27,8 @@ driver-long = "MongoDB C++ Driver"
2027
driver-short = "C++ driver"
2128
version = "3.10"
2229
full-version = "{+version+}.2"
23-
api = "https://mongocxx.org/api/current"
30+
api = "https://mongocxx.org/api/current"
31+
string-data-type = "``string``"
32+
int-data-type = "``int``"
33+
stable-api = "Stable API"
34+
mdb-server = "MongoDB Server"

‎source/aggregation.txt

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
.. _cpp-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+
.. TODO:
22+
.. toctree::
23+
:titlesonly:
24+
:maxdepth: 1
25+
26+
/aggregation/aggregation-tutorials
27+
28+
Overview
29+
--------
30+
31+
In this guide, you can learn how to use the {+driver-short+} to perform
32+
**aggregation operations**.
33+
34+
Aggregation operations process data in your MongoDB collections and
35+
return computed results. The MongoDB Aggregation framework, which is
36+
part of the Query API, is modeled on the concept of data processing
37+
pipelines. Documents enter a pipeline that contains one or more stages,
38+
and this pipeline transforms the documents into an aggregated result.
39+
40+
An aggregation operation is similar to a car factory. A car factory has
41+
an assembly line, which contains assembly stations with specialized
42+
tools to do specific jobs, like drills and welders. Raw parts enter the
43+
factory, and then the assembly line transforms and assembles them into a
44+
finished product.
45+
46+
The **aggregation pipeline** is the assembly line, **aggregation stages** are the
47+
assembly stations, and **operator expressions** are the
48+
specialized tools.
49+
50+
Aggregation Versus Find Operations
51+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52+
53+
You can use find operations to perform the following actions:
54+
55+
- Select which documents to return
56+
- Select which fields to return
57+
- Sort the results
58+
59+
You can use aggregation operations to perform the following actions:
60+
61+
- Run find operations
62+
- Rename fields
63+
- Calculate fields
64+
- Summarize data
65+
- Group values
66+
67+
Limitations
68+
~~~~~~~~~~~
69+
70+
Keep the following limitations in mind when using aggregation operations:
71+
72+
- Returned documents cannot violate the
73+
:manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
74+
of 16 megabytes.
75+
- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
76+
limit by setting the ``allow_disk_use`` field of a ``mongocxx::options::aggregate``
77+
instance to ``true``.
78+
79+
.. important:: $graphLookup Exception
80+
81+
The :manual:`$graphLookup
82+
</reference/operator/aggregation/graphLookup/>` stage has a strict
83+
memory limit of 100 megabytes and ignores the ``allow_disk_use`` field.
84+
85+
.. _cpp-aggregation-example:
86+
87+
Aggregation Example
88+
-------------------
89+
90+
.. note::
91+
92+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
93+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
94+
free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
95+
</getting-started>` guide.
96+
97+
To perform an aggregation, pass a ``mongocxx::pipeline`` instance containing the aggregation
98+
stages to the ``collection.aggregate()`` method.
99+
100+
The following code example produces a count of the number of bakeries in each borough
101+
of New York. To do so, it uses an aggregation pipeline that contains the following stages:
102+
103+
- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
104+
in which the ``cuisine`` field contains the value ``"Bakery"``
105+
106+
- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
107+
documents by the ``borough`` field, accumulating a count of documents for each distinct
108+
value
109+
110+
.. io-code-block::
111+
112+
.. input:: /includes/aggregation.cpp
113+
:start-after: start-match-group
114+
:end-before: end-match-group
115+
:language: cpp
116+
:dedent:
117+
118+
.. output::
119+
120+
{ "_id" : "Brooklyn", "count" : 173 }
121+
{ "_id" : "Queens", "count" : 204 }
122+
{ "_id" : "Bronx", "count" : 71 }
123+
{ "_id" : "Staten Island", "count" : 20 }
124+
{ "_id" : "Missing", "count" : 2 }
125+
{ "_id" : "Manhattan", "count" : 221 }
126+
127+
Explain an Aggregation
128+
~~~~~~~~~~~~~~~~~~~~~~
129+
130+
To view information about how MongoDB executes your operation, you can
131+
instruct the MongoDB query planner to **explain** it. When MongoDB explains
132+
an operation, it returns **execution plans** and performance statistics.
133+
An execution plan is a potential way MongoDB can complete an operation.
134+
When you instruct MongoDB to explain an operation, it returns both the
135+
plan MongoDB executed and any rejected execution plans.
136+
137+
To explain an aggregation operation, run the ``explain`` database command by specifying
138+
the command in a BSON document and passing it as an argument to the ``run_command()``
139+
method.
140+
141+
The following example instructs MongoDB to explain the aggregation operation from the
142+
preceding :ref:`cpp-aggregation-example`:
143+
144+
.. io-code-block::
145+
146+
.. input:: /includes/aggregation.cpp
147+
:start-after: start-explain
148+
:end-before: end-explain
149+
:language: cpp
150+
:dedent:
151+
152+
.. output::
153+
154+
{ "explainVersion" : "2", "queryPlanner" : { "namespace" : "sample_restaurants.restaurants",
155+
"indexFilterSet" : false, "parsedQuery" : { "cuisine" : { "$eq" : "Bakery" } }, "queryHash":
156+
"...", "planCacheKey" : "...", "optimizedPipeline" : true, "maxIndexedOrSolutionsReached":
157+
false, "maxIndexedAndSolutionsReached" : false, "maxScansToExplodeReached" : false,
158+
"winningPlan" : { ... }
159+
... }
160+
161+
162+
Additional Information
163+
----------------------
164+
165+
MongoDB Server Manual
166+
~~~~~~~~~~~~~~~~~~~~~
167+
168+
To view a full list of expression operators, see :manual:`Aggregation
169+
Operators. </reference/operator/aggregation/>`
170+
171+
To learn about assembling an aggregation pipeline and view examples, see
172+
:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>`
173+
174+
To learn more about creating pipeline stages, see :manual:`Aggregation
175+
Stages. </reference/operator/aggregation-pipeline/>`
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/>`
180+
181+
.. TODO:
182+
Aggregation Tutorials
183+
~~~~~~~~~~~~~~~~~~~~~
184+
185+
.. To view step-by-step explanations of common aggregation tasks, see
186+
.. :ref:`cpp-aggregation-tutorials-landing`.
187+
188+
API Documentation
189+
~~~~~~~~~~~~~~~~~
190+
191+
For more information about executing aggregation operations with the {+driver-short+},
192+
see the following API documentation:
193+
194+
- `aggregate() <{+api+}/classmongocxx_1_1v__noabi_1_1collection.html#a480f6d0f9986d43b1d17d6ed8876941d>`__
195+
- `mongocxx::options::aggregate <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1aggregate.html>`__

‎source/compatibility.txt

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _cpp-compatibility-tables:
2+
3+
=============
4+
Compatibility
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: reference
16+
17+
.. meta::
18+
:keywords: backwards compatibility, versions, upgrade
19+
20+
MongoDB Compatibility
21+
---------------------
22+
23+
The following compatibility table specifies the recommended version or versions
24+
of the {+driver-long+} for use with a specific version of MongoDB.
25+
26+
The first column lists the driver version.
27+
28+
.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
29+
30+
.. sharedinclude:: dbx/compatibility-table-legend.rst
31+
32+
.. include:: /includes/mongodb-compatibility-table-cxx.rst
33+
34+
Language Compatibility
35+
----------------------
36+
37+
The following compatibility table specifies the recommended version of the
38+
{+driver-long+} for use with a specific version of C++.
39+
40+
The first column lists the driver version.
41+
42+
.. include:: /includes/language-compatibility-table-cxx.rst
43+
44+
For more information on how to read the compatibility tables, see our guide on
45+
:ref:`MongoDB Compatibility Tables. <about-driver-compatibility>`

0 commit comments

Comments
 (0)