Detailed Description

The aerospike_key_operate() function provides the ability to execute multiple operations on a record in the database as a single atomic transaction.

The as_operations object is used to define the operations to be performed on the record.

Initialization

Before using as_operations, you must first initialize it via either:

as_operations_inita() is a macro that initializes a stack allocated as_operations and allocates an internal array of operations. The macro accepts a pointer to the stack allocated as_operations and the number of operations to be added.

as_operations ops;

as_operations_inita(&ops, 2);

as_operations_init() is a function that initializes a stack allocated as_operations. It differes from as_operations_inita() in that it allocates the internal array of operations on the heap. It accepts a pointer to the stack allocated as_operations and the number of operations to be added.

as_operations ops;

as_operations_init(&ops, 2);

as_operations_new() is a function that will allocate a new as_operations on the heap. It will also allocate the internal array of operation on the heap.

as_operations* ops = as_operations_new(2);

When you no longer need the as_operations, you can release the resources allocated to it via as_operations_destroy().

Destruction

When you no longer require an as_operations, you should call as_operations_destroy() to release it and associated resources.

as_operations_destroy(ops);

Usage

as_operations is a sequence of operations to be applied to a record.

Each of the following operations is added to the end of the sequence of operations.

When you have compiled the sequence of operations you want to execute, then you will send it to aerospike_key_operate().

Modifying a String

Aerospike allows you to append a string to a bin containing a string.

The following appends a "abc" to bin "bin1".

as_operations_add_append_str(ops, "bin1", "abc");

There is also a prepend operation, which will add the string to the beginning of the bin's current value.

as_operations_add_prepend_str(ops, "bin1", "abc");

Modifying a Byte Array

Aerospike allows you to append a byte array to a bin containing a byte array.

The following appends a 4 byte sequence to bin "bin1".

uint8_t raw[4] = { 1, 2, 3, 4 };

as_operations_add_append_raw(ops, "bin1", raw, 4);

There is also a prepend operation, which will add the bytes to the beginning of the bin's current value.

uint8_t raw[4] = { 1, 2, 3, 4 };

as_operations_add_prepend_raw(ops, "bin1", raw, 4);

Increment an Integer

Aerospike allows you to increment the value of a bin

The following increments the value in bin "bin1" by 4.

as_operations_add_incr(ops, "bin1", 4);

Write a Value

Write a value into a bin. Overwriting previous value.

The following writes a string "xyz" to "bin1".

as_operations_add_write_str(ops, "bin1", "xyz");

Read a Value

Read a value from a bin. This is ideal, if you performed an operation on a bin, and want to read the new value.

The following reads the value of "bin1"

as_operations_add_read(ops, "bin1");

Touch a Record

Touching a record will refresh its ttl and increment the generation of the record.

The following touches a record.

as_operations_add_touch(ops);

Definition at line 254 of file as_operations.h.

#include "as_operations.h"

Collaboration diagram for as_operations:

Data Fields
as_binops	binops

uint16_t	gen

uint32_t	ttl

Related Functions
(Note that these are not member functions.)
static void	as_cdt_ctx_add_list_index (as_cdt_ctx *ctx, int index)

static void	as_cdt_ctx_add_list_index_create (as_cdt_ctx *ctx, int index, as_list_order order, bool pad)

static void	as_cdt_ctx_add_list_rank (as_cdt_ctx *ctx, int rank)

static void	as_cdt_ctx_add_list_value (as_cdt_ctx ctx, as_val val)

static void	as_cdt_ctx_add_map_index (as_cdt_ctx *ctx, int index)

static void	as_cdt_ctx_add_map_key (as_cdt_ctx ctx, as_val key)

static void	as_cdt_ctx_add_map_key_create (as_cdt_ctx ctx, as_val key, as_map_order order)

static void	as_cdt_ctx_add_map_rank (as_cdt_ctx *ctx, int rank)

static void	as_cdt_ctx_add_map_value (as_cdt_ctx ctx, as_val val)

static as_cdt_ctx *	as_cdt_ctx_create (uint32_t capacity)

AS_EXTERN void	as_cdt_ctx_destroy (as_cdt_ctx *ctx)

static void	as_cdt_ctx_init (as_cdt_ctx *ctx, uint32_t capacity)

#define	as_cdt_ctx_inita(__ctx, __cap) as_vector_inita(&(__ctx)->list, sizeof(as_cdt_ctx_item), __cap)

enum	as_cdt_ctx_type

static bool	as_operations_add_append_raw (as_operations ops, const char name, const uint8_t *value, uint32_t size)

