Configure CRUD Operations

Overview

In this guide, you can learn how to configure read and write operations in PyMongo.

Read and Write Settings

You can control how the driver routes read operations by setting a read preference. You can also control options for how the driver waits for acknowledgment of read and write operations on a replica set by setting a read concern and a write concern.

By default, databases inherit these settings from the MongoClient instance, and collections inherit them from the database. However, you can change these settings on your database or collection by using one of the following methods:

• get_database(): Gets the database and applies the client's read preference, read concern, and write preference.

• database.with_options(): Gets the database and applies its current read preference, read concern, and write preference.

• get_collection(): Gets the collection and applies its current read preference, read concern, and write preference.

• collection.with_options(): Gets the collection and applies the database's read preference, read concern, and write preference.

To change read or write settings with the preceding methods, call the method and pass in the collection or database name, and the new read preference, read concern, or write preference.

The following example shows how to change the read preference, read concern and write preference of a database called test-database with the get_database() method:

client.get_database("test-database",
                    read_preference=ReadPreference.SECONDARY,
                    read_concern="local",
                    write_concern="majority")

The following example shows how to change read and write settings of a collection called test-collection with the get_collection() method:

database.get_collection("test-collection",
                    read_preference=ReadPreference.SECONDARY,
                    read_concern="local",
                    write_concern="majority")

The following example shows how to change read and write settings of a collection called test-collection with the with_options() method:

collection.with_options(read_preference=ReadPreference.SECONDARY,
                        read_concern="local",
                        write_concern="majority")

To learn more about the read and write settings, see the following guides in the MongoDB Server manual:

• Read Preference

• Read Concern

• Write Concern

Tag Sets

In MongoDB Server, you can apply key-value tags to replica-set members according to any criteria you choose. You can then use those tags to target one or more members for a read operation.

By default, PyMongo ignores tags when choosing a member to read from. To instruct PyMongo to prefer certain tags, pass them as a parameter to your read preference class constructor.

In the following code example, the tag set passed to the read_preference parameter instructs PyMongo to prefer reads from the New York data center ('dc': 'ny') and to fall back to the San Francisco data center ('dc': 'sf'):

db = client.get_database(
     'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}]))

Local Threshold

If multiple replica-set members match the read preference and tag sets you specify, PyMongo reads from the nearest replica-set members, chosen according to their ping time.

By default, the driver uses only those members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads between members with higher latencies, pass the localThresholdMS option to the MongoClient() constructor.

The following example specifies a local threshold of 35 milliseconds:

client = MongoClient(replicaSet='repl0',
                     readPreference=ReadPreference.SECONDARY_PREFERRED,
                     localThresholdMS=35)

In the preceding example, PyMongo distributes reads between matching members within 35 milliseconds of the closest member's ping time.

Retryable Reads and Writes

PyMongo automatically retries certain read and write operations a single time if they fail due to a network or server error.

You can explicitly disable retryable reads or retryable writes by setting the retryReads or retryWrites option to False in the MongoClient() constructor. The following example disables retryable reads and writes for a client:

client = MongoClient("<connection string>",
                     retryReads=False, retryWrites=False)

To learn more about supported retryable read operations, see Retryable Reads in the MongoDB Server manual. To learn more about supported retryable write operations, see Retryable Writes in the MongoDB Server manual.

Collation

When you create a collection, you can specify a default collation for all operations you perform on the collection.

A collation is a set of language-specific rules for string comparison, such as for letter case and accent marks.

To specify a collation, create an instance of the Collation class or a Python dictionary. For a list of options to pass to the Collation constructor or include as keys in the dictionary, see Collation in the MongoDB Server manual.

The following example creates the same collection as the previous example, but with a default collation of fr_CA:

from pymongo.collation import Collation
database = client["test_database"]
database.create_collection("example_collection", collation=Collation(locale='fr_CA'))