A cluster object describes the configuration of the Cassandra cluster and is used to construct a session instance. Unlike other DataStax drivers the cluster object does not maintain the control connection.

Functions

CassCluster *

cass_cluster_new

( )

Creates a new cluster.

Returns:
Type Details
CassCluster *

Returns a cluster that must be freed.

See Also:
void

cass_cluster_free

( CassCluster * cluster )

Frees a cluster instance.

Parameters:
Name Type Details
in cluster CassCluster *
CassError

cass_cluster_set_contact_points

( CassCluster * cluster, const char * contact_points )

Sets/Appends contact points. This MUST be set. The first call sets the contact points and any subsequent calls appends additional contact points. Passing an empty string will clear the contact points. White space is striped from the contact points.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”, “server1.domain.com”

Parameters:
Name Type Details
in cluster CassCluster *
in contact_points const char *

A comma delimited list of addresses or names. An empty string will clear the contact points. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_contact_points_n

( CassCluster * cluster, const char * contact_points, size_t contact_points_length )

Same as CassCluster::cass_cluster_set_contact_points, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in contact_points const char *
in contact_points_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_contact_points

See Also:
CassError

cass_cluster_set_port

( CassCluster * cluster, int port )

Sets the port.

Default: 9042

Parameters:
Name Type Details
in cluster CassCluster *
in port int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_local_address

( CassCluster * cluster, const char * name )

Sets the local address to bind when connecting to the cluster, if desired.

Parameters:
Name Type Details
in cluster CassCluster *
in name const char *

IP address to bind, or empty string for no binding. Only numeric addresses are supported; no resolution is done.

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_local_address_n

( CassCluster * cluster, const char * name, size_t name_length )

Same as CassCluster::cass_cluster_set_local_address, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in name const char *
in name_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_local_address

See Also:
void

cass_cluster_set_ssl

( CassCluster * cluster, CassSsl * ssl )

Sets the SSL context and enables SSL.

Parameters:
Name Type Details
in cluster CassCluster *
in ssl CassSsl *
See Also:
CassError

cass_cluster_set_authenticator_callbacks

( CassCluster * cluster, const CassAuthenticatorCallbacks * exchange_callbacks, CassAuthenticatorDataCleanupCallback cleanup_callback, void * data )

Sets custom authenticator

Parameters:
Name Type Details
in cluster CassCluster *
in exchange_callbacks const CassAuthenticatorCallbacks *
in cleanup_callback CassAuthenticatorDataCleanupCallback
in data void *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_protocol_version

( CassCluster * cluster, int protocol_version )

Sets the protocol version. The driver will automatically downgrade to the lowest supported protocol version.

Default: CASS_PROTOCOL_VERSION_V4 or CASS_PROTOCOL_VERSION_DSEV1 when using the DSE driver with DataStax Enterprise.

Parameters:
Name Type Details
in cluster CassCluster *
in protocol_version int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

See Also:
CassError

cass_cluster_set_use_beta_protocol_version

( CassCluster * cluster, cass_bool_t enable )

Use the newest beta protocol version. This currently enables the use of protocol version v5 (CASS_PROTOCOL_VERSION_V5) or DSEv2 (CASS_PROTOCOL_VERSION_DSEV2) when using the DSE driver with DataStax Enterprise.

Default: cass_false

Parameters:
Name Type Details
in cluster CassCluster *
in enable cass_bool_t

if false the highest non-beta protocol version will be used

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_consistency

( CassCluster * cluster, CassConsistency consistency )

Sets default consistency level of statement.

Default: CASS_CONSISTENCY_LOCAL_ONE

Parameters:
Name Type Details
in cluster CassCluster *
in consistency CassConsistency
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_serial_consistency

( CassCluster * cluster, CassConsistency consistency )

Sets default serial consistency level of statement.

Default: CASS_CONSISTENCY_ANY

Parameters:
Name Type Details
in cluster CassCluster *
in consistency CassConsistency
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_num_threads_io

( CassCluster * cluster, unsigned num_threads )

Sets the number of IO threads. This is the number of threads that will handle query requests.

