Policies

Using Policies

The Aerospike C client uses policies to define behavior for database operations. Policies are values that dictate the behavior of an operation. Each operation relies on a set of policy values, collectively called an operation policy. Each operation accepts a policy as the third argument. For example, aerospike_key_get() requires an as_policy_read as the third argument.

as_status aerospike_key_get(
    aerospike *as, as_error *err, const as_policy_read *policy,
    const as_key *key,
    as_record **rec
    );

Policy Values

A policy is a value used by an operation. Policies can also have an undefined value. When a value is undefined, it triggers a fallback mechanism to find a default value for the policy.

Defining Default Policies

Default policies are defined during client configuration. This allows you to set the default policies before the Aerospike C client.

Note

You must initialize default policies to their default values before modifying the configuration. Once initialized, you can modify the policies.

as_config config;
as_config_init(&config)

To set write operations to a 2-second timeout, but keep all other operations to 1-second timeouts:

config.policies.write.totalTimeout = 2000;

In this example, aerospike_key_get() defaults to a 1-second timeout and aerospike_key_put() defaults to a 2-second timeout.

Policy Fallback Mechanism

When a policy value is undefined for an operation or the operation policy is NULL, then the undefined policy values default to those in the operation policy for that operation. The default operation policy is defined as part of the Aerospike C client instance, which dictates default behavior for that client instance. If the default operation policy contains an undefined value, then the value in the default policy is used. Default policy values are defined in the Aerospike C client.

For example, as_policy_read is an operation policy applicable to read operations. This policy has two policy values: timeout and key. The timeout policy dictates operation wait time before a timeout. The key policy (as_policy_key) dictates how to use the key in the operation. A totalTimeout of 1000 is the default value. The key policy also has a default value: AS_POLICY_KEY_DIGEST.

The aerospike_key_get() operation accepts an as_policy_read policy. The following example sets the operation policy to NULL to return all values for the policy to the values in the default operation policy.

aerospike_key_get(&as, &err, NULL, &key, &rec);

In this example, the default operation policy for read (as_policy_read) has been re-defined as:

aerospike.config.policies.read.key = AS_POLICY_KEY_SEND;

The operation will use AS_POLICY_KEY_SEND rather than Aerospike C Client default value of AS_POLICY_KEY_DIGEST. Since the totalTimeout policy is undefined, the operation will still use the totalTimeout policy default of 1000.

aerospike.config.policies.totalTimeout = 1000;

Defining a Policy for an Operation

To provide an operation policy on a per-operation basis, initialize the policy and set the values to override. Note that each operation policy has an initialization function.

as_policy_read policy;
as_policy_read_init(&policy);

Then, set the values of the policy:

policy.base.totalTimeout = 5000;

Now, pass the policy to the operation:

aerospike_key_get(&as, &err, &policy, &key, &rec);

This results in the following policy for the operation:

policy.base.totalTimeout = 5000;
policy.key = AS_POLICY_DIGEST;

This is because the key policy value was not defined for the policy provided to the operation. It defaults to the default read policy value for the key policy:

aerospike.config.policies.read.key = AS_POLICY_KEY_DIGEST;