Tuning policies

Tuning policies determine load balancing, retrying queries, and reconnecting to a node.

Load balancing policy

The load balancing policy determines which node to execute a query on.


The load balancing policy interface consists of three methods:
  • HostDistance Distance(Host host): determines the distance to the specified host. The values are HostDistance.IGNORED, LOCAL, and REMOTE.
  • void Initialize(Cluster cluster): initializes the policy. The driver calls this method only once and before any other method calls are made.
  • IEnumerable<Host> NewQueryPlan(): returns the hosts to use for a query. Each new query calls this method.
The policy also implements the Host.StateListener interface which is for tracking node events (that is add, down, remove, and up).
By default, the driver uses a round robin load balancing policy when building a cluster object. There is also a token-aware policy which allows the ability to prefer the replica for a query as coordinator. The driver includes these three policy classes:
  • DCAwareRoundRobinPolicy
  • RoundRobinPolicy
  • TokenAwarePolicy

Reconnection policy

The reconnection policy determines how often a reconnection to a dead node is attempted.


The reconnection policy consists of one method:
  • IReconnectionSchedule NewSchedule(): creates a new schedule to use in reconnection attempts.
By default, the driver uses an exponential reconnection policy. The driver includes these two policy classes:
  • ConstantReconnectionPolicy
  • ExponentialReconnectionPolicy

Retry policy

The retry policy determines a default behavior to adopt when a request either times out or if a node is unavailable.


A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an UnavailableException, but if the replica fails after the request is made, it throws a TimeoutException. Of course, this all depends on the consistency level set for the query before executing it.

A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code.

The retry policy interface consists of three methods:
  • RetryDecision OnReadTimeout(Query query, ConsistencyLevel cl, int requiredResponses, int receivedResponses, boolean dataRetrieved, int nbRetry)
  • RetryDecision OnUnavailable(Query query, ConsistencyLevel cl, int requiredReplica, int aliveReplica, int nbRetry)
  • RetryDecision OnWriteTimeout(Query query, ConsistencyLevel cl, WriteType writeType, int requiredAcks, int receivedAcks, int nbRetry)
By default, the driver uses a default retry policy. The driver includes these four policy classes:
  • DefaultRetryPolicy
  • DowngradingConsistencyRetryPolicy
  • FallthroughRetryPolicy
  • LoggingRetryPolicy