All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Typedefs | Functions
Query Operations (3.0 only)

Description

The Aerospike Query Operations provide the ability to query data in the Aerospike database. The queries can only be performed on secondary indexes, which have been created in the database. To scan all the records in the database, then you must use the Scan Operations.

Usage

Before you can execute a query, you first need to build a query using as_query. See as_query for details on building queries.

Once you have a query defined, then you can execute the query :

When aerospike_query_foreach() is executed, it will process the results and create records on the stack. Because the records are on the stack, they will only be available within the context of the callback function.

Walk-through

First, we define a query using as_query. The query will be for the "test" namespace and "demo" set. We will add a where predicate on "bin2", on which we have already created a secondary index.

as_query query;
as_query_init(&query, "test", "demo");
as_query_where(&query, "bin2", as_integer_equals(100));

Now that we have a query defined, we want to execute it using aerospike_query_foreach().

if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}

The callback provided to the function above is implemented as:

bool callback(const as_val * val, void * udata) {
if ( !rec ) return false;
fprintf("record contains %d bins", as_record_numbins(rec));
return true;
}

An as_query is simply a query definition, so it does not contain any state, allowing it to be reused for multiple query operations.

When you are finished with the query, you should destroy the resources allocated to it:

+ Collaboration diagram for Query Operations (3.0 only):

Typedefs

typedef bool(* aerospike_query_foreach_callback )(const as_val *val, void *udata)
 

Functions

as_status aerospike_query_background (aerospike *as, as_error *err, const as_policy_write *policy, const as_query *query, uint64_t *query_id)
 
as_status aerospike_query_foreach (aerospike *as, as_error *err, const as_policy_query *policy, const as_query *query, aerospike_query_foreach_callback callback, void *udata)
 
static as_status aerospike_query_info (aerospike *as, as_error *err, const as_policy_info *policy, const as_query *query, uint64_t query_id, as_job_info *info)
 
static as_status aerospike_query_wait (aerospike *as, as_error *err, const as_policy_info *policy, const as_query *query, uint64_t query_id, uint32_t interval_ms)
 

Typedef Documentation

typedef bool(* aerospike_query_foreach_callback)(const as_val *val, void *udata)

This callback will be called for each value or record returned from a query. Multiple threads will likely be calling this callback in parallel. Therefore, your callback implementation should be thread safe.

The aerospike_query_foreach() function accepts this callback.

bool my_callback(as_val * val, void * udata) {
return true;
}
Parameters
valThe value received from the query.
udataUser-data provided to the calling function.
Returns
true to continue to the next value. Otherwise, iteration will end.

Definition at line 125 of file aerospike_query.h.

Function Documentation

as_status aerospike_query_background ( aerospike as,
as_error err,
const as_policy_write policy,
const as_query query,
uint64_t *  query_id 
)

Apply user defined function on records that match the query filter. Records are not returned to the client. This asynchronous server call will return before command is complete. The user can optionally wait for command completion.

as_query query;
as_query_init(&query, "test", "demo");
as_query_select(&query, "bin1");
as_query_where(&query, "bin2", as_integer_equals(100));
as_query_apply(&query, "my_lua.lua", "my_lua_function", NULL);
uint64_t query_id = 0;
if (aerospike_query_background(&as, &err, NULL, &query, &query_id) == AEROSPIKE_OK) {
aerospike_query_wait(as, &err, NULL, &query, query_id, 0);
}
else {
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.
queryThe query to execute against the cluster.
query_idThe id for the query job, which can be used for querying the status of the query.
Returns
AEROSPIKE_OK on success, otherwise an error.
as_status aerospike_query_foreach ( aerospike as,
as_error err,
const as_policy_query policy,
const as_query query,
aerospike_query_foreach_callback  callback,
void *  udata 
)

Execute a query and call the callback function for each result item. Multiple threads will likely be calling the callback in parallel. Therefore, your callback implementation should be thread safe.

as_query query;
as_query_init(&query, "test", "demo");
as_query_select(&query, "bin1");
as_query_where(&query, "bin2", as_integer_equals(100));
if ( aerospike_query_foreach(&as, &err, NULL, &query, 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.
queryThe query to execute against the cluster.
callbackThe callback function to call for each result value.
udataUser-data to be passed to the callback.
Returns
AEROSPIKE_OK on success, otherwise an error.
static as_status aerospike_query_info ( aerospike as,
as_error err,
const as_policy_info policy,
const as_query query,
uint64_t  query_id,
as_job_info info 
)
inlinestatic

Check the progress of a background query running on the database.

Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe info policy to use for this operation. If NULL, then the default policy will be used.
queryThe query that was executed against the cluster.
query_idThe id for the query job, which can be used for querying the status of the query.
infoInformation about this background query, to be populated by this operation.
Returns
AEROSPIKE_OK on success, otherwise an error.

Definition at line 246 of file aerospike_query.h.

References aerospike_job_info(), as_query_predicates::size, and as_query::where.

static as_status aerospike_query_wait ( aerospike as,
as_error err,
const as_policy_info policy,
const as_query query,
uint64_t  query_id,
uint32_t  interval_ms 
)
inlinestatic

Wait for a background query to be completed by servers.

Parameters
asThe aerospike instance to use for this operation.
errThe as_error to be populated if an error occurs.
policyThe info policy to use for this operation. If NULL, then the default policy will be used.
queryThe query that was executed against the cluster.
query_idThe id for the query job, which can be used for querying the status of the query.
interval_msPolling interval in milliseconds. If zero, 1000 ms is used.
Returns
AEROSPIKE_OK on success, otherwise an error.

Definition at line 222 of file aerospike_query.h.

References aerospike_job_wait(), as_query_predicates::size, and as_query::where.