AS_EXTERN bool	as_operations_add_append_rawp (as_operations ops, const char name, const uint8_t *value, uint32_t size, bool free)

static bool	as_operations_add_append_str (as_operations ops, const char name, const char *value)

AS_EXTERN bool	as_operations_add_append_strp (as_operations ops, const char name, const char *value, bool free)

AS_EXTERN bool	as_operations_add_delete (as_operations *ops)

AS_EXTERN bool	as_operations_add_incr (as_operations ops, const char name, int64_t value)

AS_EXTERN bool	as_operations_add_incr_double (as_operations ops, const char name, double value)

static bool	as_operations_add_prepend_raw (as_operations ops, const char name, const uint8_t *value, uint32_t size)

AS_EXTERN bool	as_operations_add_prepend_rawp (as_operations ops, const char name, const uint8_t *value, uint32_t size, bool free)

static bool	as_operations_add_prepend_str (as_operations ops, const char name, const char *value)

AS_EXTERN bool	as_operations_add_prepend_strp (as_operations ops, const char name, const char *value, bool free)

AS_EXTERN bool	as_operations_add_read (as_operations ops, const char name)

AS_EXTERN bool	as_operations_add_read_all (as_operations *ops)

AS_EXTERN bool	as_operations_add_touch (as_operations *ops)

AS_EXTERN bool	as_operations_add_write (as_operations ops, const char name, as_bin_value *value)

AS_EXTERN bool	as_operations_add_write_bool (as_operations ops, const char name, bool value)

AS_EXTERN bool	as_operations_add_write_double (as_operations ops, const char name, double value)

static bool	as_operations_add_write_geojson_str (as_operations ops, const char name, const char *value)

AS_EXTERN bool	as_operations_add_write_geojson_strp (as_operations ops, const char name, const char *value, bool free)

AS_EXTERN bool	as_operations_add_write_int64 (as_operations ops, const char name, int64_t value)

static bool	as_operations_add_write_raw (as_operations ops, const char name, const uint8_t *value, uint32_t size)

AS_EXTERN bool	as_operations_add_write_rawp (as_operations ops, const char name, const uint8_t *value, uint32_t size, bool free)

static bool	as_operations_add_write_str (as_operations ops, const char name, const char *value)

AS_EXTERN bool	as_operations_add_write_strp (as_operations ops, const char name, const char *value, bool free)

AS_EXTERN void	as_operations_destroy (as_operations *ops)

AS_EXTERN as_operations *	as_operations_init (as_operations *ops, uint16_t nops)

#define	as_operations_inita(__ops, __nops)

AS_EXTERN as_operations *	as_operations_new (uint16_t nops)

Friends And Related Function Documentation

static void as_cdt_ctx_add_list_index	(	as_cdt_ctx *	ctx,
		int	index
	)

If the index is negative, the resolved index starts backwards from end of list. If an index is out of bounds, a parameter error will be returned. Examples:

0: First item.
4: Fifth item.
-1: Last item.
-3: Third to last item.

Definition at line 154 of file as_cdt_ctx.h.

References AS_CDT_CTX_LIST_INDEX, as_vector_append(), as_cdt_ctx_item::ival, as_cdt_ctx::list, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_list_index_create	(	as_cdt_ctx *	ctx,
		int	index,
		as_list_order	order,
		bool	pad
	)

Definition at line 169 of file as_cdt_ctx.h.

References AS_CDT_CTX_LIST_INDEX, as_list_order_to_flag(), as_vector_append(), as_cdt_ctx_item::ival, as_cdt_ctx::list, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_list_rank	(	as_cdt_ctx *	ctx,
		int	rank
	)

0 = smallest value
N = Nth smallest value
-1 = largest value

Definition at line 189 of file as_cdt_ctx.h.

References AS_CDT_CTX_LIST_RANK, as_vector_append(), as_cdt_ctx_item::ival, as_cdt_ctx::list, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_list_value	(	as_cdt_ctx *	ctx,
		as_val *	val
	)

Definition at line 204 of file as_cdt_ctx.h.

References AS_CDT_CTX_LIST_VALUE, as_vector_append(), as_cdt_ctx::list, as_cdt_ctx_item::pval, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_map_index	(	as_cdt_ctx *	ctx,
		int	index
	)

If the index is negative, the resolved index starts backwards from end of list. If an index is out of bounds, a parameter error will be returned. Examples:

0: First item.
4: Fifth item.
-1: Last item.
-3: Third to last item.

Definition at line 228 of file as_cdt_ctx.h.

References AS_CDT_CTX_MAP_INDEX, as_vector_append(), as_cdt_ctx_item::ival, as_cdt_ctx::list, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_map_key	(	as_cdt_ctx *	ctx,
		as_val *	key
	)

