Skip to main content

Java Client Policies

Overview​

This page describes how you can customize your client policies for optimal query performance and reliability. Aerospike client policies control the behavior of database queries at a fine-grained level.

Connecting to the server​

The com.aerospike.client.policy package includes classes and interfaces for defining the client/server connection, including authentication, consistency guarantees, and TCP keep-alive. See Program.cs for a code example demonstrating how to use ClientPolicy.

Basic timeout settings​

Aerospike clients offer a variety of timeout and retry settings that you can set for any operation requests. You can modify these timeout settings in the policy objects, and then they are passed as a parameter when the Aerospike operation is requested.

Timeout setting recommendations behave as you would expect - you should increase timeout lengths longer than a normal request time to avoid premature timeouts. Decrease timeout lengths if you know it is safe to do so to avoid unnecessary delays in detecting a real abnormal condition or problem with the network or server.

Increase the number of retries and the time between retries in an environment where your responses are unreliable, due to either network or server issues. Keep in mind that doing so will also cause more delays in detecting fatal error conditions such as real network or server outages.

  • Socket timeout: Policy.socketTimeout specifies socket idle timeout in milliseconds when processing a database command.

  • Total timeout: Policy.totalTimeout specifies total transaction timeout in milliseconds.

  • Max retries: Policy.maxRetries specifies the maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

  • Sleep between retries: Policy.sleepBetweenRetries specifies the milliseconds to sleep between retries. Enter zero to skip sleep. This field is ignored when maxRetries is zero. This field is also ignored in async mode.

For more information, see the timeout policies blog post.

Connection pool configuration​

Whenever possible, Aerospike clients manage an internal session pool to avoid the cost of creating a session when making an operation request. A variety of client policy options are available to control the behavior of the Aerospike client's session pool management. You can avoid fluctuation in the client pool and create a fixed resource utilization cost by setting the minimum connections per node to the same value as the maximum connections per node.

  • Increase the minimum connections per node to avoid the transaction overhead for creating new connections after a period of relative inactivity. This situation can arise if your workload has spikes or waves of high volume, but comes at the cost of constant increased client-side resource utilization.

  • Increase the maximum connections per node to avoid transaction overhead and blocking or queuing during your peak workload periods. This can greatly increase your client-side resource utilization. You may want to reduce this number if you are controlling client-side scaling externally. For instance, with Kubernetes application side scaling, you may want to reduce the total number of outstanding sessions that the Aerospike server will need to support simultaneously.

Minimum connections per node​

Increase the minimum connections per node to avoid the transaction overhead for creating new connections after a period of relative inactivity. This situation can arise if your workload has spikes or waves of high volume, but comes at the cost of constant increased client-side resource utilization.

ClientPolicy.minConnsPerNode is the minimum number of synchronous connections allowed per server node. Setting this option preallocates the minimum connections on client node creation. The client periodically allocates new connections if the count falls below minConnsPerNode.

For more information, see minConnsPerNode.

You can avoid fluctuation in the client pool and create a fixed resource utilization cost by setting the minimum connections per node to the same value as the maximum connections per node.

Maximum connections per node​

Increase the maximum connections per node to avoid transaction overhead and blocking or queuing during your peak workload periods. This can greatly increase your client-side resource utilization. You may want to reduce this number if you are controlling client-side scaling externally. For instance, with Kubernetes application side scaling, you may want to reduce the total number of outstanding sessions that the Aerospike server will need to support simultaneously. ClientPolicy.maxConnsPerNode is the maximum number of synchronous connections allowed per server node. Transactions go through retry logic and potentially fail with ResultCode.NO_MORE_CONNECTIONS if the maximum number of connections is exceeded.

Backoff behavior​

Aerospike clients provide client-side backoff or circuit breaker functionality that you can control with the Client policy. This functionality restricts an application from overwhelming the server with requests if it notices an increase in the number of errors returned by the server. We highly recommend that you use this functionality, especially in situations where you have a large or scalable application workload connected to a single Aerospike cluster.

  • Max error rate: ClientPolicy.maxErrorRate is the maximum number of errors allowed per node during an interval defined by ClientPolicy.errorRateWindow before the backoff algorithm throws an AerospikeException.Backoff error on database commands to that node. If maxErrorRate is zero, there is no error limit and the exception is never thrown.
  • Error rate window: ClientPolicy.errorRateWindow is the number of cluster tend iterations to use to evaluate the maxErrorRate. If the maxErrorRate is reached, the backoff algorithm rejects additional database commands to the node until the number of errors goes back down.

Tend configuration​

Every client instance runs a cluster tend thread that periodically polls server nodes for cluster status. You can control how frequently client instances check in with the server by adjusting the tend interval.

Policy defaults​

Every client application database API call takes a policy parameter, and if that parameter is null the API call uses the default policy. You can set defaults for all the various clientPolicy parameters and use them throughout the application, rather than setting a policy for every API call.

The following example creates a client policy, sets defaults, and connects to a cluster:

ClientPolicy clientPolicy = new ClientPolicy();
clientPolicy.readPolicyDefault.socketTimeout = 100;
clientPolicy.readPolicyDefault.totalTimeout = 100;
clientPolicy.writePolicyDefault.socketTimeout = 500;
clientPolicy.writePolicyDefault.totalTimeout = 500;

// Connect to the cluster.
AerospikeClient client = new AerospikeClient(clientPolicy, new Host("localhost", 3000));

Single operation policy defaults are set in the following Client properties:

  • readPolicyDefault
  • writePolicyDefault
  • scanPolicyDefault
  • queryPolicyDefault

All of these policies inherit from the base Policy class. You can set base Policy default settings for each single operation type by using the associated base Policy inherited properties.

Batch operation defaults are set with the following Client properties:

  • batchPolicyDefault
  • batchParentPolicyWriteDefault
  • batchWritePolicyDefault
  • batchDeletePolicyDefault
  • batchUDFPolicyDefault

Note that batchWritePolicy, batchDeletePolicy, and BatchUDF policies do not inherit from the base batchPolicy class. To properly set default batch policies for the client object, use:

  • batchPolicyDefault property to set defaults for reads.
  • batchParentPolicyWriteDefault to set base policy property defaults for writes
  • batchWritePolicyDefault, batchDeletePolicyDefault, and batchUDFPolicyDefault to set the detailed specific property settings for those batch operations.

Transaction client policies​

You can use WritePolicy parameters such as CommitLevel and DurableDelete to control transaction settings on a per-transaction basis.

// Make a copy of the client's default write policy.
WritePolicy policy = new WritePolicy(client.writePolicyDefault);

// Change commit level.
policy.commitLevel = CommitLevel.COMMIT_MASTER;

// Write record with modified write policy.
client.put(policy, key, bins);

More information about transactions can be found on the Transaction operations page.

Batch operations​

Batch operations affect multiple records with a single request. Batch requests can occur serially or in parallel, depending on the batch policy settings.

ClientPolicy.batchPolicyDefault defines the default settings for the batch policy, which are used whenver null is passed to an API call as the policy parameter.

Batch write operations process multiple updates in a single operation using fewer connections. Batch write policy options include:

  • Commit level: BatchWritePolicy.commitLevel specifies a consistency guarantee when committing a transaction on the server.

  • Durable delete: BatchWritePolicy.durableDelete is a boolean value. If true, the server leaves a tombstone for the record if the transaction results in a record deletion.

Collection Data Types (CDT)​

ListPolicy and MapPolicy define how list and map operations should behave.

  • Write flags: MapWriteFlags and ListWriteFlags provide options for what to do if a key specified by a write operation already exists or contains duplicate data.