Default: 1

Parameters:
Name Type Details
in cluster CassCluster *
in num_threads unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_queue_size_io

( CassCluster * cluster, unsigned queue_size )

Sets the size of the fixed size queue that stores pending requests.

Default: 8192

Parameters:
Name Type Details
in cluster CassCluster *
in queue_size unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_queue_size_event

( CassCluster * cluster, unsigned queue_size )

Sets the size of the fixed size queue that stores events.

Default: 8192

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in queue_size unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_core_connections_per_host

( CassCluster * cluster, unsigned num_connections )

Sets the number of connections made to each server in each IO thread.

Default: 1

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_connections_per_host

( CassCluster * cluster, unsigned num_connections )

Sets the maximum number of connections made to each server in each IO thread.

Default: 2

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

void

cass_cluster_set_reconnect_wait_time

( CassCluster * cluster, unsigned wait_time )

Sets the amount of time to wait before attempting to reconnect.

Deprecated:

This is being replaced with CassCluster::cass_cluster_set_constant_reconnect. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in wait_time unsigned
void

cass_cluster_set_constant_reconnect

( CassCluster * cluster, cass_uint64_t delay_ms )

Configures the cluster to use a reconnection policy that waits a constant time between each reconnection attempt.

Parameters:
Name Type Details
in cluster CassCluster *
in delay_ms cass_uint64_t

Time in milliseconds to delay attempting a reconnection; 0 to perform a reconnection immediately.

CassError

cass_cluster_set_exponential_reconnect

( CassCluster * cluster, cass_uint64_t base_delay_ms, cass_uint64_t max_delay_ms )

Configures the cluster to use a reconnection policy that waits exponentially longer between each reconnection attempt; however will maintain a constant delay once the maximum delay is reached.

Default:

  • 2000 milliseconds base delay
  • 60000 milliseconds max delay

Note: A random amount of jitter (+/- 15%) will be added to the pure exponential delay value. This helps to prevent situations where multiple connections are in the reconnection process at exactly the same time. The jitter will never cause the delay to be less than the base delay, or more than the max delay.

Parameters:
Name Type Details
in cluster CassCluster *
in base_delay_ms cass_uint64_t

The base delay (in milliseconds) to use for scheduling reconnection attempts.

in max_delay_ms cass_uint64_t

The maximum delay to wait between two reconnection attempts.

Returns:
Type Details
CassError

CASS_OK if successful, otherwise error occurred.

CassError

cass_cluster_set_coalesce_delay

( CassCluster * cluster, cass_int64_t delay_us )

Sets the amount of time, in microseconds, to wait for new requests to coalesce into a single system call. This should be set to a value around the latency SLA of your application’s requests while also considering the request’s roundtrip time. Larger values should be used for throughput bound workloads and lower values should be used for latency bound workloads.

Default: 200 us

Parameters:
Name Type Details
in cluster CassCluster *
in delay_us cass_int64_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_new_request_ratio

( CassCluster * cluster, cass_int32_t ratio )

Sets the ratio of time spent processing new requests versus handling the I/O and processing of outstanding requests. The range of this setting is 1 to 100, where larger values allocate more time to processing new requests and smaller values allocate more time to processing outstanding requests.

Default: 50

Parameters:
Name Type Details
in cluster CassCluster *
in ratio cass_int32_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_concurrent_creation

( CassCluster * cluster, unsigned num_connections )

Sets the maximum number of connections that will be created concurrently. Connections are created when the current connections are unable to keep up with request throughput.

Default: 1

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_concurrent_requests_threshold

( CassCluster * cluster, unsigned num_requests )

Sets the threshold for the maximum number of concurrent requests in-flight on a connection before creating a new connection. The number of new connections created will not exceed max_connections_per_host.

Default: 100

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_requests_per_flush

( CassCluster * cluster, unsigned num_requests )

Sets the maximum number of requests processed by an IO worker per flush.

Default: 128

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_write_bytes_high_water_mark

( CassCluster * cluster, unsigned num_bytes )

