Skip to content

Commit 33fb65a

Browse files
mcmorisimcmorisi
authored
DOCSP-51347: Server Selection (#118)
1 parent f337e8f commit 33fb65a

File tree

3 files changed

+177
-0
lines changed

3 files changed

+177
-0
lines changed

‎source/connect/connection-options.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Specify Connection Options
1616
:maxdepth: 1
1717

1818
Network Compression </connect/connection-options/network-compression>
19+
Server Selection </connect/connection-options/server-selection>
1920
Stable API </connect/connection-options/stable-api>
2021
Limit Server Execution Time </connect/connection-options/csot>
2122
Connection Pools </connect/connection-pools>

‎source/connect/connection-options/server-selection.txt

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
.. _kotlin-sync-server-selection:
2+
3+
==========================
4+
Customize Server Selection
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: read preference, write, server selection
19+
20+
Overview
21+
--------
22+
23+
All MongoDB drivers follow a defined algorithm when selecting a server to read or write
24+
from. By using the ``ClusterSettings`` property of a ``MongoClientSettings`` object, you can
25+
customize this algorithm to choose the server that works best for your application.
26+
27+
.. important::
28+
29+
Customizing the server selection algorithm might have unintended consequences,
30+
such as degraded read or write performance.
31+
32+
Server Selection Algorithm
33+
--------------------------
34+
35+
When the {+driver-short+} executes a read operation, it performs the following steps,
36+
in order, to select a MongoDB deployment:
37+
38+
1. Selects all servers from the list of known servers suitable for the requested
39+
operation, barring those that the driver considers unavailable or problematic
40+
41+
1. For reads, selects all servers that match the active read preference
42+
43+
#. For writes, selects all writeable servers
44+
45+
#. Calls the user-defined server-selector function, if the user provides one, and passes in
46+
the list from the previous step
47+
48+
#. Applies the ``localThreshold`` connection setting to the list of
49+
servers returned from the function
50+
51+
#. Selects at most two random servers from the list of servers that match the
52+
preceding criteria, then selects the server with fewer outstanding concurrent operations
53+
54+
When the {+driver-short+} executes a write operation, it begins by selecting all writeable
55+
servers from the list of known servers, not just those that match the active read preference.
56+
The remaining steps are identical to the preceding list.
57+
58+
To learn more about the MongoDB server selection algorithm, see
59+
:manual:`Server Selection Algorithm </core/read-preference-mechanics/>` in the
60+
{+mdb-server+} manual.
61+
62+
Implement Custom Server Selection Logic
63+
---------------------------------------
64+
65+
You can implement your own custom server selection logic by creating a class that
66+
implements the ``ServerSelector`` interface. The following
67+
example shows a simple custom server selection class that selects servers with a ``type``
68+
value of ``ServerType.REPLICA_SET_SECONDARY``:
69+
70+
.. literalinclude:: /includes/connect/ServerSelection.kt
71+
:language: kotlin
72+
:copyable: true
73+
:start-after: // start-custom-selector
74+
:end-before: // end-custom-selector
75+
76+
Use the ``applyToClusterSettings()`` method to pass an instance of this class to your
77+
``MongoClientSettings``. The following example shows how to create
78+
a ``MongoClient`` with an instance of the custom server selector class from the preceding example:
79+
80+
.. literalinclude:: /includes/connect/ServerSelection.kt
81+
:language: kotlin
82+
:copyable: true
83+
:start-after: // start-selector
84+
:end-before: // end-selector
85+
:dedent:
86+
87+
Use Settings to Configure Server Selection
88+
------------------------------------------
89+
90+
You can specify the following server selection settings in your ``MongoClient`` object or
91+
in your connection URI:
92+
93+
.. list-table::
94+
:widths: 30 70
95+
:header-rows: 1
96+
97+
* - Setting
98+
- Description
99+
100+
* - ``localThreshold``
101+
- | The latency window for server eligibility. If a server's round trip takes longer
102+
| than the fastest server's round-trip time plus this value, the server isn't
103+
| eligible for selection. You can specify this setting to a ``ClusterSettings`` object
104+
in addition to the connection URI.
105+
|
106+
| **Data Type**: ``Integer``
107+
| **Default**: 15 milliseconds
108+
| **Connection URI Example**: ``localThresholdMS=0``
109+
110+
* - ``readPreference``
111+
- | The client's default read-preference settings. For more information on read preference
112+
options, see :manual:`Read Preference </core/read-preference/>` in the {+mdb-server+} manual.
113+
You can specify this setting to a ``MongoClientSettings`` object in addition to the
114+
connection URI.
115+
|
116+
| **Data Type**: `ReadPreference <{+core-api+}/ReadPreference.html>`__
117+
| **Default**: ``ReadPreference.primary()``
118+
| **Connection URI Example**:
119+
120+
.. code-block:: none
121+
:copyable: false
122+
123+
readPreference=primaryPreferred
124+
&maxStalenessSeconds=90
125+
&readPreferenceTags=dc:ny,rack:1
126+
127+
* - ``serverSelectionTimeout``
128+
- | The length of time the driver tries to select a server before timing out.
129+
You can specify this setting to a ``ClusterSettings`` object in addition to the
130+
connection URI.
131+
|
132+
| **Data Type**: ``Long``
133+
| **Default**: 30 seconds
134+
| **Connection URI Example**: ``serverSelectionTimeoutMS=15000``
135+
136+
API Documentation
137+
-----------------
138+
139+
To learn more about the classes and methods used in this guide, see the following API
140+
documentation:
141+
142+
- `MongoClient <{+driver-api+}/-mongo-client/index.html>`__
143+
- `MongoClientSettings <{+core-api+}/MongoClientSettings.html>`__
144+
- `ServerSelector <{+core-api+}/selector/ServerSelector.html>`__
145+
- `ReadPreference <{+core-api+}/ReadPreference.html>`__

‎source/includes/connect/ServerSelection.kt

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package org.example
2+
import com.mongodb.ConnectionString
3+
import com.mongodb.MongoClientSettings
4+
import com.mongodb.connection.ClusterDescription
5+
import com.mongodb.connection.ServerDescription
6+
import com.mongodb.connection.ServerType
7+
import com.mongodb.kotlin.client.MongoClient
8+
import com.mongodb.selector.ServerSelector
9+
10+
// start-custom-selector
11+
class CustomServerSelector : ServerSelector {
12+
override fun select(cluster: ClusterDescription): List<ServerDescription> {
13+
return cluster.serverDescriptions.filter { it.type == ServerType.REPLICA_SET_SECONDARY }
14+
}
15+
}
16+
// end-custom-selector
17+
18+
fun main() {
19+
// start-selector
20+
val settings = MongoClientSettings.builder()
21+
.applyConnectionString(ConnectionString("<connection URI>"))
22+
.applyToClusterSettings { builder ->
23+
builder.serverSelector(CustomServerSelector())
24+
}
25+
.build()
26+
27+
val mongoClient = MongoClient.create(settings)
28+
// end-selector
29+
}
30+
31+

0 commit comments

Comments
 (0)