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:

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("<connection string>"))
        .timeout(200L, MILLISECONDS)
        .build();
try (MongoClient mongoClient = MongoClients.create(settings)) {
    MongoDatabase database = mongoClient.getDatabase("db");
    MongoCollection<Document> collection = database.getCollection("people");
    collection.insertOne(new 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 Java 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:

ClientSessionOptions opts = ClientSessionOptions.builder()
        .defaultTimeout(200L, MILLISECONDS)
        .build();
ClientSession session = mongoClient.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:

TransactionOptions transactionOptions = TransactionOptions.builder()
        .timeout(200L, 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:

FindIterable<Document> cursorWithLifetimeTimeout = collection
        .find(gte("age", 40))
        .timeoutMode(TimeoutMode.CURSOR_LIFETIME);

Cursor Iteration Mode

The cursor iteration mode sets the timeout to limit each call to the next(), hasNext(), and tryNext() methods. The timeout refreshes after each call completes. This is the default mode for all tailable cursors, such as the tailable cursors returned by the find() method on capped collections or change streams.

The following code example iterates over documents in the db.people collection by using a cursor with the ITERATION timeout mode, and then retrieves and prints the name field value for each document:

try (MongoCursor<Document> cursorWithIterationTimeout = collection
        .find(gte("age", 40))
        .timeoutMode(TimeoutMode.ITERATION)
        .cursor()
) {
    while (cursorWithIterationTimeout.hasNext()) {
        System.out.println(cursorWithIterationTimeout.next().toJson());
    }
}