Definition at line 263 of file as_cdt_ctx.h.

References AS_CDT_CTX_MAP_KEY, as_vector_append(), as_cdt_ctx::list, as_cdt_ctx_item::pval, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_map_key_create	(	as_cdt_ctx *	ctx,
		as_val *	key,
		as_map_order	order
	)

Definition at line 279 of file as_cdt_ctx.h.

References AS_CDT_CTX_MAP_KEY, as_map_order_to_flag(), as_vector_append(), as_cdt_ctx::list, as_cdt_ctx_item::pval, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_map_rank	(	as_cdt_ctx *	ctx,
		int	rank
	)

0 = smallest value
N = Nth smallest value
-1 = largest value

Definition at line 248 of file as_cdt_ctx.h.

References AS_CDT_CTX_MAP_RANK, as_vector_append(), as_cdt_ctx_item::ival, as_cdt_ctx::list, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static void as_cdt_ctx_add_map_value	(	as_cdt_ctx *	ctx,
		as_val *	val
	)

Definition at line 294 of file as_cdt_ctx.h.

References AS_CDT_CTX_MAP_VALUE, as_vector_append(), as_cdt_ctx::list, as_cdt_ctx_item::pval, as_cdt_ctx_item::type, and as_cdt_ctx_item::val.

static as_cdt_ctx * as_cdt_ctx_create ( uint32_t capacity )

Definition at line 124 of file as_cdt_ctx.h.

References as_vector_create().

AS_EXTERN void as_cdt_ctx_destroy ( as_cdt_ctx * ctx )

static void as_cdt_ctx_init	(	as_cdt_ctx *	ctx,
		uint32_t	capacity
	)

Definition at line 111 of file as_cdt_ctx.h.

References as_vector_init(), and as_cdt_ctx::list.

#define as_cdt_ctx_inita	(	__ctx,
		__cap
	)	as_vector_inita(&(__ctx)->list, sizeof(as_cdt_ctx_item), __cap)

Lookup last list in list of lists.
as_cdt_ctx ctx;
as_cdt_ctx_inita(&ctx, 1);
as_cdt_ctx_add_list_index(&ctx, -1);

Call as_cdt_ctx_destroy() when done with the context list if any context levels contain a heap allocated as_val instance. If in doubt, call as_cdt_ctx_destroy().

Parameters

__ctx	The nested context to initialize.
__cap	The max number of context levels allowed.

Definition at line 97 of file as_cdt_ctx.h.

enum as_cdt_ctx_type

Definition at line 37 of file as_cdt_ctx.h.

static bool as_operations_add_append_raw	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.
size	The size of the value.

Returns: true on success. Otherwise an error occurred.

Definition at line 739 of file as_operations.h.

References as_operations_add_append_rawp().

