Skip to content

Commit a315380

Browse files
mcmorisimcmorisi
authored
Merge branch 'master' into DOCSP-41508-TLS
2 parents abca930 + d45f795 commit a315380

File tree

15 files changed

+2579
-8
lines changed

15 files changed

+2579
-8
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ toc_landing_pages = [
1414
"/indexes",
1515
"work-with-indexes",
1616
"/data-formats",
17+
"/builders",
1718
"/aggregation"
1819
]
1920

‎source/agg-exp-ops.txt

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

‎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: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@ Connect to MongoDB
2222
:titlesonly:
2323
:maxdepth: 1
2424

25-
/connect/stable-api
25+
/connect/mongoclient
2626
/connect/connection-targets
27+
/connect/connection-options
2728
/connect/tls
29+
/connect/stable-api
2830

29-
.. /connect/mongoclient
30-
.. /connect/connection-options
3131
.. /connect/network-compression
3232
.. /connect/server-selection
3333
.. /connect/csot

‎source/connect/connection-options.txt

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _kotlin-sync-connection-options:
2+
3+
==========================
4+
Specify Connection Options
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: connection string, URI, server, Atlas, settings, configure
19+
20+
Overview
21+
--------

‎source/connect/mongoclient.txt

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _kotlin-sync-mongoclient:
2+
3+
====================
4+
Create a MongoClient
5+
====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, Atlas, 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+
To connect to a MongoDB deployment, you need two things:
24+
25+
- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+}
26+
which MongoDB deployment to connect to.
27+
- A **MongoClient** object, which creates the connection to and performs
28+
operations on the MongoDB deployment.
29+
30+
You can also use ``MongoClientSettings`` to customize the way the {+driver-short+} behaves
31+
while connected to MongoDB.
32+
33+
This guide shows you how to create a connection string and use a ``MongoClient`` object
34+
to connect to MongoDB.
35+
36+
.. _kotlin-sync-connection-uri:
37+
38+
Connection URI
39+
--------------
40+
41+
A standard connection string includes the following components:
42+
43+
.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made:
44+
.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`.
45+
46+
.. list-table::
47+
:widths: 20 80
48+
:header-rows: 1
49+
50+
* - Component
51+
- Description
52+
53+
* - ``mongodb://``
54+
55+
- Required. A prefix that identifies this as a string in the
56+
standard connection format.
57+
58+
* - ``username:password``
59+
60+
- Optional. Authentication credentials. If you include these, the client
61+
authenticates the user against the database specified in ``authSource``.
62+
63+
* - ``host[:port]``
64+
65+
- Required. The host and optional port number where MongoDB is running. If you don't
66+
include the port number, the driver uses the default port, ``27017``.
67+
68+
* - ``/defaultauthdb``
69+
70+
- Optional. The authentication database to use if the
71+
connection string includes ``username:password@``
72+
authentication credentials but not the ``authSource`` option. If you don't include
73+
this component, the client authenticates the user against the ``admin`` database.
74+
75+
* - ``?<options>``
76+
77+
- Optional. A query string that specifies connection-specific
78+
options as ``<name>=<value>`` pairs. See
79+
:ref:`kotlin-sync-connection-options` for a full description of
80+
these options.
81+
82+
For more information about creating a connection string, see
83+
:manual:`Connection Strings </reference/connection-string>` in the
84+
MongoDB Server documentation.
85+
86+
Atlas Connection Example
87+
------------------------
88+
89+
To connect to a MongoDB deployment on Atlas, you must first create a client.
90+
91+
You can pass a connection URI as a string to the ``MongoClient.create()`` method
92+
to connect to a MongoDB instance:
93+
94+
.. literalinclude:: /includes/connect/mongoclient2.kt
95+
:start-after: start-connect-to-atlas-w-uri
96+
:end-before: end-connect-to-atlas-w-uri
97+
:language: kotlin
98+
:copyable:
99+
:dedent:
100+
101+
You can also create a client with your desired configurations by passing a
102+
``MongoClientSettings`` object to the ``MongoClient.create()`` method.
103+
104+
To instantiate a ``MongoClientSettings`` object, use the builder method to
105+
specify your connection string, using the ``applyConnectionString()`` method,
106+
and any other client options. Once you have your desired configuration,
107+
call the ``build()`` method.
108+
109+
You can set the Stable API version client option to avoid breaking changes when
110+
you upgrade to a new server version. To learn more about the Stable API feature,
111+
see the :ref:`Stable API page <kotlin-sync-stable-api>`.
112+
113+
The following code shows how you can specify the connection string and the
114+
Stable API client option when connecting to a MongoDB deployment on Atlas
115+
and verify that the connection is successful:
116+
117+
.. literalinclude:: /includes/connect/mongoclient.kt
118+
:start-after: start-connect-to-atlas
119+
:end-before: end-connect-to-atlas
120+
:language: kotlin
121+
:copyable:
122+
:dedent:
123+
124+
API Documentation
125+
-----------------
126+
127+
For more information about creating a ``MongoClient`` object with the
128+
{+driver-short+}, see the following API documentation:
129+
130+
- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__
131+
- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__

0 commit comments

Comments
 (0)