Key Operations

Description

Aerospike provides a key based API to access and modify data into the cluster.

The Key API is a collection of APIs that use as_key as for looking up records for accessing and modifying in the cluster.

Collaboration diagram for Key Operations:

Functions
AS_EXTERN as_status	aerospike_key_apply (aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const char *module, const char *function, as_list *arglist, as_val **result)
AS_EXTERN as_status	aerospike_key_apply_async (aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const char *module, const char *function, as_list *arglist, as_async_value_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_exists (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_record **rec)
AS_EXTERN as_status	aerospike_key_exists_async (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_async_record_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_get (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_record **rec)
AS_EXTERN as_status	aerospike_key_get_async (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_async_record_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_operate (aerospike *as, as_error *err, const as_policy_operate *policy, const as_key *key, const as_operations *ops, as_record **rec)
AS_EXTERN as_status	aerospike_key_operate_async (aerospike *as, as_error *err, const as_policy_operate *policy, const as_key *key, const as_operations *ops, as_async_record_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_put (aerospike *as, as_error *err, const as_policy_write *policy, const as_key *key, as_record *rec)
AS_EXTERN as_status	aerospike_key_put_async (aerospike *as, as_error *err, const as_policy_write *policy, const as_key *key, as_record *rec, as_async_write_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_remove (aerospike *as, as_error *err, const as_policy_remove *policy, const as_key *key)
AS_EXTERN as_status	aerospike_key_remove_async (aerospike *as, as_error *err, const as_policy_remove *policy, const as_key *key, as_async_write_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)
AS_EXTERN as_status	aerospike_key_select (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, const char *bins[], as_record **rec)
AS_EXTERN as_status	aerospike_key_select_async (aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, const char *bins[], as_async_record_listener listener, void *udata, as_event_loop *event_loop, as_pipe_listener pipe_listener)

Function Documentation

AS_EXTERN as_status aerospike_key_apply	(	aerospike *	as,
		as_error *	err,
		const as_policy_apply *	policy,
		const as_key *	key,
		const char *	module,
		const char *	function,
		as_list *	arglist,
		as_val **	result
	)

Lookup a record by key, then apply the UDF.

as_key key;
as_key_init(&key, "ns", "set", "key");

as_arraylist args;
as_arraylist_inita(&args, 2);
as_arraylist_append_int64(&args, 1);
as_arraylist_append_int64(&args, 2);

as_val * res = NULL;

if (aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK) {
    printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
else {
       as_val_destroy(res);
}

as_arraylist_destroy(&args);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
module	The module containing the function to execute.
function	The function to execute.
arglist	The arguments for the function.
result	The return value from the function.

Returns

AEROSPIKE_OK if successful. Otherwise an error.

AS_EXTERN as_status aerospike_key_apply_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_apply *	policy,
		const as_key *	key,
		const char *	module,
		const char *	function,
		as_list *	arglist,
		as_async_value_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously lookup a record by key, then apply the UDF.

void my_listener(as_error* err, as_val* val, void* udata, as_event_loop* event_loop)
{
       if (err) {
           printf("Command failed: %d %s\n", err->code, err->message);
           return;
        }
        // Process value.  The calling function will call as_val_destroy().
        // If the value needs to be preserved, bump up the reference count using as_val_reserve()
        // and call as_val_destroy() when done with the value.
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_arraylist args;
as_arraylist_inita(&args, 2);
as_arraylist_append_int64(&args, 1);
as_arraylist_append_int64(&args, 2);

as_status status = aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, my_listener, NULL, NULL, NULL);
as_arraylist_destroy(&args);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
module	The module containing the function to execute.
function	The function to execute.
arglist	The arguments for the function.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

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

Check if a record exists in the cluster via its key. The record's metadata will be populated if the record exists.

as_key key;
as_key_init(&key, "ns", "set", "key");

as_record* rec = NULL;
if (aerospike_key_exists(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
    printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
else {
       if (rec) {
           printf("Record exists.");
           as_record_destroy(rec);
    }
       else {
           printf("Record doesn't exist.");
       }
}

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
rec	The metadata will be populated if the record exists. If the record pointer is preset to NULL, the record will be created and initialized. If the record pointer is not NULL, the record is assumed to be valid and will be reused. Either way, the record must be preset.

Returns

AEROSPIKE_OK if successful. AEROSPIKE_ERR_RECORD_NOT_FOUND if not found. Otherwise an error.

AS_EXTERN as_status aerospike_key_exists_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_read *	policy,
		const as_key *	key,
		as_async_record_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously check if a record exists in the cluster via its key. The record's metadata will be populated if the record exists.

void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
{
       if (err) {
           printf("Command failed: %d %s\n", err->code, err->message);
           return;
       }
       if (record) {
           printf("Record exists.");
           // Only call as_record_destroy(record) when the record exists, the command is successful 
        // (err == NULL) and "as_policy_read.async_heap_rec" is true. Otherwise, the calling
        // function will destroy the record when the listener completes.
       }
       else {
           printf("Record doesn't exist.");
       }
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_status status = aerospike_key_exists_async(&as, &err, NULL, &key, my_listener, NULL, NULL, NULL);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

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

Look up a record by key and return all bins.

as_key key;
as_key_init(&key, "ns", "set", "key");

as_record* rec = NULL;
if (aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
    printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
else {
       as_record_destroy(rec);
}

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
rec	The record to be populated with the data from request. If the record pointer is preset to NULL, the record will be created and initialized. If the record pointer is not NULL, the record is assumed to be valid and will be reused. Either way, the record must be preset.

Returns

AEROSPIKE_OK if successful. Otherwise an error.

AS_EXTERN as_status aerospike_key_get_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_read *	policy,
		const as_key *	key,
		as_async_record_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously look up a record by key and return all bins.

void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
{
    if (err) {
        printf("Command failed: %d %s\n", err->code, err->message);
        return;
       }
       // Process record bins
       // Only call as_record_destroy(record) when command is successful (err == NULL) and 
    // "as_policy_read.async_heap_rec" is true. Otherwise, the calling function will destroy the
    // record when the listener completes.
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_status status = aerospike_key_get_async(&as, &err, NULL, &key, my_listener, NULL, NULL, NULL);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

AS_EXTERN as_status aerospike_key_operate	(	aerospike *	as,
		as_error *	err,
		const as_policy_operate *	policy,
		const as_key *	key,
		const as_operations *	ops,
		as_record **	rec
	)

Lookup a record by key, then perform specified operations.

as_key key;
as_key_init(&key, "ns", "set", "key");

as_operations ops;
as_operations_inita(&ops,3);
as_operations_add_incr(&ops, "bin1", 456);
as_operations_add_append_str(&ops, "bin2", "def");
as_operations_add_read(&ops, "bin1")

as_record* rec = NULL;

if (aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK) {
       printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
else {
       as_record_destroy(rec);
}
as_operations_destroy(&ops);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
ops	The operations to perform on the record.
rec	The record to be populated with the data from AS_OPERATOR_READ operations.

Returns

AEROSPIKE_OK if successful. Otherwise an error.

AS_EXTERN as_status aerospike_key_operate_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_operate *	policy,
		const as_key *	key,
		const as_operations *	ops,
		as_async_record_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously lookup a record by key, then perform specified operations.

void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
{
       if (err) {
       printf("Command failed: %d %s\n", err->code, err->message);
          return;
       }
       // Process record bins
       // Only call as_record_destroy(record) when command is successful (err == NULL) and
    // "as_policy_operate.async_heap_rec" is true. Otherwise, the calling function will destroy
    // the record when the listener completes.
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_operations ops;
as_operations_inita(&ops,3);
as_operations_add_incr(&ops, "bin1", 456);
as_operations_add_append_str(&ops, "bin2", "def");
as_operations_add_read(&ops, "bin1")

as_status status = aerospike_key_operate(&as, &err, NULL, &key, &ops, my_listener, NULL, NULL, NULL);
as_operations_destroy(&ops);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
ops	The operations to perform on the record.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

AS_EXTERN as_status aerospike_key_put	(	aerospike *	as,
		as_error *	err,
		const as_policy_write *	policy,
		const as_key *	key,
		as_record *	rec
	)

Store a record in the cluster.

as_key key;
as_key_init(&key, "ns", "set", "key");

as_record rec;
as_record_init(&rec, 2);
as_record_set_str(&rec, "bin1", "abc");
as_record_set_int64(&rec, "bin2", 123);

if (aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
       printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
as_record_destroy(&rec);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
rec	The record containing the data to be written.

Returns

AEROSPIKE_OK if successful. Otherwise an error.

AS_EXTERN as_status aerospike_key_put_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_write *	policy,
		const as_key *	key,
		as_record *	rec,
		as_async_write_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously store a record in the cluster.

void my_listener(as_error* err, void* udata, as_event_loop* event_loop)
{
       if (err) {
           printf("Command failed: %d %s\n", err->code, err->message);
           return;
       }
       printf("Command succeeded\n");
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_record rec;
as_record_init(&rec, 2);
as_record_set_str(&rec, "bin1", "abc");
as_record_set_int64(&rec, "bin2", 123);

as_status status = aerospike_key_put_async(&as, &err, NULL, &key, &rec, my_listener, NULL, NULL, NULL);
as_record_destroy(&rec);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
rec	The record containing the data to be written.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

AS_EXTERN as_status aerospike_key_remove	(	aerospike *	as,
		as_error *	err,
		const as_policy_remove *	policy,
		const as_key *	key
	)

Remove a record from the cluster.

as_key key;
as_key_init(&key, "ns", "set", "key");

if (aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK) {
       printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.

Returns

AEROSPIKE_OK if successful and AEROSPIKE_ERR_RECORD_NOT_FOUND if the record was not found. Otherwise an error.

AS_EXTERN as_status aerospike_key_remove_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_remove *	policy,
		const as_key *	key,
		as_async_write_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously remove a record from the cluster.

void my_listener(as_error* err, void* udata, as_event_loop* event_loop)
{
       if (err) {
           printf("Command failed: %d %s\n", err->code, err->message);
           return;
       }
       printf("Command succeeded\n");
}

as_key key;
as_key_init(&key, "ns", "set", "key");

as_status status = aerospike_key_remove(&as, &err, NULL, &key, my_listener, NULL, NULL, NULL);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.

AS_EXTERN as_status aerospike_key_select	(	aerospike *	as,
		as_error *	err,
		const as_policy_read *	policy,
		const as_key *	key,
		const char *	bins[],
		as_record **	rec
	)

Lookup a record by key, then return specified bins.

char* select[] = {"bin1", "bin2", "bin3", NULL};

as_key key;
as_key_init(&key, "ns", "set", "key");

as_record* rec = NULL;
if (aerospike_key_select(&as, &err, NULL, &key, select, &rec) != AEROSPIKE_OK) {
       printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
else {
    as_record_destroy(rec);
}

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
bins	The bins to select. A NULL terminated array of NULL terminated strings.
rec	The record to be populated with the data from request. If the record pointer is preset to NULL, the record will be created and initialized. If the record pointer is not NULL, the record is assumed to be valid and will be reused. Either way, the record must be preset.

Returns

AEROSPIKE_OK if successful. Otherwise an error.

AS_EXTERN as_status aerospike_key_select_async	(	aerospike *	as,
		as_error *	err,
		const as_policy_read *	policy,
		const as_key *	key,
		const char *	bins[],
		as_async_record_listener	listener,
		void *	udata,
		as_event_loop *	event_loop,
		as_pipe_listener	pipe_listener
	)

Asynchronously lookup a record by key, then return specified bins.

void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
{
    if (err) {
           printf("Command failed: %d %s\n", err->code, err->message);
           return;
       }
       // Process record bins
       // Only call as_record_destroy(record) when command is successful (err == NULL) and 
    // "as_policy_read.async_heap_rec" is true. Otherwise, the calling function will destroy the
    // record when the listener completes.
}

char* select[] = {"bin1", "bin2", "bin3", NULL};

as_key key;
as_key_init(&key, "ns", "set", "key");

as_status status = aerospike_key_select_async(&as, &err, NULL, &key, select, my_listener, NULL, NULL, NULL);

Parameters

as	The aerospike instance to use for this operation.
err	The as_error to be populated if an error occurs.
policy	The policy to use for this operation. If NULL, then the default policy will be used.
key	The key of the record.
bins	The bins to select. A NULL terminated array of NULL terminated strings.
listener	User function to be called with command results.
udata	User data to be forwarded to user callback.
event_loop	Event loop assigned to run this command. If NULL, an event loop will be chosen by round-robin.
pipe_listener	Enables command pipelining, if not NULL. The given callback is invoked after the current command has been sent to the server. This allows for issuing the next command even before receiving a result for the current command.

Returns

AEROSPIKE_OK if async command successfully queued. Otherwise an error.