Client Side Operation Timeout - PyMongo 4.13.2 documentation (original) (raw)
Toggle table of contents sidebar
PyMongo 4.2 introduced timeout() and the timeoutMSURI and keyword argument to MongoClient. These features allow applications to more easily limit the amount of time that one or more operations can execute before control is returned to the app. This timeout applies to all of the work done to execute the operation, including but not limited to server selection, connection checkout, serialization, and server-side execution.
Basic Usage¶
The following example uses timeout() to configure a 10-second timeout for an insert_one() operation:
import pymongo with pymongo.timeout(10): coll.insert_one({"name": "Nunu"})
The timeout() applies to all pymongo operations within the block. The following example ensures that both the insert and the find complete within 10 seconds total, or raise a timeout error:
with pymongo.timeout(10): coll.insert_one({"name": "Nunu"}) coll.find_one({"name": "Nunu"})
When nesting timeout(), the nested deadline is capped by the outer deadline. The deadline can only be shortened, not extended. When exiting the block, the previous deadline is restored:
with pymongo.timeout(5): coll.find_one() # Uses the 5 second deadline. with pymongo.timeout(3): coll.find_one() # Uses the 3 second deadline. coll.find_one() # Uses the original 5 second deadline. with pymongo.timeout(10): coll.find_one() # Still uses the original 5 second deadline. coll.find_one() # Uses the original 5 second deadline.
Timeout errors¶
When the timeout() with-statement is entered, a deadline is set for the entire block. When that deadline is exceeded, any blocking pymongo operation will raise a timeout exception. For example:
try: with pymongo.timeout(10): coll.insert_one({"name": "Nunu"}) time.sleep(10) # The deadline has now expired, the next operation will raise # a timeout exception. coll.find_one({"name": "Nunu"}) except PyMongoError as exc: if exc.timeout: print(f"block timed out: {exc!r}") else: print(f"failed with non-timeout error: {exc!r}")
The pymongo.errors.PyMongoError.timeout property (added in PyMongo 4.2) will be True when the error was caused by a timeout and False otherwise.
The timeoutMS URI option¶
PyMongo 4.2 also added support for the timeoutMS URI and keyword argument toMongoClient. When this option is configured, the client will automatically apply the timeout to each API call. For example:
client = MongoClient("mongodb://localhost/?timeoutMS=10000") coll = client.test.test coll.insert_one({"name": "Nunu"}) # Uses a 10-second timeout. coll.find_one({"name": "Nunu"}) # Also uses a 10-second timeout.
The above is roughly equivalent to:
client = MongoClient() coll = client.test.test with pymongo.timeout(10): coll.insert_one({"name": "Nunu"}) with pymongo.timeout(10): coll.find_one({"name": "Nunu"})
pymongo.timeout overrides timeoutMS¶
timeout() overrides timeoutMS; within atimeout() block a client’s timeoutMS option is ignored:
client = MongoClient("mongodb://localhost/?timeoutMS=10000") coll = client.test.test coll.insert_one({"name": "Nunu"}) # Uses the client's 10-second timeout.
pymongo.timeout overrides the client's timeoutMS.
with pymongo.timeout(20): coll.insert_one({"name": "Nunu"}) # Uses the 20-second timeout. with pymongo.timeout(5): coll.find_one({"name": "Nunu"}) # Uses the 5-second timeout.
pymongo.timeout is thread safe¶
timeout() is thread safe; the timeout only applies to current thread and multiple threads can configure different timeouts in parallel.
pymongo.timeout is asyncio safe¶
timeout() is asyncio safe; the timeout only applies to current Task and multiple Tasks can configure different timeouts concurrently.timeout() can be used identically inMotor, for example:
import motor.motor_asyncio client = motor.motor_asyncio.AsyncIOMotorClient() coll = client.test.test with pymongo.timeout(10): await coll.insert_one({"name": "Nunu"}) await coll.find_one({"name": "Nunu"})
Troubleshooting¶
There are many timeout errors that can be raised depending on when the timeout expires. In code, these can be identified with the pymongo.errors.PyMongoError.timeoutproperty. Some specific timeout errors examples are described below.
When the client was unable to find an available server to run the operation within the given timeout:
pymongo.errors.ServerSelectionTimeoutError: No servers found yet, Timeout: -0.00202266700216569s, Topology Description: <TopologyDescription id: 63698e87cebfd22ab1bd2ae0, topology_type: Unknown, servers: [<ServerDescription ('localhost', 27017) server_type: Unknown, rtt: None>]>
When either the client was unable to establish a connection within the given timeout or the operation was sent but the server was not able to respond in time:
pymongo.errors.NetworkTimeout: localhost:27017: timed out
When the server cancelled the operation because it exceeded the given timeout. Note that the operation may have partially completed on the server (depending on the operation):
pymongo.errors.ExecutionTimeout: operation exceeded time limit, full error: {'ok': 0.0, 'errmsg': 'operation exceeded time limit', 'code': 50, 'codeName': 'MaxTimeMSExpired'}
When the client cancelled the operation because it was not possible to complete within the given timeout:
pymongo.errors.ExecutionTimeout: operation would exceed time limit, remaining timeout:0.00196 <= network round trip time:0.00427
When the client attempted a write operation but the server could not replicate that write (according to the configured write concern) within the given timeout:
pymongo.errors.WTimeoutError: operation exceeded time limit, full error: {'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}
The same error as above but for insert_many()or bulk_write():
pymongo.errors.BulkWriteError: batch op errors occurred, full error: {'writeErrors': [], 'writeConcernErrors': [{'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 0, 'nModified': 0, 'nRemoved': 0, 'upserted': []}