Skip to content

Commit 82f255f

Browse files
mcmorisimcmorisi
authored
Merge branch 'master' into DOCSP-41161-builders
2 parents 4c49729 + 7ee3261 commit 82f255f

35 files changed

+3136
-70
lines changed

‎snooty.toml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ toc_landing_pages = [
1515
"work-with-indexes",
1616
"/data-formats",
1717
"/builders"
18+
"/aggregation"
1819
]
1920

2021
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -28,7 +29,7 @@ full-version = "{+version-number+}.2"
2829
version = "v{+version-number+}"
2930
mdb-server = "MongoDB Server"
3031
stable-api = "Stable API"
31-
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
32+
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync"
3233
java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
33-
core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
34+
core-api = "{+java-api+}/apidocs/mongodb-driver-core"
3435
kotlin-docs = "https://kotlinlang.org"

‎source/agg-exp-ops.txt

Lines changed: 1180 additions & 0 deletions
Large diffs are not rendered by default.

‎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/connect.txt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ Connect to MongoDB
1919
:keywords: client, ssl, tls, localhost
2020

2121
.. toctree::
22-
:titlesonly:
23-
:maxdepth: 1
22+
:titlesonly:
23+
:maxdepth: 1
2424

25-
/connect/stable-api
26-
..
25+
/connect/stable-api
26+
/connect/connection-targets
27+
2728
.. /connect/mongoclient
28-
.. /connect/connection-targets
2929
.. /connect/connection-options
3030
.. /connect/tls
3131
.. /connect/network-compression
@@ -84,7 +84,7 @@ deployment hosted on Atlas:
8484

8585
.. code-block:: kotlin
8686

87-
val uri = "mongodb+srv://<username>:<password>@<hostname/port>/?<options>"
87+
val uri = "mongodb+srv://<db_username>:<db_password>@<hostname/port>/?<options>"
8888
val mongoClient = MongoClient.create(uri)
8989

9090
Replica Set
@@ -161,7 +161,7 @@ selection function:
161161

162162
.. code-block:: kotlin
163163

164-
val client = MongoClient.create("mongodb://<username>:<password>@<hostname>:<port>",
164+
val client = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>",
165165
server_selector=<selector function>)
166166

167167
.. To learn more about customizing server selection, see

‎source/connect/connection-targets.txt

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
.. _kotlin-sync-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use a connection string and a ``MongoClient`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
Atlas
27+
-----
28+
29+
To connect to a MongoDB deployment on Atlas, include the following elements
30+
in your connection string:
31+
32+
- The URL of your Atlas cluster
33+
- Your MongoDB username
34+
- Your MongoDB password
35+
36+
Then, pass your connection string to the ``MongoClient`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
41+
to retrieve your connection string.
42+
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
44+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
45+
To learn more about the {+stable-api+} feature, see the :ref:`<kotlin-sync-stable-api>`
46+
guide.
47+
48+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49+
code also uses the ``serverApi()`` method to specify a {+stable-api+} version.
50+
51+
.. literalinclude:: /includes/connect/connection-targets.kt
52+
:language: kotlin
53+
:start-after: start-connect
54+
:end-before: end-connect
55+
:dedent:
56+
57+
Local Deployments
58+
-----------------
59+
60+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
61+
default, the ``mongod`` process runs on port 27017, though you can customize this for
62+
your deployment.
63+
64+
The following code shows how to use the {+driver-short+} to connect to a local MongoDB
65+
deployment:
66+
67+
.. literalinclude:: /includes/connect/connection-targets.kt
68+
:language: kotlin
69+
:start-after: start-connect-local
70+
:end-before: end-connect-local
71+
:dedent:
72+
73+
Replica Sets
74+
------------
75+
76+
To connect to a replica set, specify the hostnames (or IP addresses) and
77+
port numbers of the replica-set members.
78+
79+
If you aren't able to provide a full list of hosts in the replica set, you can
80+
specify one or more of the hosts in the replica set and instruct the {+driver-short+} to
81+
perform automatic discovery to find the others. To instruct the driver to perform
82+
automatic discovery, perform one of the following actions:
83+
84+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
85+
- Specify ``false`` as the value of the ``directConnection`` parameter.
86+
- Specify more than one host in the replica set.
87+
88+
The following examples show how to connect to a MongoDB replica set running on port
89+
``27017`` of three different hosts by using either the ``ConnectionString`` or
90+
``MongoClientSettings`` class. Select the tab that corresponds to your preferred class.
91+
92+
.. tabs::
93+
94+
.. tab:: ConnectionString
95+
:tabid: connectionstring
96+
97+
.. literalinclude:: /includes/connect/connection-targets.kt
98+
:language: kotlin
99+
:start-after: start-connect-rs-connection-string
100+
:end-before: end-connect-rs-connection-string
101+
:dedent:
102+
103+
.. tab:: MongoClientSettings
104+
:tabid: mongoclientsettings
105+
106+
.. literalinclude:: /includes/connect/connection-targets.kt
107+
:language: kotlin
108+
:start-after: start-connect-rs-settings
109+
:end-before: end-connect-rs-settings
110+
:dedent:
111+
112+
.. note::
113+
114+
The ``MongoClient`` constructor is *non-blocking*.
115+
When you connect to a replica set, the constructor returns immediately while the
116+
client uses background threads to connect to the replica set.
117+
118+
If you construct a ``MongoClient`` and immediately print the string representation
119+
of its ``nodes`` attribute, the list might be empty while the client connects to
120+
the replica-set members.

0 commit comments

Comments
 (0)