All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Typedefs | Functions
Batch Operations

Description

Aerospike provides a batch API to access data in the cluster.

The Batch API is a collection of APIs that use as_keyset as for looking up records for accessing in the cluster.

+ Collaboration diagram for Batch Operations:

Typedefs

typedef bool(* aerospike_batch_read_callback )(const as_batch_read *results, uint32_t n, void *udata)
 
typedef void(* as_async_batch_listener )(as_error *err, as_batch_read_records *records, void *udata, as_event_loop *event_loop)
 

Functions

as_status aerospike_batch_exists (aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, aerospike_batch_read_callback callback, void *udata)
 
as_status aerospike_batch_get (aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, aerospike_batch_read_callback callback, void *udata)
 
as_status aerospike_batch_get_bins (aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, const char **bins, uint32_t n_bins, aerospike_batch_read_callback callback, void *udata)
 
as_status aerospike_batch_read (aerospike *as, as_error *err, const as_policy_batch *policy, as_batch_read_records *records)
 
as_status aerospike_batch_read_async (aerospike *as, as_error *err, const as_policy_batch *policy, as_batch_read_records *records, as_async_batch_listener listener, void *udata, as_event_loop *event_loop)
 
static as_batch_read_recordsas_batch_read_create (uint32_t capacity)
 
void as_batch_read_destroy (as_batch_read_records *records)
 
static void as_batch_read_init (as_batch_read_records *records, uint32_t capacity)
 
static as_batch_read_recordas_batch_read_reserve (as_batch_read_records *records)
 

Typedef Documentation

typedef bool(* aerospike_batch_read_callback)(const as_batch_read *results, uint32_t n, void *udata)

This callback will be called with the results of aerospike_batch_get(), or aerospike_batch_exists() functions.

The results argument will be an array of n as_batch_read entries. The results argument is on the stack and is only available within the context of the callback. To use the data outside of the callback, copy the data.

bool my_callback(const as_batch_read * results, uint32_t n, void * udata) {
return true;
}
Parameters
resultsThe results from the batch request.
nThe number of results from the batch request.
udataUser-data provided to the calling function.
Returns
true on success. Otherwise, an error occurred.

Definition at line 135 of file aerospike_batch.h.

typedef void(* as_async_batch_listener)(as_error *err, as_batch_read_records *records, void *udata, as_event_loop *event_loop)

Asynchronous batch user callback. This function is called once when the batch completes or an error has occurred.

Parameters
errThis error structure is only populated when the command fails. Null on success.
recordsReturned records. Records must be destroyed with as_batch_read_destroy() when done.
udataUser data that is forwarded from asynchronous command function.
event_loopEvent loop that this command was executed on. Use this event loop when running nested asynchronous commands when single threaded behavior is desired for the group of commands.

Definition at line 157 of file aerospike_batch.h.

Function Documentation

as_status aerospike_batch_exists ( aerospike as,
as_error err,
const as_policy_batch policy,
const as_batch batch,
aerospike_batch_read_callback  callback,
void *  udata 
)

Test whether multiple records exist in the cluster.

