• 2.8
• 2.7
• 2.6
• 2.5
• 2.4
• 2.3
• 2.2
• 2.1
• 2.0
• 1.0

cass_cluster_new

Creates a new cluster.

Returns:

Type	Details
CassCluster *	Returns a cluster that must be freed.

See Also:

• CassCluster::cass_cluster_free

cass_cluster_free

Frees a cluster instance.

Parameters:

Name	Type	Details
in cluster

cass_cluster_set_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
in contact_points	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.

cass_cluster_set_contact_points_n

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

Parameters:

Name	Type	Details
in cluster
in contact_points
in contact_points_length

Returns:

Type	Details
CassError	same as CassCluster::cass_cluster_set_contact_points

See Also:

• CassCluster::cass_cluster_set_contact_points

cass_cluster_set_port

Sets the port.

Default: 9042

Parameters:

Name	Type	Details
in cluster
in port

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_ssl

Sets the SSL context and enables SSL.

Parameters:

Name	Type	Details
in cluster
in ssl

See Also:

• CassSsl::cass_ssl_new

cass_cluster_set_authenticator_callbacks

Sets custom authenticator

Parameters:

Name	Type	Details
in cluster
in exchange_callbacks
in cleanup_callback
in data

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_protocol_version

Sets the protocol version. This will automatically downgrade to the lowest supported protocol version.

Default: CASS_PROTOCOL_VERSION_V4

Parameters:

Name	Type	Details
in cluster
in protocol_version

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

See Also:

• CassCluster::cass_cluster_set_use_beta_protocol_version

cass_cluster_set_use_beta_protocol_version

Use the newest beta protocol version. This currently enables the use of protocol version v5 (CASS_PROTOCOL_VERSION_V5).

Default: cass_false

Parameters:

Name	Type	Details
in cluster
in enable	if false the highest non-beta protocol version will be used

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_consistency

Sets default consistency level of statement.

Default: CASS_CONSISTENCY_LOCAL_ONE

Parameters:

Name	Type	Details
in cluster
in consistency

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_serial_consistency

Sets default serial consistency level of statement.

Default: CASS_CONSISTENCY_ANY

Parameters:

Name	Type	Details
in cluster
in consistency

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_num_threads_io

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
in num_threads

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_queue_size_io

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

Default: 8192

Parameters:

Name	Type	Details
in cluster
in queue_size

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_queue_size_event

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

Default: 8192

Parameters:

Name	Type	Details
in cluster
in queue_size

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_core_connections_per_host

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

Default: 1

Parameters:

Name	Type	Details
in cluster
in num_connections

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_max_connections_per_host

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

Default: 2

Parameters:

Name	Type	Details
in cluster
in num_connections

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_reconnect_wait_time

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

Default: 2000 milliseconds

Parameters:

Name	Type	Details
in cluster
in wait_time

cass_cluster_set_max_concurrent_creation

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

Parameters:

Name	Type	Details
in cluster
in num_connections

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_max_concurrent_requests_threshold

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

Parameters:

Name	Type	Details
in cluster
in num_requests

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_max_requests_per_flush

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

Default: 128

Parameters:

Name	Type	Details
in cluster
in num_requests

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_write_bytes_high_water_mark

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
in num_bytes

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_write_bytes_low_water_mark

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
in num_bytes

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_pending_requests_high_water_mark

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
in num_requests

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_pending_requests_low_water_mark

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
in num_requests

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred.

cass_cluster_set_connect_timeout

Sets the timeout for connecting to a node.

Default: 5000 milliseconds

Parameters:

Name	Type	Details
in cluster
in timeout_ms	Connect timeout in milliseconds

cass_cluster_set_request_timeout

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

Default: 12000 milliseconds

Parameters:

Name	Type	Details
in cluster
in timeout_ms	Request timeout in milliseconds. Use 0 for no timeout.

cass_cluster_set_resolve_timeout

Sets the timeout for waiting for DNS name resolution.

Default: 2000 milliseconds

Parameters:

Name	Type	Details
in cluster
in timeout_ms	Request timeout in milliseconds

cass_cluster_set_credentials

Sets credentials for plain text authentication.

Parameters:

Name	Type	Details
in cluster
in username
in password

cass_cluster_set_credentials_n

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

Parameters:

Name	Type	Details
in cluster
in username
in username_length
in password
in password_length

Returns:

Type	Details
void	same as CassCluster::cass_cluster_set_credentials

See Also:

• CassCluster::cass_cluster_set_credentials ;

cass_cluster_set_load_balance_round_robin

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

cass_cluster_set_load_balance_dc_aware

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.

Parameters:

Name	Type	Details
in cluster
in local_dc	The primary data center to try first
in used_hosts_per_remote_dc	The number of host used in each remote DC if no hosts are available in the local dc
in allow_remote_dcs_for_local_cl	Allows remote hosts to be used if no local dc hosts are available and the consistency level is LOCAL_ONE or LOCAL_QUORUM

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred

