Limit Server Execution Time

Accepted Timeout Values

The following table describes the timeout behavior corresponding to the accepted values for timeoutMS:

If you specify the timeoutMS option, the driver automatically applies the specified timeout to each server operation. The following code example specifies a timeout of 200 milliseconds at the client level, and then calls the MongoCollection.insertOne() method:

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()
val client = MongoClient.create(settings)
val collection = client
    .getDatabase("db")
    .getCollection<Document>("people")
collection.insertOne(Document("name", "Francine Loews"))

Timeout Inheritance

When you specify the timeoutMS option, the driver applies the timeout according to the same inheritance behaviors as the other Kotlin driver options. The following table describes how the timeout value is inherited at each level:

For more information on overrides and specific options, see the following Overrides section.

Transactions

When you create a new ClientSession instance to implement a transaction, use the defaultTimeout() method when building a ClientSessionOptions instance. You can use this option to specify the timeout for the following methods:

• commitTransaction()

• abortTransaction()

• withTransaction()

• close()

The following code demonstrates how to set the defaultTimeout when instantiating a ClientSession:

val opts = ClientSessionOptions.builder()
    .defaultTimeout(200L, TimeUnit.MILLISECONDS)
    .build()
val session = client.startSession(opts)
// ... perform operations on ClientSession

If you do not specify the defaultTimeout, the driver uses the timeout value set on the parent MongoClient.

You can also set a transaction-level timeout by calling the timeout() method when building a TransactionOptions instance. Setting this option applies a timeout to all operations performed in the scope of the transaction:

val transactionOptions = TransactionOptions.builder()
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()

To learn more about transactions, see the Transactions guide.

Client Encryption

When you use Client-Side Field Level Encryption (CSFLE), the driver uses the timeoutMS option to limit the time allowed for encryption and decryption operations. You can set a timeout option for your ClientEncryption instance by calling the timeout() method when building a ClientEncryptionSettings instance.

If you specify the timeout when you construct a ClientEncryption instance, the timeout controls the lifetime of all operations performed on that instance. If you do not provide a timeout when instantiating ClientEncryption, the instance inherits the timeout setting from the MongoClient used in the ClientEncryption constructor.

If you set timeoutMS both on the client and directly in ClientEncryption, the value provided to ClientEncryption takes precedence.

Cursor Lifetime Mode

The cursor lifetime mode uses the timeout setting to limit the entire lifetime of a cursor. In this mode, your application must initialize the cursor, complete all calls to the cursor methods, and return all documents within the specified time limit. Otherwise, the cursor's lifetime expires and the driver raises a timeout error.

When you close a cursor by calling the close() method, the timeout resets for the killCursors command to ensure server-side resources are cleaned up.

The following example shows how to set a cursor timeout to ensure that the cursor is initialized and all documents are retrieved within the inherited timeout:

val flowWithLifetimeTimeout = collection
    .find(Filters.gte("age", 40))
    .timeoutMode(TimeoutMode.CURSOR_LIFETIME)