AS_EXTERN bool as_operations_add_append_rawp	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
size	The size of the value.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_append_str	(	as_operations *	ops,
		const char *	name,
		const char *	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.

Returns: true on success. Otherwise an error occurred.

Definition at line 703 of file as_operations.h.

References as_operations_add_append_strp().

AS_EXTERN bool as_operations_add_append_strp	(	as_operations *	ops,
		const char *	name,
		const char *	value,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_delete ( as_operations * ops )

Parameters

ops	The `as_operations` to append the operation to.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_incr	(	as_operations *	ops,
		const char *	name,
		int64_t	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_incr_double	(	as_operations *	ops,
		const char *	name,
		double	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_prepend_raw	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.
size	The size of the value.

Returns: true on success. Otherwise an error occurred.

Definition at line 669 of file as_operations.h.

References as_operations_add_prepend_rawp().

AS_EXTERN bool as_operations_add_prepend_rawp	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
size	The size of the value.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_prepend_str	(	as_operations *	ops,
		const char *	name,
		const char *	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.

Returns: true on success. Otherwise an error occurred.

Definition at line 633 of file as_operations.h.

References as_operations_add_prepend_strp().

AS_EXTERN bool as_operations_add_prepend_strp	(	as_operations *	ops,
		const char *	name,
		const char *	value,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_read	(	as_operations *	ops,
		const char *	name
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_read_all ( as_operations * ops )

Parameters

ops	The `as_operations` to append the operation to.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_touch ( as_operations * ops )

Parameters

ops	The `as_operations` to append the operation to.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_write	(	as_operations *	ops,
		const char *	name,
		as_bin_value *	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_write_bool	(	as_operations *	ops,
		const char *	name,
		bool	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_write_double	(	as_operations *	ops,
		const char *	name,
		double	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_write_geojson_str	(	as_operations *	ops,
		const char *	name,
		const char *	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.

Returns: true on success. Otherwise an error occurred.

Definition at line 506 of file as_operations.h.

References as_operations_add_write_geojson_strp().

AS_EXTERN bool as_operations_add_write_geojson_strp	(	as_operations *	ops,
		const char *	name,
		const char *	value,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN bool as_operations_add_write_int64	(	as_operations *	ops,
		const char *	name,
		int64_t	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_write_raw	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
size	The size of the value. Must last for the lifetime of the operations.

Returns: true on success. Otherwise an error occurred.

Definition at line 542 of file as_operations.h.

References as_operations_add_write_rawp().

AS_EXTERN bool as_operations_add_write_rawp	(	as_operations *	ops,
		const char *	name,
		const uint8_t *	value,
		uint32_t	size,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
size	The size of the value.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

static bool as_operations_add_write_str	(	as_operations *	ops,
		const char *	name,
		const char *	value
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation. Must last for the lifetime of the operations.

Returns: true on success. Otherwise an error occurred.

Definition at line 472 of file as_operations.h.

References as_operations_add_write_strp().

AS_EXTERN bool as_operations_add_write_strp	(	as_operations *	ops,
		const char *	name,
		const char *	value,
		bool	free
	)

Parameters

ops	The `as_operations` to append the operation to.
name	The name of the bin to perform the operation on.
value	The value to be used in the operation.
free	If true, then the value will be freed when the operations is destroyed.

Returns: true on success. Otherwise an error occurred.

AS_EXTERN void as_operations_destroy ( as_operations * ops )

as_operations_destroy(binops);

Parameters

ops	The `as_operations` to destroy.

AS_EXTERN as_operations * as_operations_init	(	as_operations *	ops,
		uint16_t	nops
	)

as_operations ops;
as_operations_init(&ops, 2);
as_operations_add_incr(&ops, "bin1", 123);
as_operations_add_append_str(&ops, "bin2", "abc");

Use as_operations_destroy() to free the resources allocated to the as_operations.

Parameters

ops	The `as_operations` to initialize.
nops	The number of `as_operations.binops.entries` to allocate on the heap.

Returns: The initialized as_operations on success. Otherwise NULL.

#define as_operations_inita	(	__ops,
		__nops
	)

(__ops)->binops.entries = (as_binop*) alloca(sizeof(as_binop) * (__nops));\
    (__ops)->binops.capacity = (__nops);\
    (__ops)->binops.size = 0;\
    (__ops)->binops._free = false;\
    (__ops)->ttl = 0;\
    (__ops)->gen = 0;\
    (__ops)->_free = false;

Initializes a stack allocated as_operations (as_operations) and allocates __nops number of entries on the stack.

as_operations ops;
as_operations_inita(&ops, 2);
as_operations_add_incr(&ops, "bin1", 123);
as_operations_add_append_str(&ops, "bin2", "abc");

Parameters

__ops	The `as_operations *` to initialize.
__nops	The number of `as_binops.entries` to allocate on the stack.

Definition at line 309 of file as_operations.h.

AS_EXTERN as_operations * as_operations_new ( uint16_t nops )

as_operations ops = as_operations_new(2);
as_operations_add_incr(ops, "bin1", 123);
as_operations_add_append_str(ops, "bin2", "abc");

Use as_operations_destroy() to free the resources allocated to the as_operations.

Parameters

nops	The number of `as_operations.binops.entries` to allocate on the heap.

Returns: The new as_operations on success. Otherwise NULL.

Field Documentation

as_binops as_operations::binops

Operations to be performed on the bins of a record.

Definition at line 259 of file as_operations.h.

uint16_t as_operations::gen

The generation of the record.

Definition at line 277 of file as_operations.h.

uint32_t as_operations::ttl

The time-to-live (expiration) of the record in seconds.

There are also special values that can be set in the record ttl:

AS_RECORD_DEFAULT_TTL: Use the server default ttl from the namespace.
AS_RECORD_NO_EXPIRE_TTL: Do not expire the record.
AS_RECORD_NO_CHANGE_TTL: Keep the existing record ttl when the record is updated.
AS_RECORD_CLIENT_DEFAULT_TTL: Use the default client ttl in as_policy_operate.

Definition at line 272 of file as_operations.h.

The documentation for this struct was generated from the following files:

Detailed Description

Initialization

Destruction

Usage

Modifying a String

Modifying a Byte Array

Increment an Integer

Write a Value

Read a Value

Touch a Record

Data Fields

Related Functions

Friends And Related Function Documentation

Field Documentation