Global

Type Definitions

ClientOptions

Client options
Type:
  • Object
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.

keyspace String The logged keyspace for all the connections created within the Client instance.
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.
policies Object
Properties
Name Type Description
loadBalancing LoadBalancingPolicy The load balancing policy instance to be used to determine the coordinator per query.
retry RetryPolicy The retry policy.
reconnection ReconnectionPolicy The reconnection policy to be used.
addressResolution AddressTranslator The address resolution policy.
queryOptions QueryOptions Default options for all queries.
pooling Object Pooling options.
Properties
Name Type Description
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.
coreConnectionsPerHost Object Associative array containing amount of connections per host distance.
warmup Boolean Determines if all connections to hosts in the local datacenter must be opened on connect. Default: false.
protocolOptions Object
Properties
Name Type Description
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.
maxSchemaAgreementWaitSeconds Number The maximum time in seconds to wait for schema agreement between nodes before returning from a DDL query. Default: 10.
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.
socketOptions Object
Properties
Name Type Description
connectTimeout Number Connection timeout in milliseconds. Default: 5000.
defunctReadTimeoutThreshold Number Determines the amount of requests that simultaneously have to timeout before closing the connection. Default: 64.
keepAlive Boolean Whether to enable TCP keep-alive on the socket. Default: true.
keepAliveDelay Number TCP keep-alive delay in milliseconds. Default: 0.
readTimeout Number Per-host read timeout in milliseconds.

Please note that this is not the maximum time a call to Client#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 Client#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: 0.
tcpNoDelay Boolean When set to true, it disables the Nagle algorithm. Default: true.
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.
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.
encoding Object
Properties
Name Type Description
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.
set function Set constructor to use for Cassandra set type encoding and decoding. If not set, it will default to Javascript Array.
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.

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.

profiles Array.<ExecutionProfile> The array of execution profiles.

QueryOptions

Query options
Type:
  • Object
Properties:
Name Type Attributes Description
autoPage Boolean <optional>
 Determines if the driver must retrieve the following result pages automatically.
captureStackTrace Boolean <optional>
 Determines if the stack trace before the query execution should be maintained.

Useful for debugging purposes, it should be set to false under production environment as it adds an unnecessary overhead to each execution.

Default: false.
consistency Number <optional>
 Consistency level. Default: localOne.
customPayload Object <optional>
 Key-value payload to be passed to the server. On the Cassandra side, implementations of QueryHandler can use this data.
executionProfile String | ExecutionProfile <optional>
 Name or instance of the profile to be used for this execution. If not set, it will the use "default" execution profile.
fetchSize Number <optional>
 Amount of rows to retrieve per page.
hints Array | Array.<Array> <optional>
 Type hints for parameters given in the query, ordered as for the parameters.

For batch queries, an array of such arrays, ordered as with the queries in the batch.
logged Boolean <optional>
 Determines if the batch should be written to the batchlog. Only valid for Client#batch(), it will be ignored by other methods. Default: true.
pageState Buffer | String <optional>
 Buffer or string token representing the paging state.

Useful for manual paging, if provided, the query will be executed starting from a given paging state.
prepare Boolean <optional>
 Determines if the query must be executed as a prepared statement.
readTimeout Number <optional>
 When defined, it overrides the default read timeout (socketOptions.readTimeout) in milliseconds for this execution per coordinator.

Suitable for statements for which the coordinator may allow a longer server-side timeout, for example aggregation queries.

A value of 0 disables client side read timeout for the execution. Default: undefined.

retry RetryPolicy <optional>
 Retry policy for the query.

This property can be used to specify a different retry policy to the one specified in the ClientOptions.policies.

retryOnTimeout Boolean <optional>
 Determines if the client should retry when it didn't hear back from a host within socketOptions.readTimeout. Default: true.
routingIndexes Array <optional>
 Index of the parameters that are part of the partition key to determine the routing.
routingKey Buffer | Array <optional>
 Partition key(s) to determine which coordinator should be used for the query.
routingNames Array <optional>
 Array of the parameters names that are part of the partition key to determine the routing.
serialConsistency Number <optional>
 Serial consistency is the consistency level for the serial phase of conditional updates. This option will be ignored for anything else that a conditional update/insert.
timestamp Number | Long <optional>
 The default timestamp for the query in microseconds from the unix epoch (00:00:00, January 1st, 1970).

If provided, this will replace the server side assigned timestamp as default timestamp.

Use generateTimestamp() utility method to generate a valid timestamp based on a Date and microseconds parts.
traceQuery Boolean <optional>
 Enable query tracing for the execution. Use query tracing to diagnose performance problems related to query executions. Default: false.

To retrieve trace, you can call Metadata.getTrace() method.

ResultCallback(err, resultopt)

Callback used by execution methods.
Parameters:
Name Type Attributes Description
err Error Error occurred in the execution of the query.
result ResultSet <optional>
 Result of the execution of the query.