Client Policies

Description

Policies define the behavior of database operations.

Policies fall into two groups: policy values and operation policies. A policy value is a single value which defines how the client behaves. An operation policy is a group of policy values which affect an operation.

Policy Values

The following are the policy values. For details, please see the documentation for each policy value

• as_policy_key
• as_policy_gen
• as_policy_exists
• as_policy_replica
• as_policy_read_mode_ap
• as_policy_read_mode_sc
• as_policy_commit_level

Operation Policies

The following are the operation policies. Operation policies are groups of policy values for a type of operation.

• as_policy_batch
• as_policy_info
• as_policy_operate
• as_policy_read
• as_policy_remove
• as_policy_query
• as_policy_scan
• as_policy_write

Data Structures
struct	as_policies
struct	as_policy_admin
struct	as_policy_apply
struct	as_policy_base
struct	as_policy_batch
struct	as_policy_batch_apply
struct	as_policy_batch_read
struct	as_policy_batch_remove
struct	as_policy_batch_write
struct	as_policy_info
struct	as_policy_operate
struct	as_policy_query
struct	as_policy_read
struct	as_policy_remove
struct	as_policy_scan
struct	as_policy_write

Macros
#define	AS_POLICY_COMMIT_LEVEL_DEFAULT   AS_POLICY_COMMIT_LEVEL_ALL
#define	AS_POLICY_COMPRESSION_THRESHOLD_DEFAULT   0
#define	AS_POLICY_EXISTS_DEFAULT   AS_POLICY_EXISTS_IGNORE
#define	AS_POLICY_GEN_DEFAULT   AS_POLICY_GEN_IGNORE
#define	AS_POLICY_KEY_DEFAULT   AS_POLICY_KEY_DIGEST
#define	AS_POLICY_READ_MODE_AP_DEFAULT   AS_POLICY_READ_MODE_AP_ONE
#define	AS_POLICY_READ_MODE_SC_DEFAULT   AS_POLICY_READ_MODE_SC_SESSION
#define	AS_POLICY_REPLICA_DEFAULT   AS_POLICY_REPLICA_SEQUENCE
#define	AS_POLICY_SOCKET_TIMEOUT_DEFAULT   30000
#define	AS_POLICY_TOTAL_TIMEOUT_DEFAULT   1000

Enumerations
enum	as_policy_commit_level { AS_POLICY_COMMIT_LEVEL_ALL , AS_POLICY_COMMIT_LEVEL_MASTER }
enum	as_policy_exists {   AS_POLICY_EXISTS_IGNORE , AS_POLICY_EXISTS_CREATE , AS_POLICY_EXISTS_UPDATE , AS_POLICY_EXISTS_REPLACE ,   AS_POLICY_EXISTS_CREATE_OR_REPLACE }
enum	as_policy_gen { AS_POLICY_GEN_IGNORE , AS_POLICY_GEN_EQ , AS_POLICY_GEN_GT }
enum	as_policy_key { AS_POLICY_KEY_DIGEST , AS_POLICY_KEY_SEND }
enum	as_policy_read_mode_ap { AS_POLICY_READ_MODE_AP_ONE , AS_POLICY_READ_MODE_AP_ALL }
enum	as_policy_read_mode_sc { AS_POLICY_READ_MODE_SC_SESSION , AS_POLICY_READ_MODE_SC_LINEARIZE , AS_POLICY_READ_MODE_SC_ALLOW_REPLICA , AS_POLICY_READ_MODE_SC_ALLOW_UNAVAILABLE }
enum	as_policy_replica { AS_POLICY_REPLICA_MASTER , AS_POLICY_REPLICA_ANY , AS_POLICY_REPLICA_SEQUENCE , AS_POLICY_REPLICA_PREFER_RACK }
enum	as_policy_retry { AS_POLICY_RETRY_NONE , AS_POLICY_RETRY_ONCE }
enum	as_query_duration { AS_QUERY_DURATION_LONG , AS_QUERY_DURATION_SHORT , AS_QUERY_DURATION_LONG_RELAX_AP }

Macro Definition Documentation

AS_POLICY_COMMIT_LEVEL_DEFAULT

#define AS_POLICY_COMMIT_LEVEL_DEFAULT   AS_POLICY_COMMIT_LEVEL_ALL

