Interface TimeoutDescriptor

Overview

The generic timeout descriptor that is used to define the timeout for all the various operations supported by the DataAPIClient and its children.

Inheritance

The TimeoutDescriptor, or a subset of it, may be specified at any level of the client hierarchy, all the way from the DataAPIClient down to the individual methods. The timeout specified at a lower level will override the timeout specified at a higher level (through a typical object merge).

Example

// The request timeout for all operations is set to 1000ms.
const client = new DataAPIClient('...', {
  timeoutDefaults: { requestTimeoutMs: 1000 },
});

// The request timeout for all operations borne from this Db is set to 2000ms.
const db = client.db('...', {
  timeoutDefaults: { requestTimeoutMs: 2000 },
});
The WithTimeout interface

The WithTimeout interface lets you specify timeouts for individual methods, in two different formats:

  • A subtype of TimeoutDescriptor, which lets you specify the timeout for specific categories.
  • A number, which specifies the "happy path" timeout for the method.
    • In single-call methods, this sets both the request & overall method timeouts.
    • In multi-call methods, this sets the overall method timeout (request timeouts are kept as default).

Example

// Both `requestTimeoutMs` and `generalMethodTimeoutMs` are set to 1000ms.
await coll.insertOne({ ... }, { timeout: 1000 });

// `requestTimeoutMs` is left as default, `generalMethodTimeoutMs` is set to 2000ms.
await coll.insertOne({ ... }, { timeout: { generalMethodTimeoutMs: 2000 } });

// Both `requestTimeoutMs` and `generalMethodTimeoutMs` are set to 2000ms.
await coll.insertMany([...], {
  timeout: { requestTimeoutMs: 2000, generalMethodTimeoutMs: 2000 },
});

Example

// `requestTimeoutMs` is left as default, `generalMethodTimeoutMs` is set to 2000ms.
await coll.insertMany([...], { timeout: 2000 });

// `requestTimeoutMs` is left as default, `generalMethodTimeoutMs` is set to 2000ms.
await coll.insertMany([...], { timeout: { generalMethodTimeoutMs: 2000 } });

// Both `requestTimeoutMs` and `generalMethodTimeoutMs` are set to 2000ms.
await coll.insertMany([...], {
  timeout: { requestTimeoutMs: 2000, generalMethodTimeoutMs: 2000 },
});

Timeout types

There are 6 generalized categories of timeouts, each with its own default values.

In general though, two types of timeouts are always in play:

  • requestTimeoutMs, which is the maximum time the client will wait for a response from the server.
  • The overall method timeout, which is the maximum time the client will wait for the entire method to complete.

Timeout behavior depends on the type of method being called:

  • In single-call methods, the minimum of these two values is used as the timeout.
  • In multi-call methods, the requestTimeoutMs is used as the timeout for each individual call, and the overall method timeout is used as the timeout for the entire method.

This two-part timeout system is used in all methods but, but for a special few, where the overall method timeout is the only one used (only createCollection, at the moment). This is because the method is a single call, but it takes a long time for the server to complete.

If any timeout is set to 0, that category is effectively disabled.

Timeout categories

See each individual field for more information, but in general, the timeouts are as follows:

  • requestTimeoutMs:
    • The maximum time the client will wait for a response from the server.
    • Default: 10 seconds
  • generalMethodTimeoutMs:
    • The overall method timeout for methods that don't have a specific overall method timeout.
    • (mostly applies to document/row-level operations)
    • Default: 30 seconds
  • collectionAdminTimeoutMs:
    • The overall method timeout for collection admin operations.
    • (create, drop, list, etc.)
    • Default: 1 minute
  • tableAdminTimeoutMs:
    • The overall method timeout for table admin operations.
    • (create, drop, list, alter, create/dropIndex, etc.)
    • Default: 30 seconds
  • databaseAdminTimeoutMs:
    • The overall method timeout for database admin operations.
    • (create, drop, list, info, findEmbeddingProviders, etc.)
    • Default: 10 minutes
  • keyspaceAdminTimeoutMs:
    • The overall method timeout for keyspace admin operations.
    • (create, drop, list)
    • Default: 30 seconds

See

WithTimeout

interface TimeoutDescriptor {
    collectionAdminTimeoutMs: number;
    databaseAdminTimeoutMs: number;
    generalMethodTimeoutMs: number;
    keyspaceAdminTimeoutMs: number;
    requestTimeoutMs: number;
    tableAdminTimeoutMs: number;
}

Properties

collectionAdminTimeoutMs databaseAdminTimeoutMs generalMethodTimeoutMs keyspaceAdminTimeoutMs requestTimeoutMs tableAdminTimeoutMs

Properties

collectionAdminTimeoutMs

collectionAdminTimeoutMs: number

The overall method timeout for collection admin operations.

Such methods include (but may not be limited to):

  • db.createCollection()
  • db.dropCollection()
  • db.listCollections()
  • collection.options()

Default: 1 minute

databaseAdminTimeoutMs

databaseAdminTimeoutMs: number

The overall method timeout for database admin operations.

Such methods include (but may not be limited to):

  • admin.createDatabase()
  • admin.dropDatabase()
  • admin.listDatabases()
  • dbAdmin.info()
  • dbAdmin.findEmbeddingProviders()

Default: 10 minutes

generalMethodTimeoutMs

generalMethodTimeoutMs: number

The overall method timeout for methods that don't have a specific overall method timeout.

Mostly applies to document/row-level operations. DDL-esque operations (working with collections, tables, databases, keyspaces, indexes, etc.) have their own overall method timeouts.

In single-call methods, such as insertOne, the minimum of requestTimeoutMs and generalMethodTimeoutMs is used as the timeout.

In multi-call methods, such as insertMany, the requestTimeoutMs is used as the timeout for each individual call, and the generalMethodTimeoutMs is used as the timeout for the entire method.

Default: 30 seconds

keyspaceAdminTimeoutMs

keyspaceAdminTimeoutMs: number

The overall method timeout for keyspace admin operations.

Such methods include (but may not be limited to):

  • admin.createKeyspace()
  • admin.dropKeyspace()
  • admin.listKeyspaces()

Default: 30 seconds

requestTimeoutMs

requestTimeoutMs: number

The maximum time the client will wait for a response from the server.

Note that it is technically possible for a request to time out, but still have the request be processed, and even succeed, on the server.

Every HTTP call will use a requestTimeout, except for very special cases (at the moment, only createCollection, where the request may take a long time to return).

Default: 10 seconds

tableAdminTimeoutMs

tableAdminTimeoutMs: number

The overall method timeout for table admin operations.

Such methods include (but may not be limited to):

  • db.createTable()
  • db.dropTable()
  • db.listTables()
  • table.alter()
  • table.createIndex()
  • db.dropTableIndex()
  • table.definition()

Default: 30 seconds

Settings

Member Visibility

Theme

On This Page

collectionAdminTimeoutMsdatabaseAdminTimeoutMsgeneralMethodTimeoutMskeyspaceAdminTimeoutMsrequestTimeoutMstableAdminTimeoutMs