as_batch batch;
as_batch_inita(&batch, 3);
as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
if ( aerospike_batch_exists(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe policy to use for this operation. If NULL, then the default policy will be used.
batchThe batch of keys to read.
callbackThe callback to invoke for each record read.
udataThe user-data for the callback.
Returns
AEROSPIKE_OK if successful. Otherwise an error.
as_status aerospike_batch_get ( aerospike as,
as_error err,
const as_policy_batch policy,
const as_batch batch,
aerospike_batch_read_callback  callback,
void *  udata 
)

Look up multiple records by key, then return all bins.

as_batch batch;
as_batch_inita(&batch, 3);
as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
if ( aerospike_batch_get(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe policy to use for this operation. If NULL, then the default policy will be used.
batchThe batch of keys to read.
callbackThe callback to invoke for each record read.
udataThe user-data for the callback.
Returns
AEROSPIKE_OK if successful. Otherwise an error.
as_status aerospike_batch_get_bins ( aerospike as,
as_error err,
const as_policy_batch policy,
const as_batch batch,
const char **  bins,
uint32_t  n_bins,
aerospike_batch_read_callback  callback,
void *  udata 
)

Look up multiple records by key, then return specified bins.

as_batch batch;
as_batch_inita(&batch, 3);
as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
const char* bin_filters[] = {"bin1", "bin2"};
if ( aerospike_batch_get_bins(&as, &err, NULL, &batch, bin_filters, 2, callback, NULL) != AEROSPIKE_OK ) {
fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe policy to use for this operation. If NULL, then the default policy will be used.
batchThe batch of keys to read.
binsBin filters. Only return these bins.
n_binsThe number of bin filters.
callbackThe callback to invoke for each record read.
udataThe user-data for the callback.
Returns
AEROSPIKE_OK if successful. Otherwise an error.
as_status aerospike_batch_read ( aerospike as,
as_error err,
const as_policy_batch policy,
as_batch_read_records records 
)

Read multiple records for specified batch keys in one batch call. This method allows different namespaces/bins to be requested for each key in the batch. The returned records are located in the same batch array. This method requires Aerospike Server version >= 3.6.0.

as_batch_read_inita(&records, 10);
char* bin_names[] = {"bin1", "bin2"};
char* ns = "ns";
char* set = "set";
as_key_init(&record->key, ns, set, "key1");
record->bin_names = bin_names;
record->n_bin_names = 2;
record = as_batch_read_reserve(&records);
as_key_init(&record->key, ns, set, "key2");
record->read_all_bins = true;
if (aerospike_batch_read(&as, &err, NULL, &records) != AEROSPIKE_OK) {
fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}
Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe policy to use for this operation. If NULL, then the default policy will be used.
recordsList of keys and bins to retrieve. The returned records are located in the same array.
Returns
AEROSPIKE_OK if successful. Otherwise an error.
as_status aerospike_batch_read_async ( aerospike as,
as_error err,
const as_policy_batch policy,
as_batch_read_records records,
as_async_batch_listener  listener,
void *  udata,
as_event_loop event_loop 
)

Asynchronously read multiple records for specified batch keys in one batch call. This method allows different namespaces/bins to be requested for each key in the batch. The returned records are located in the same batch array. This method requires Aerospike Server version >= 3.6.0.

void my_listener(as_error* err, as_batch_read_records* records, void* udata, as_event_loop* event_loop)
{
if (err) {
fprintf(stderr, "Command failed: %d %s\n", err->code, err->message);
}
else {
as_vector* list = &records->list;
for (uint32_t i = 0; i < list->size; i++) {
as_batch_read_record* record = as_vector_get(list, i);
// Process record
}
}
// Must free batch records on both success and error conditions because it was created
// before calling aerospike_batch_read_async().
}
// bin_names can be placed on stack because it's only referenced before being queued on event loop.
char* bin_names[] = {"bin1", "bin2"};
char* ns = "ns";
char* set = "set";
as_key_init(&record->key, ns, set, "key1");
record->bin_names = bin_names;
record->n_bin_names = 2;
record = as_batch_read_reserve(records);
as_key_init(&record->key, ns, set, "key2");
record->read_all_bins = true;
as_status status = aerospike_batch_read_async(&as, &err, NULL, records, NULL, my_listener, NULL);
if (status != AEROSPIKE_OK) {
// Must free batch records on queue error because the callback will not be called.
}
Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe policy to use for this operation. If NULL, then the default policy will be used.
recordsList of keys and bins to retrieve. The returned records are located in the same array. Must create using as_batch_read_create() (which allocates memory on heap) because async method will return immediately after queueing command.
listenerUser function to be called with command results.
udataUser data to be forwarded to user callback.
event_loopEvent loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
Returns
AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
static as_batch_read_records * as_batch_read_create ( uint32_t  capacity)
related

Create as_batch_read_records on heap with specified list capacity on the heap.

When the batch is no longer needed, then use as_batch_destroy() to release the batch and associated resources.

Parameters
capacityInitial capacity of batch record list. List will resize when necessary.
Returns
Batch record list.

Definition at line 209 of file aerospike_batch.h.

References as_vector_create().

void as_batch_read_destroy ( as_batch_read_records records)
related

Destroy keys and records in record list. It's the responsility of the caller to free as_batch_read_record.bin_names when necessary.

Parameters
recordsBatch record list.
static void as_batch_read_init ( as_batch_read_records records,
uint32_t  capacity 
)
related

Initialize as_batch_read_records with specified capacity on the heap.

When the batch is no longer needed, then use as_batch_destroy() to release the batch and associated resources.

Parameters
recordsBatch record list.
capacityInitial capacity of batch record list. List will resize when necessary.

Definition at line 191 of file aerospike_batch.h.

References as_vector_init(), and as_batch_read_records::list.

static as_batch_read_record * as_batch_read_reserve ( as_batch_read_records records)
related

Reserve a new as_batch_read_record slot. Capacity will be increased when necessary. Return reference to record. The record is already initialized to zeroes.

Parameters
recordsBatch record list.

Definition at line 224 of file aerospike_batch.h.

References as_vector_reserve(), and as_batch_read_records::list.