Default as_policy_commit_level value for write

Definition at line 134 of file as_policy.h.

AS_POLICY_COMPRESSION_THRESHOLD_DEFAULT

#define AS_POLICY_COMPRESSION_THRESHOLD_DEFAULT   0

Default value for compression threshold

Definition at line 85 of file as_policy.h.

AS_POLICY_EXISTS_DEFAULT

#define AS_POLICY_EXISTS_DEFAULT   AS_POLICY_EXISTS_IGNORE

Default as_policy_exists value

Definition at line 106 of file as_policy.h.

AS_POLICY_GEN_DEFAULT

#define AS_POLICY_GEN_DEFAULT   AS_POLICY_GEN_IGNORE

Default as_policy_gen value

Definition at line 92 of file as_policy.h.

AS_POLICY_KEY_DEFAULT

#define AS_POLICY_KEY_DEFAULT   AS_POLICY_KEY_DIGEST

Default as_policy_key value

Definition at line 99 of file as_policy.h.

AS_POLICY_READ_MODE_AP_DEFAULT

#define AS_POLICY_READ_MODE_AP_DEFAULT   AS_POLICY_READ_MODE_AP_ONE

Default as_policy_read_mode_ap value

Definition at line 120 of file as_policy.h.

AS_POLICY_READ_MODE_SC_DEFAULT

#define AS_POLICY_READ_MODE_SC_DEFAULT   AS_POLICY_READ_MODE_SC_SESSION

Default as_policy_read_mode_sc value

Definition at line 127 of file as_policy.h.

AS_POLICY_REPLICA_DEFAULT

#define AS_POLICY_REPLICA_DEFAULT   AS_POLICY_REPLICA_SEQUENCE

Default as_policy_replica value

Definition at line 113 of file as_policy.h.

AS_POLICY_SOCKET_TIMEOUT_DEFAULT

#define AS_POLICY_SOCKET_TIMEOUT_DEFAULT   30000

Default socket idle timeout value

Definition at line 71 of file as_policy.h.

AS_POLICY_TOTAL_TIMEOUT_DEFAULT

#define AS_POLICY_TOTAL_TIMEOUT_DEFAULT   1000

Default total timeout value

Definition at line 78 of file as_policy.h.

Enumeration Type Documentation

as_policy_commit_level

enum as_policy_commit_level

Commit Level

Specifies the number of replicas required to be successfully committed before returning success in a write operation to provide the desired consistency guarantee.

Enumerator
AS_POLICY_COMMIT_LEVEL_ALL	Return succcess only after successfully committing all replicas.
AS_POLICY_COMMIT_LEVEL_MASTER	Return succcess after successfully committing the master replica.

Definition at line 371 of file as_policy.h.

as_policy_exists

enum as_policy_exists

Existence Policy

Specifies the behavior for writing the record depending whether or not it exists.

Enumerator
AS_POLICY_EXISTS_IGNORE	Write the record, regardless of existence. (i.e. create or update.)
AS_POLICY_EXISTS_CREATE	Create a record, ONLY if it doesn't exist.
AS_POLICY_EXISTS_UPDATE	Update a record, ONLY if it exists.
AS_POLICY_EXISTS_REPLACE	Completely replace a record, ONLY if it exists.
AS_POLICY_EXISTS_CREATE_OR_REPLACE	Completely replace a record if it exists, otherwise create it.

Definition at line 237 of file as_policy.h.

as_policy_gen

enum as_policy_gen

Generation Policy

Specifies the behavior of record modifications with regard to the generation value.

Enumerator
AS_POLICY_GEN_IGNORE	Do not use record generation to restrict writes.
AS_POLICY_GEN_EQ	Update/delete record if expected generation is equal to server generation. Otherwise, fail.
AS_POLICY_GEN_GT	Update/delete record if expected generation greater than the server generation. Otherwise, fail. This is useful for restore after backup.

Definition at line 173 of file as_policy.h.

as_policy_key

enum as_policy_key

Key Policy

Specifies the behavior for whether keys or digests should be sent to the cluster.

