client_session – Logical sessions for sequential operations

Logical sessions for ordering sequential operations.

Added in version 3.6.

Causally Consistent Reads

with client.start_session(causal_consistency=True) as session:
    collection = client.db.collection
    await collection.update_one({"_id": 1}, {"$set": {"x": 10}}, session=session)
    secondary_c = collection.with_options(read_preference=ReadPreference.SECONDARY)

    # A secondary read waits for replication of the write.
    await secondary_c.find_one({"_id": 1}, session=session)

If causal_consistency is True (the default), read operations that use the session are causally after previous read and write operations. Using a causally consistent session, an application can read its own writes and is guaranteed monotonic reads, even when reading from replica set secondaries.

See also

The MongoDB documentation on causal-consistency.


Added in version 3.7.

MongoDB 4.0 adds support for transactions on replica set primaries. A transaction is associated with a ClientSession. To start a transaction on a session, use ClientSession.start_transaction() in a with-statement. Then, execute an operation within the transaction by passing the session to the operation:

orders = client.db.orders
inventory = client.db.inventory
with client.start_session() as session:
    async with session.start_transaction():
        await orders.insert_one({"sku": "abc123", "qty": 100}, session=session)
        await inventory.update_one(
            {"sku": "abc123", "qty": {"$gte": 100}},
            {"$inc": {"qty": -100}},

Upon normal completion of async with session.start_transaction() block, the transaction automatically calls ClientSession.commit_transaction(). If the block exits with an exception, the transaction automatically calls ClientSession.abort_transaction().

In general, multi-document transactions only support read/write (CRUD) operations on existing collections. However, MongoDB 4.4 adds support for creating collections and indexes with some limitations, including an insert operation that would result in the creation of a new collection. For a complete description of all the supported and unsupported operations see the MongoDB server’s documentation for transactions.

A session may only have a single active transaction at a time, multiple transactions on the same session can be executed in sequence.

Sharded Transactions

Added in version 3.9.

PyMongo 3.9 adds support for transactions on sharded clusters running MongoDB >=4.2. Sharded transactions have the same API as replica set transactions. When running a transaction against a sharded cluster, the session is pinned to the mongos server selected for the first operation in the transaction. All subsequent operations that are part of the same transaction are routed to the same mongos server. When the transaction is completed, by running either commitTransaction or abortTransaction, the session is unpinned.

See also

The MongoDB documentation on transactions.

Snapshot Reads

Added in version 3.12.

MongoDB 5.0 adds support for snapshot reads. Snapshot reads are requested by passing the snapshot option to start_session(). If snapshot is True, all read operations that use this session read data from the same snapshot timestamp. The server chooses the latest majority-committed snapshot timestamp when executing the first read operation using the session. Subsequent reads on this session read from the same snapshot timestamp. Snapshot reads are also supported when reading from replica set secondaries.

# Each read using this session reads data from the same point in time.
with client.start_session(snapshot=True) as session:
    order = await orders.find_one({"sku": "abc123"}, session=session)
    inventory = await inventory.find_one({"sku": "abc123"}, session=session)

Snapshot Reads Limitations

Snapshot reads sessions are incompatible with causal_consistency=True. Only the following read operations are supported in a snapshot reads session: