Server Selector Example

Users can exert fine-grained control over the server selection algorithmby setting the server_selector option on the MongoClientto an appropriate callable. This example shows how to use this functionalityto prefer servers running on localhost.

Warning

Use of custom server selector functions is a power user feature. Misusingcustom server selectors can have unintended consequences such as degradedread/write performance.

Example: Selecting Servers Running on localhost

To start, we need to write the server selector function that will be used.The server selector function should accept a list ofServerDescription objects and return alist of server descriptions that are suitable for the read or write operation.A server selector must not create or modifyServerDescription objects, and must returnthe selected instances unchanged.

In this example, we write a server selector that prioritizes servers running onlocalhost. This can be desirable when using a sharded cluster with multiplemongos, as locally run queries are likely to see lower latency and higherthroughput. Please note, however, that it is highly dependent on theapplication if preferring localhost is beneficial or not.

In addition to comparing the hostname with localhost, our server selectorfunction accounts for the edge case when no servers are running onlocalhost. In this case, we allow the default server selection logic toprevail by passing through the received server description list unchanged.Failure to do this would render the client unable to communicate with MongoDBin the event that no servers were running on localhost.

The described server selection logic is implemented in the following serverselector function:

>>> def server_selector(server_descriptions):
...     servers = [
...         server for server in server_descriptions
...         if server.address[0] == 'localhost'
...     ]
...     if not servers:
...         return server_descriptions
...     return servers

Finally, we can create a MongoClient instance with thisserver selector.

>>> client = MongoClient(server_selector=server_selector)

Server Selection Process

This section dives deeper into the server selection process for reads andwrites. In the case of a write, the driver performs the following operations(in order) during the selection process:

• Select all writeable servers from the list of known hosts. For a replica setthis is the primary, while for a sharded cluster this is all the known mongoses.
• Apply the user-defined server selector function. Note that the custom serverselector is not called if there are no servers left from the previousfiltering stage.
• Apply the localThresholdMS setting to the list of remaining hosts. Thiswhittles the host list down to only contain servers whose latency is at mostlocalThresholdMS milliseconds higher than the lowest observed latency.
• Select a server at random from the remaining host list. The desiredoperation is then performed against the selected server.In the case of reads the process is identical except for the first step.Here, instead of selecting all writeable servers, we select all serversmatching the user’s ReadPreference from thelist of known hosts. As an example, for a 3-member replica set with aSecondary read preference, we would selectall available secondaries.