Enumerator
AS_POLICY_KEY_DIGEST	Send the digest value of the key. This is the recommended mode of operation. This calculates the digest and send the digest to the server. The digest is only calculated on the client, and not on the server.
AS_POLICY_KEY_SEND	Send the key, in addition to the digest value. If you want keys to be returned when scanning or querying, the keys must be stored on the server. This policy causes a write operation to store the key. Once a key is stored, the server will keep it - there is no need to use this policy on subsequent updates of the record. If this policy is used on read or delete operations, or on subsequent updates of a record with a stored key, the key sent will be compared with the key stored on the server. A mismatch will cause AEROSPIKE_ERR_RECORD_KEY_MISMATCH to be returned.

Definition at line 201 of file as_policy.h.

as_policy_read_mode_ap

enum as_policy_read_mode_ap

Read policy for AP (availability) namespaces.

How duplicates should be consulted in a read operation. Only makes a difference during migrations and only applicable in AP mode.

Enumerator
AS_POLICY_READ_MODE_AP_ONE	Involve single node in the read operation.
AS_POLICY_READ_MODE_AP_ALL	Involve all duplicates in the read operation.

Definition at line 313 of file as_policy.h.

as_policy_read_mode_sc

enum as_policy_read_mode_sc

Read policy for SC (strong consistency) namespaces.

Determines SC read consistency options.

Enumerator
AS_POLICY_READ_MODE_SC_SESSION	Ensures this client will only see an increasing sequence of record versions. Client only reads from master. This is the default.
AS_POLICY_READ_MODE_SC_LINEARIZE	Ensures all clients will only see an increasing sequence of record versions. Client only reads from master.
AS_POLICY_READ_MODE_SC_ALLOW_REPLICA	Client may read from master or any full (non-migrating) replica. Increasing sequence of record versions is not guaranteed.
AS_POLICY_READ_MODE_SC_ALLOW_UNAVAILABLE	Client may read from master or any full (non-migrating) replica or from unavailable partitions. Increasing sequence of record versions is not guaranteed.

Definition at line 334 of file as_policy.h.

as_policy_replica

enum as_policy_replica

Replica Policy

Defines algorithm used to determine the target node for a command.

Enumerator
AS_POLICY_REPLICA_MASTER	Use node containing key's master partition.
AS_POLICY_REPLICA_ANY	Distribute reads across nodes containing key's master and replicated partition in round-robin fashion.
AS_POLICY_REPLICA_SEQUENCE	Try node containing master partition first. If connection fails, all commands try nodes containing replicated partitions. If socketTimeout is reached, reads also try nodes containing replicated partitions, but writes remain on master node.
AS_POLICY_REPLICA_PREFER_RACK	For reads, try node on preferred racks first. If there are no nodes on preferred racks, use SEQUENCE instead. Also use SEQUENCE for writes. as_config.rack_aware, as_config.rack_id or as_config.rack_ids, and server rack configuration must also be set to enable this functionality.

Definition at line 273 of file as_policy.h.

as_policy_retry

enum as_policy_retry

Retry Policy

Specifies the behavior of failed operations.

Enumerator
AS_POLICY_RETRY_NONE	Only attempt an operation once.
AS_POLICY_RETRY_ONCE	If an operation fails, attempt the operation one more time.

Definition at line 150 of file as_policy.h.

as_query_duration

enum as_query_duration

Expected query duration. The server treats the query in different ways depending on the expected duration. This enum is ignored for aggregation queries, background queries and server versions < 6.0.

Enumerator
AS_QUERY_DURATION_LONG	The query is expected to return more than 100 records per node. The server optimizes for a large record set in the following ways: Allow query to be run in multiple threads using the server's query threading configuration. Do not relax read consistency for AP namespaces. Add the query to the server's query monitor. Do not add the overall latency to the server's latency histogram. Do not allow server timeouts.
AS_QUERY_DURATION_SHORT	The query is expected to return less than 100 records per node. The server optimizes for a small record set in the following ways: Always run the query in one thread and ignore the server's query threading configuration. Allow query to be inlined directly on the server's service thread. Relax read consistency for AP namespaces. Do not add the query to the server's query monitor. Add the overall latency to the server's latency histogram. Allow server timeouts. The default server timeout for a short query is 1 second.
AS_QUERY_DURATION_LONG_RELAX_AP	Treat query as a LONG query, but relax read consistency for AP namespaces. This value is treated exactly like LONG for server versions < 7.1.

Definition at line 391 of file as_policy.h.