Client options

Global
This type is global
Properties:
Name Type Description
contactPoints Array<string>

Array of addresses or host names of the nodes to add as contact points.

Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology.

Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, because if that single contact point is unavailable, the driver will not be able to initialize correctly.

localDataCenter String

The local data center to use.

If using DCAwareRoundRobinPolicy (default), this option is required and only hosts from this data center are connected to and used in query plans.

keyspace String

The logged keyspace for all the connections created within the Client instance.

credentials Object

An object containing the username and password for plain-text authentication. It configures the authentication provider to be used against Apache Cassandra’s PasswordAuthenticator or DSE’s DseAuthenticator, when default auth scheme is plain-text.

Note that you should configure either credentials or authProvider to connect to an auth-enabled cluster, but not both.

credentials.username String

The username to use for plain-text authentication.

credentials.password String

The password to use for plain-text authentication.

refreshSchemaDelay Number

The default window size in milliseconds used to debounce node list and schema refresh metadata requests. Default: 1000.

isMetadataSyncEnabled Boolean

Determines whether client-side schema metadata retrieval and update is enabled.

Setting this value to false will cause keyspace information not to be automatically loaded, affecting replica calculation per token in the different keyspaces. When disabling metadata synchronization, use Metadata.refreshKeyspaces() to keep keyspace information up to date or token-awareness will not work correctly.

Default: true.
prepareOnAllHosts Boolean

Determines if the driver should prepare queries on all hosts in the cluster. Default: true.

rePrepareOnUp Boolean

Determines if the driver should re-prepare all cached prepared queries on a host when it marks it back up. Default: true.

maxPrepared Number

Determines the maximum amount of different prepared queries before evicting items from the internal cache. Reaching a high threshold hints that the queries are not being reused, like when hard-coding parameter values inside the queries. Default: 500.

policies Object
policies.loadBalancing LoadBalancingPolicy

The load balancing policy instance to be used to determine the coordinator per query.

policies.retry RetryPolicy

The retry policy.

policies.reconnection ReconnectionPolicy

The reconnection policy to be used.

policies.addressResolution AddressTranslator

The address resolution policy.

policies.speculativeExecution SpeculativeExecutionPolicy

The SpeculativeExecutionPolicy instance to be used to determine if the client should send speculative queries when the selected host takes more time than expected.

Default: NoSpeculativeExecutionPolicy

policies.timestampGeneration TimestampGenerator

The client-side query timestamp generator.

Default: MonotonicTimestampGenerator

Use null to disable client-side timestamp generation.

queryOptions QueryOptions

Default options for all queries.

pooling Object

Pooling options.

pooling.heartBeatInterval Number

The amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. Default: 30000.

pooling.coreConnectionsPerHost Object

Associative array containing amount of connections per host distance.

pooling.maxRequestsPerConnection Number

The maximum number of requests per connection. The default value is:

  • For modern protocol versions (v3 and above): 2048
  • For older protocol versions (v1 and v2): 128
pooling.warmup Boolean

Determines if all connections to hosts in the local datacenter must be opened on connect. Default: true.

protocolOptions Object
protocolOptions.port Number

The port to use to connect to the Cassandra host. If not set through this method, the default port (9042) will be used instead.

protocolOptions.maxSchemaAgreementWaitSeconds Number

The maximum time in seconds to wait for schema agreement between nodes before returning from a DDL query. Default: 10.

protocolOptions.maxVersion Number

When set, it limits the maximum protocol version used to connect to the nodes. Useful for using the driver against a cluster that contains nodes with different major/minor versions of Cassandra.

protocolOptions.noCompact Boolean

When set to true, enables the NO_COMPACT startup option.

When this option is supplied SELECT, UPDATE, DELETE, and BATCH statements on COMPACT STORAGE tables function in “compatibility” mode which allows seeing these tables as if they were “regular” CQL tables.

This option only effects interactions with interactions with tables using COMPACT STORAGE and is only supported by C* 3.0.16+, 3.11.2+, 4.0+ and DSE 6.0+.

socketOptions Object
socketOptions.connectTimeout Number

Connection timeout in milliseconds. Default: 5000.

socketOptions.defunctReadTimeoutThreshold Number

Determines the amount of requests that simultaneously have to timeout before closing the connection. Default: 64.

socketOptions.keepAlive Boolean

Whether to enable TCP keep-alive on the socket. Default: true.

socketOptions.keepAliveDelay Number

TCP keep-alive delay in milliseconds. Default: 0.

socketOptions.readTimeout Number

Per-host read timeout in milliseconds.

Please note that this is not the maximum time a call to execute may have to wait; this is the maximum time that call will wait for one particular Cassandra host, but other hosts will be tried if one of them timeout. In other words, a execute call may theoretically wait up to readTimeout * number_of_cassandra_hosts (though the total number of hosts tried for a given query also depends on the LoadBalancingPolicy in use).

When setting this value, keep in mind the following:

  • the timeout settings used on the Cassandra side (*_request_timeout_in_ms in cassandra.yaml) should be taken into account when picking a value for this read timeout. You should pick a value a couple of seconds greater than the Cassandra timeout settings.
  • the read timeout is only approximate and only control the timeout to one Cassandra host, not the full query.
Setting a value of 0 disables read timeouts. Default: 12000.
socketOptions.tcpNoDelay Boolean

When set to true, it disables the Nagle algorithm. Default: true.

socketOptions.coalescingThreshold Number

Buffer length in bytes use by the write queue before flushing the frames. Default: 8000.

authProvider AuthProvider

Provider to be used to authenticate to an auth-enabled cluster.

requestTracker RequestTracker

The instance of RequestTracker used to monitor or log requests executed with this instance.

sslOptions Object

Client-to-node ssl options. When set the driver will use the secure layer. You can specify cert, ca, … options named after the Node.js tls.connect() options.

It uses the same default values as Node.js tls.connect() except for rejectUnauthorized which is set to false by default (for historical reasons). This setting is likely to change in upcoming versions to enable validation by default.

encoding Object
encoding.map function

Map constructor to use for Cassandra map type encoding and decoding. If not set, it will default to Javascript Object with map keys as property names.

encoding.set function

Set constructor to use for Cassandra set type encoding and decoding. If not set, it will default to Javascript Array.

encoding.copyBuffer Boolean

Determines if the network buffer should be copied for buffer based data types (blob, uuid, timeuuid and inet).

Setting it to true will cause that the network buffer is copied for each row value of those types, causing additional allocations but freeing the network buffer to be reused. Setting it to true is a good choice for cases where the Row and ResultSet returned by the queries are long-lived objects.

Setting it to false will cause less overhead and the reference of the network buffer to be maintained until the row / result set are de-referenced. Default: true.

encoding.useUndefinedAsUnset Boolean

Valid for Cassandra 2.2 and above. Determines that, if a parameter is set to undefined it should be encoded as unset.

By default, ECMAScript undefined is encoded as null in the driver. Cassandra 2.2 introduced the concept of unset. At driver level, you can set a parameter to unset using the field types.unset. Setting this flag to true allows you to use ECMAScript undefined as Cassandra unset.

Default: true.

encoding.useBigIntAsLong Boolean

Use BigInt ECMAScript type to represent CQL bigint and counter data types.

encoding.useBigIntAsVarint Boolean

Use BigInt ECMAScript type to represent CQL varint data type.

profiles Array<ExecutionProfile>

The array of execution profiles.

promiseFactory function

Function to be used to create a Promise from a callback-style function.

Promise libraries often provide different methods to create a promise. For example, you can use Bluebird’s Promise.fromCallback() method.

By default, the driver will use the Promise constructor.