Sets the high water mark for the number of bytes outstanding on a connection. Disables writes to a connection if the number of bytes queued exceed this value.

Default: 64 KB

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_bytes unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_write_bytes_low_water_mark

( CassCluster * cluster, unsigned num_bytes )

Sets the low water mark for number of bytes outstanding on a connection. After exceeding high water mark bytes, writes will only resume once the number of bytes fall below this value.

Default: 32 KB

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_bytes unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_pending_requests_high_water_mark

( CassCluster * cluster, unsigned num_requests )

Sets the high water mark for the number of requests queued waiting for a connection in a connection pool. Disables writes to a host on an IO worker if the number of requests queued exceed this value.

Default: 256

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_pending_requests_low_water_mark

( CassCluster * cluster, unsigned num_requests )

Sets the low water mark for the number of requests queued waiting for a connection in a connection pool. After exceeding high water mark requests, writes to a host will only resume once the number of requests fall below this value.

Default: 128

Deprecated:

This is no longer useful and does nothing. Expect this to be removed in a future release.

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

void

cass_cluster_set_connect_timeout

( CassCluster * cluster, unsigned timeout_ms )

Sets the timeout for connecting to a node.

Default: 5000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_ms unsigned

Connect timeout in milliseconds

void

cass_cluster_set_request_timeout

( CassCluster * cluster, unsigned timeout_ms )

Sets the timeout for waiting for a response from a node.

Default: 12000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_ms unsigned

Request timeout in milliseconds. Use 0 for no timeout.

void

cass_cluster_set_resolve_timeout

( CassCluster * cluster, unsigned timeout_ms )

Sets the timeout for waiting for DNS name resolution.

Default: 2000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_ms unsigned

Request timeout in milliseconds

void

cass_cluster_set_max_schema_wait_time

( CassCluster * cluster, unsigned wait_time_ms )

Sets the maximum time to wait for schema agreement after a schema change is made (e.g. creating, altering, dropping a table/keyspace/view/index etc).

Default: 10000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in wait_time_ms unsigned

Wait time in milliseconds

void

cass_cluster_set_credentials

( CassCluster * cluster, const char * username, const char * password )

Sets credentials for plain text authentication.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in password const char *
void

cass_cluster_set_credentials_n

( CassCluster * cluster, const char * username, size_t username_length, const char * password, size_t password_length )

Same as CassCluster::cass_cluster_set_credentials, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in username_length size_t
in password const char *
in password_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_credentials

See Also:
void

cass_cluster_set_load_balance_round_robin

( CassCluster * cluster )

Configures the cluster to use round-robin load balancing.

The driver discovers all nodes in a cluster and cycles through them per request. All are considered ‘local’.

Parameters:
Name Type Details
in cluster CassCluster *
CassError

cass_cluster_set_load_balance_dc_aware