cass_cluster_set_load_balance_dc_aware_n

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

Parameters:

Name	Type	Details
in cluster
in local_dc
in local_dc_length
in used_hosts_per_remote_dc
in allow_remote_dcs_for_local_cl

Returns:

Type	Details
CassError	same as CassCluster::cass_cluster_set_load_balance_dc_aware

See Also:

• CassCluster::cass_cluster_set_load_balance_dc_aware

cass_cluster_set_token_aware_routing

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
in enabled

cass_cluster_set_latency_aware_routing

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
in enabled

cass_cluster_set_latency_aware_routing_settings

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
in exclusion_threshold	Controls how much worse the latency must be compared to the average latency of the best performing node before it penalized.
in scale_ms	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	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	The rate at which the best average latency is recomputed.
in min_measured	The minimum number of measurements per-host required to be considered by the policy.

cass_cluster_set_whitelist_filtering

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
in hosts	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.

cass_cluster_set_whitelist_filtering_n

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

Parameters:

Name	Type	Details
in cluster
in hosts
in hosts_length

Returns:

Type	Details
void	same as cass_cluster_set_whitelist_filtering_hosts()

See Also:

• cass_cluster_set_whitelist_filtering_hosts()

cass_cluster_set_blacklist_filtering

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
in hosts	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.

cass_cluster_set_blacklist_filtering_n

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

Parameters:

Name	Type	Details
in cluster
in hosts
in hosts_length

Returns:

Type	Details
void	same as cass_cluster_set_blacklist_filtering_hosts()

See Also:

• cass_cluster_set_blacklist_filtering_hosts()

cass_cluster_set_whitelist_dc_filtering

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
in dcs	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.

cass_cluster_set_whitelist_dc_filtering_n

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

Parameters:

Name	Type	Details
in cluster
in dcs
in dcs_length

Returns:

Type	Details
void	same as CassCluster::cass_cluster_set_whitelist_dc_filtering

See Also:

• CassCluster::cass_cluster_set_whitelist_dc_filtering

cass_cluster_set_blacklist_dc_filtering

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
in dcs	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.

cass_cluster_set_blacklist_dc_filtering_n

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

Parameters:

Name	Type	Details
in cluster
in dcs
in dcs_length

Returns:

Type	Details
void	same as CassCluster::cass_cluster_set_blacklist_dc_filtering

See Also:

• CassCluster::cass_cluster_set_blacklist_dc_filtering

cass_cluster_set_tcp_nodelay

Enable/Disable Nagle’s algorithm on connections.

Default: cass_true (disables Nagle’s algorithm).

Parameters:

Name	Type	Details
in cluster
in enabled

cass_cluster_set_tcp_keepalive

Enable/Disable TCP keep-alive

Default: cass_false (disabled).

Parameters:

Name	Type	Details
in cluster
in enabled
in delay_secs	The initial delay in seconds, ignored when enabled is false.

cass_cluster_set_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: server-side timestamp generator.

Requires Cassandra: 2.1+

Parameters:

Name	Type	Details
in cluster
in timestamp_gen

See Also:

• CassStatement::cass_statement_set_timestamp
• CassBatch::cass_batch_set_timestamp

cass_cluster_set_connection_heartbeat_interval

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
in interval_secs	Use 0 to disable heartbeat messages

cass_cluster_set_connection_idle_timeout

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
in timeout_secs

cass_cluster_set_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
in retry_policy

See Also:

• CassRetryPolicy::cass_retry_policy_default_new
• CassStatement::cass_statement_set_retry_policy
• CassBatch::cass_batch_set_retry_policy

cass_cluster_set_use_schema

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
in enabled

See Also:

• CassSession::cass_session_get_schema_meta

cass_cluster_set_use_hostname_resolution

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).

Important: Not implemented if using libuv 0.1x or earlier

Parameters:

Name	Type	Details
in cluster
in enabled

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred

See Also:

• CassCluster::cass_cluster_set_resolve_timeout

cass_cluster_set_use_randomized_contact_points

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
in enabled

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred

cass_cluster_set_constant_speculative_execution_policy

Enable constant speculative executions with the supplied settings.

Parameters:

Name	Type	Details
in cluster
in constant_delay_ms
in max_speculative_executions

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred

cass_cluster_set_no_speculative_execution_policy

Disable speculative executions

Default: This is the default speculative execution policy.

Parameters:

Name	Type	Details
in cluster

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred

cass_cluster_set_prepare_on_all_hosts

Prepare statements on all available hosts.

Default: cass_true

Parameters:

Name	Type	Details
cluster
enabled

Returns:

Type	Details
CassError	CASS_OK if successful, otherwise an error occurred