Skip to content

Commit ddf178e

Browse files
lindseymoorelindseymoore
authored
Merge branch 'master' into DOCSP-41121-create-mongoclient
2 parents 737405f + 7f97934 commit ddf178e

37 files changed

+3398
-71
lines changed

‎snooty.toml

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ toc_landing_pages = [
1313
"/connect",
1414
"/indexes",
1515
"work-with-indexes",
16-
"/data-formats"
16+
"/data-formats",
17+
"/builders",
18+
"/aggregation"
1719
]
1820

1921
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -27,7 +29,7 @@ full-version = "{+version-number+}.2"
2729
version = "v{+version-number+}"
2830
mdb-server = "MongoDB Server"
2931
stable-api = "Stable API"
30-
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"
3133
java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
32-
core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
34+
core-api = "{+java-api+}/apidocs/mongodb-driver-core"
3335
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/builders.txt

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _kotlin-sync-builders:
2+
3+
=========================
4+
Use Builders Code Pattern
5+
=========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. .. toctree::
14+
15+
.. /fundamentals/builders/aggregates
16+
.. /fundamentals/builders/filters
17+
.. /fundamentals/builders/indexes
18+
.. /fundamentals/builders/projections
19+
.. /fundamentals/builders/sort
20+
.. /fundamentals/builders/updates
21+
22+
Overview
23+
--------
24+
25+
This page describes how to use the various available builders in your code and describes
26+
benefits of using the provided builders.
27+
28+
The {+driver-short+} provides type-safe builder classes and methods that enable developers to
29+
efficiently build queries and aggregations.
30+
31+
Why Use Builders?
32+
-----------------
33+
34+
If you use only plain {+language+} to construct BSON query documents, you are not
35+
able to identify syntax errors until runtime. The builders help ensure the corretness of
36+
syntax and can be less verbose than constructing BSON documents.
37+
38+
Example
39+
-------
40+
41+
This section provides three equivalent ways to fetch the ``email`` field values of documents
42+
in the ``users`` collection that meet the following criteria:
43+
44+
- ``gender`` value is ``"female"``
45+
- ``age`` value is greater than ``29``
46+
47+
The following data class models the documents in the ``users`` collection:
48+
49+
.. literalinclude:: /includes/builders/builders.kt
50+
:start-after: start-user-class
51+
:end-before: end-user-class
52+
:language: kotlin
53+
:copyable:
54+
:dedent:
55+
56+
The following data class models the results returned by our query:
57+
58+
.. literalinclude:: /includes/builders/builders.kt
59+
:start-after: start-result-class
60+
:end-before: end-result-class
61+
:language: kotlin
62+
:copyable:
63+
:dedent:
64+
65+
MongoDB Query API
66+
~~~~~~~~~~~~~~~~~
67+
68+
The following sample performs the query by using the MongoDB Query API:
69+
70+
.. code-block:: js
71+
72+
collection.find(
73+
{ "gender": "female", "age" : { "$gt": 29 }},
74+
{ "_id": 0, "email": 1 }
75+
)
76+
77+
Document Class Filter
78+
~~~~~~~~~~~~~~~~~~~~~
79+
80+
The following example performs the query by using the ``Document`` class to construct the
81+
query filter:
82+
83+
.. literalinclude:: /includes/builders/builders.kt
84+
:start-after: start-find
85+
:end-before: end-find
86+
:language: kotlin
87+
:copyable:
88+
:dedent:
89+
90+
Builders
91+
~~~~~~~~
92+
93+
The following example performs the query by using the builder helpers:
94+
95+
.. literalinclude:: /includes/builders/builders.kt
96+
:start-after: start-find-builders
97+
:end-before: end-find-builders
98+
:language: kotlin
99+
:copyable:
100+
:dedent:
101+
102+
.. TODO: Uncomment as pages get built
103+
104+
.. Available Builders
105+
.. ------------------
106+
107+
.. The following pages describe how to implement the different classes of builders
108+
.. available in the {+driver-short+}.
109+
110+
.. - :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
111+
.. - :ref:`Filters <filters-builders>` for building query filters.
112+
.. - :ref:`Indexes <indexes-builders>` for creating index keys.
113+
.. - :ref:`Projections <projections-builders>` for building projections.
114+
.. - :ref:`Sorts <sorts-builders>` for building sort criteria.
115+
.. - :ref:`Updates <updates-builders>` for building updates.

‎source/connect.txt

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

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

2525
/connect/mongoclient
2626
/connect/stable-api
2727
/connect/connection-options
28+
/connect/connection-targets
2829

29-
.. /connect/connection-targets
3030
.. /connect/tls
3131
.. /connect/network-compression
3232
.. /connect/server-selection
@@ -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

0 commit comments

Comments
 (0)