( CassCluster * cluster, const char * local_dc, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Configures the cluster to use DC-aware load balancing. For each query, all live nodes in a primary ‘local’ DC are tried first, followed by any node from other DCs.

Note: This is the default, and does not need to be called unless switching an existing from another policy or changing settings. Without further configuration, a default local_dc is chosen from the first connected contact point, and no remote hosts are considered in query plans. If relying on this mechanism, be sure to use only contact points from the local DC.

Deprecated:

The remote DC settings for DC-aware are not suitable for most scenarios that require DC failover. There is also unhandled gap between replication factor number of nodes failing and the full cluster failing. Only the remote DC settings are being deprecated.

Parameters:
Name Type Details
in cluster CassCluster *
in local_dc const char *

The primary data center to try first

in used_hosts_per_remote_dc unsigned

The number of hosts used in each remote DC if no hosts are available in the local dc (deprecated)

in allow_remote_dcs_for_local_cl cass_bool_t

Allows remote hosts to be used if no local dc hosts are available and the consistency level is LOCAL_ONE or LOCAL_QUORUM (deprecated)

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_load_balance_dc_aware_n

( CassCluster * cluster, const char * local_dc, size_t local_dc_length, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Same as CassCluster::cass_cluster_set_load_balance_dc_aware, but with lengths for string parameters.

Deprecated:

The remote DC settings for DC-aware are not suitable for most scenarios that require DC failover. There is also unhandled gap between replication factor number of nodes failing and the full cluster failing. Only the remote DC settings are being deprecated.

Parameters:
Name Type Details
in cluster CassCluster *
in local_dc const char *
in local_dc_length size_t
in used_hosts_per_remote_dc unsigned

(deprecated)

in allow_remote_dcs_for_local_cl cass_bool_t

(deprecated)

Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_load_balance_dc_aware

See Also:
void

cass_cluster_set_token_aware_routing

( CassCluster * cluster, cass_bool_t enabled )

Configures the cluster to use token-aware request routing or not.

Important: Token-aware routing depends on keyspace metadata. For this reason enabling token-aware routing will also enable retrieving and updating keyspace schema metadata.

Default: cass_true (enabled).

This routing policy composes the base routing policy, routing requests first to replicas on nodes considered ‘local’ by the base load balancing policy.

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_token_aware_routing_shuffle_replicas

( CassCluster * cluster, cass_bool_t enabled )

Configures token-aware routing to randomly shuffle replicas. This can reduce the effectiveness of server-side caching, but it can better distribute load over replicas for a given partition key.

Note: Token-aware routing must be enabled for the setting to be applicable.

Default: cass_true (enabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_latency_aware_routing

( CassCluster * cluster, cass_bool_t enabled )

Configures the cluster to use latency-aware request routing or not.

Default: cass_false (disabled).

This routing policy is a top-level routing policy. It uses the base routing policy to determine locality (dc-aware) and/or placement (token-aware) before considering the latency.

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_latency_aware_routing_settings

( CassCluster * cluster, cass_double_t exclusion_threshold, cass_uint64_t scale_ms, cass_uint64_t retry_period_ms, cass_uint64_t update_rate_ms, cass_uint64_t min_measured )

Configures the settings for latency-aware request routing.

Defaults:

  • exclusion_threshold: 2.0
  • scale_ms: 100 milliseconds
  • retry_period_ms: 10,000 milliseconds (10 seconds)
  • update_rate_ms: 100 milliseconds
  • min_measured: 50
Parameters:
Name Type Details
in cluster CassCluster *
in exclusion_threshold cass_double_t

Controls how much worse the latency must be compared to the average latency of the best performing node before it penalized.

in scale_ms cass_uint64_t

Controls the weight given to older latencies when calculating the average latency of a node. A bigger scale will give more weight to older latency measurements.

in retry_period_ms cass_uint64_t

The amount of time a node is penalized by the policy before being given a second chance when the current average latency exceeds the calculated threshold (exclusion_threshold * best_average_latency).

in update_rate_ms cass_uint64_t

The rate at which the best average latency is recomputed.

in min_measured cass_uint64_t

The minimum number of measurements per-host required to be considered by the policy.

void

cass_cluster_set_whitelist_filtering

( CassCluster * cluster, const char * hosts )

Sets/Appends whitelist hosts. The first call sets the whitelist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the whitelist. White space is striped from the hosts.

This policy filters requests to all other policies, only allowing requests to the hosts contained in the whitelist. Any host not in the whitelist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will only connect to a predefined set of hosts.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”

Parameters:
Name Type Details
in cluster CassCluster *
in hosts const char *

A comma delimited list of addresses. An empty string will clear the whitelist hosts. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

void

cass_cluster_set_whitelist_filtering_n

( CassCluster * cluster, const char * hosts, size_t hosts_length )

Same as CassCluster::cass_cluster_set_whitelist_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in hosts const char *
in hosts_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_whitelist_filtering

See Also:
void

cass_cluster_set_blacklist_filtering

( CassCluster * cluster, const char * hosts )

Sets/Appends blacklist hosts. The first call sets the blacklist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the blacklist. White space is striped from the hosts.

This policy filters requests to all other policies, only allowing requests to the hosts not contained in the blacklist. Any host in the blacklist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will not connect to a predefined set of hosts.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”

Parameters:
Name Type Details
in cluster CassCluster *
in hosts const char *

A comma delimited list of addresses. An empty string will clear the blacklist hosts. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

void

cass_cluster_set_blacklist_filtering_n

( CassCluster * cluster, const char * hosts, size_t hosts_length )

Same as cass_cluster_set_blacklist_filtering_hosts(), but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in hosts const char *
in hosts_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_blacklist_filtering

See Also:
void

cass_cluster_set_whitelist_dc_filtering

( CassCluster * cluster, const char * dcs )

Same as CassCluster::cass_cluster_set_whitelist_filtering, but whitelist all hosts of a dc

Examples: “dc1”, “dc1,dc2”

Parameters:
Name Type Details
in cluster CassCluster *
in dcs const char *

A comma delimited list of dcs. An empty string will clear the whitelist dcs. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

void

cass_cluster_set_whitelist_dc_filtering_n

( CassCluster * cluster, const char * dcs, size_t dcs_length )

Same as CassCluster::cass_cluster_set_whitelist_dc_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in dcs const char *
in dcs_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_whitelist_dc_filtering

See Also:
void

cass_cluster_set_blacklist_dc_filtering

( CassCluster * cluster, const char * dcs )

Same as CassCluster::cass_cluster_set_blacklist_filtering, but blacklist all hosts of a dc

Examples: “dc1”, “dc1,dc2”

Parameters:
Name Type Details
in cluster CassCluster *
in dcs const char *

A comma delimited list of dcs. An empty string will clear the blacklist dcs. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

void

cass_cluster_set_blacklist_dc_filtering_n

( CassCluster * cluster, const char * dcs, size_t dcs_length )

Same as CassCluster::cass_cluster_set_blacklist_dc_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in dcs const char *
in dcs_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_blacklist_dc_filtering

See Also:
void

cass_cluster_set_tcp_nodelay

( CassCluster * cluster, cass_bool_t enabled )

Enable/Disable Nagle’s algorithm on connections.

Default: cass_true (disables Nagle’s algorithm).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_tcp_keepalive

( CassCluster * cluster, cass_bool_t enabled, unsigned delay_secs )

Enable/Disable TCP keep-alive

Default: cass_false (disabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
in delay_secs unsigned

The initial delay in seconds, ignored when enabled is false.

void

cass_cluster_set_timestamp_gen

( CassCluster * cluster, CassTimestampGen * timestamp_gen )

Sets the timestamp generator used to assign timestamps to all requests unless overridden by setting the timestamp on a statement or a batch.

Default: Monotonically increasing, client-side timestamp generator.

Requires Apache Cassandra: 2.1+

Parameters:
Name Type Details
in cluster CassCluster *
in timestamp_gen CassTimestampGen *
See Also:
void

cass_cluster_set_connection_heartbeat_interval

( CassCluster * cluster, unsigned interval_secs )

Sets the amount of time between heartbeat messages and controls the amount of time the connection must be idle before sending heartbeat messages. This is useful for preventing intermediate network devices from dropping connections.

Default: 30 seconds

Parameters:
Name Type Details
in cluster CassCluster *
in interval_secs unsigned

Use 0 to disable heartbeat messages

void

cass_cluster_set_connection_idle_timeout

( CassCluster * cluster, unsigned timeout_secs )

Sets the amount of time a connection is allowed to be without a successful heartbeat response before being terminated and scheduled for reconnection.

Default: 60 seconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_secs unsigned
void

cass_cluster_set_retry_policy

( CassCluster * cluster, CassRetryPolicy * retry_policy )

Sets the retry policy used for all requests unless overridden by setting a retry policy on a statement or a batch.

Default: The same policy as would be created by the function: CassRetryPolicy::cass_retry_policy_default_new. This policy will retry on a read timeout if there was enough replicas, but no data present, on a write timeout if a logged batch request failed to write the batch log, and on a unavailable error it retries using a new host. In all other cases the default policy will return an error.

Parameters:
Name Type Details
in cluster CassCluster *
in retry_policy CassRetryPolicy *
See Also:
void

cass_cluster_set_use_schema

( CassCluster * cluster, cass_bool_t enabled )

Enable/Disable retrieving and updating schema metadata. If disabled this is allows the driver to skip over retrieving and updating schema metadata and CassSession::cass_session_get_schema_meta will always return an empty object. This can be useful for reducing the startup overhead of short-lived sessions.

Default: cass_true (enabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
See Also:
CassError

cass_cluster_set_use_hostname_resolution

( CassCluster * cluster, cass_bool_t enabled )

Enable/Disable retrieving hostnames for IP addresses using reverse IP lookup.

This is useful for authentication (Kerberos) or encryption (SSL) services that require a valid hostname for verification.

Default: cass_false (disabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

See Also:
CassError

cass_cluster_set_use_randomized_contact_points

( CassCluster * cluster, cass_bool_t enabled )

Enable/Disable the randomization of the contact points list.

Default: cass_true (enabled).

Important: This setting should only be disabled for debugging or tests.

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_constant_speculative_execution_policy

( CassCluster * cluster, cass_int64_t constant_delay_ms, int max_speculative_executions )

Enable constant speculative executions with the supplied settings.

Parameters:
Name Type Details
in cluster CassCluster *
in constant_delay_ms cass_int64_t
in max_speculative_executions int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_no_speculative_execution_policy

( CassCluster * cluster )

Disable speculative executions

Default: This is the default speculative execution policy.

Parameters:
Name Type Details
in cluster CassCluster *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_max_reusable_write_objects

( CassCluster * cluster, unsigned num_objects )

Sets the maximum number of “pending write” objects that will be saved for re-use for marshalling new requests. These objects may hold on to a significant amount of memory and reducing the number of these objects may reduce memory usage of the application.

The cost of reducing the value of this setting is potentially slower marshalling of requests prior to sending.

Default: Max unsigned integer value

Parameters:
Name Type Details
in cluster CassCluster *
in num_objects unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_execution_profile

( CassCluster * cluster, const char * name, CassExecProfile * profile )

Associates a named execution profile which can be utilized during execution.

Note: Once the execution profile is added to a cluster, it is immutable and any changes made to the execution profile must be re-assigned to the cluster before a session connection is established in order for those settings to be utilized during query execution.

Parameters:
Name Type Details
in cluster CassCluster *
in name const char *
in profile CassExecProfile *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

See Also:
CassError

cass_cluster_set_execution_profile_n

( CassCluster * cluster, const char * name, size_t name_length, CassExecProfile * profile )

Same as cass_cluster_add_execution_profile(), but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in name const char *
in name_length size_t
in profile CassExecProfile *
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_execution_profile

See Also:
CassError

cass_cluster_set_prepare_on_all_hosts

( CassCluster * cluster, cass_bool_t enabled )

Prepare statements on all available hosts.

Default: cass_true

Parameters:
Name Type Details
cluster CassCluster *
enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_no_compact

( CassCluster * cluster, cass_bool_t enabled )

Enable the NO_COMPACT startup option.

This can help facilitate uninterrupted cluster upgrades where tables using COMPACT_STORAGE will operate in “compatibility mode” for BATCH, DELETE, SELECT, and UPDATE CQL operations.

Default: cass_false

Requires Apache Cassandra: 3.0.16+ Requires Apache Cassandra: 3.11.2+ Requires Apache Cassandra: 4.0+

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
CassError

cass_cluster_set_host_listener_callback

( CassCluster * cluster, CassHostListenerCallback callback, void * data )

Sets a callback for handling host state changes in the cluster.

Note: The callback is invoked only when state changes in the cluster are applicable to the configured load balancing policy(s).

Parameters:
Name Type Details
in cluster CassCluster *
in callback CassHostListenerCallback
in data void *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise and error occurred

void

cass_cluster_set_application_name

( CassCluster * cluster, const char * application_name )

Set the application name.

This is optional; however it provides the server with the application name that can aid in debugging issues with larger clusters where there are a lot of client (or application) connections.

Parameters:
Name Type Details
in cluster CassCluster *
in application_name const char *
void

cass_cluster_set_application_name_n

( CassCluster * cluster, const char * application_name, size_t application_name_length )

Same as CassCluster::cass_cluster_set_application_name, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in application_name const char *
in application_name_length size_t
void

cass_cluster_set_application_version

( CassCluster * cluster, const char * application_version )

Set the application version.

This is optional; however it provides the server with the application version that can aid in debugging issues with large clusters where there are a lot of client (or application) connections that may have different versions in use.

Parameters:
Name Type Details
in cluster CassCluster *
in application_version const char *
void

cass_cluster_set_application_version_n

( CassCluster * cluster, const char * application_version, size_t application_version_length )

Same as CassCluster::cass_cluster_set_application_version, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in application_version const char *
in application_version_length size_t
void

cass_cluster_set_client_id

( CassCluster * cluster, CassUuid client_id )

Set the client id.

This is optional; however it provides the server with the client ID that can aid in debugging issues with large clusters where there are a lot of client connections.

Default: UUID v4 generated (

Parameters:
Name Type Details
in cluster CassCluster *
in client_id CassUuid
See Also:
void

cass_cluster_set_monitor_reporting_interval

( CassCluster * cluster, unsigned interval_secs )

Sets the amount of time between monitor reporting event messages.

Default: 300 seconds.

Parameters:
Name Type Details
in cluster CassCluster *
in interval_secs unsigned

Use 0 to disable monitor reporting event messages.

CassError

cass_cluster_set_dse_gssapi_authenticator

( CassCluster * cluster, const char * service, const char * principal )

Enables GSSAPI authentication for DSE clusters secured with the DseAuthenticator.

Parameters:
Name Type Details
in cluster CassCluster *
in service const char *
in principal const char *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_dse_gssapi_authenticator_n

( CassCluster * cluster, const char * service, size_t service_length, const char * principal, size_t principal_length )

Same as CassCluster::cass_cluster_set_dse_gssapi_authenticator, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in service const char *
in service_length size_t
in principal const char *
in principal_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_dse_gssapi_authenticator

CassError

cass_cluster_set_dse_gssapi_authenticator_proxy

( CassCluster * cluster, const char * service, const char * principal, const char * authorization_id )

Enables GSSAPI authentication with proxy authorization for DSE clusters secured with the DseAuthenticator.

Parameters:
Name Type Details
in cluster CassCluster *
in service const char *
in principal const char *
in authorization_id const char *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_dse_gssapi_authenticator_proxy_n

( CassCluster * cluster, const char * service, size_t service_length, const char * principal, size_t principal_length, const char * authorization_id, size_t authorization_id_length )

Same as CassCluster::cass_cluster_set_dse_gssapi_authenticator_proxy, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in service const char *
in service_length size_t
in principal const char *
in principal_length size_t
in authorization_id const char *
in authorization_id_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_dse_gssapi_authenticator_proxy

CassError

cass_cluster_set_dse_plaintext_authenticator

( CassCluster * cluster, const char * username, const char * password )

Enables plaintext authentication for DSE clusters secured with the DseAuthenticator.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in password const char *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_dse_plaintext_authenticator_n

( CassCluster * cluster, const char * username, size_t username_length, const char * password, size_t password_length )

Same as CassCluster::cass_cluster_set_dse_plaintext_authenticator, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in username_length size_t
in password const char *
in password_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_dse_plaintext_authenticator

CassError

cass_cluster_set_dse_plaintext_authenticator_proxy

( CassCluster * cluster, const char * username, const char * password, const char * authorization_id )

Enables plaintext authentication with proxy authorization for DSE clusters secured with the DseAuthenticator.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in password const char *
in authorization_id const char *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_dse_plaintext_authenticator_proxy_n

( CassCluster * cluster, const char * username, size_t username_length, const char * password, size_t password_length, const char * authorization_id, size_t authorization_id_length )

Same as CassCluster::cass_cluster_set_dse_plaintext_authenticator_proxy, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in username_length size_t
in password const char *
in password_length size_t
in authorization_id const char *
in authorization_id_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_dse_plaintext_authenticator_proxy