All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Data Fields | Private Attributes | Related Functions
as_query Struct Reference

Detailed Description

The as_query object is used define a query to be executed in the datasbase.

Initialization

Before using an as_query, it must be initialized via either:

as_query_init() should be used on a stack allocated as_query. It will initialize the as_query with the given namespace and set. On success, it will return a pointer to the initialized as_query. Otherwise, NULL is returned.

as_query query;
as_query_init(&query, "namespace", "set");

as_query_new() should be used to allocate and initialize a heap allocated as_query. It will allocate the as_query, then initialized it with the given namespace and set. On success, it will return a pointer to the initialized as_query. Otherwise, NULL is returned.

as_query * query = as_query_new("namespace", "set");

Destruction

When you are finished with the as_query, you can destroy it and associated resources:

Usage

The following explains how to use an as_query to build a query.

Selecting Bins

as_query_select() is used to specify the bins to be selected by the query.

as_query_select(query, "bin1");
as_query_select(query, "bin2");

Before adding bins to select, the select structure must be initialized via either:

Both functions are given the number of bins to be selected.

A complete example using as_query_select_inita()

as_query_select(query, "bin1");
as_query_select(query, "bin2");

Predicates on Bins

as_query_where() is used to specify predicates to be added to the the query.

Note: Currently, a single where predicate is supported. To do more advanced filtering, you will want to use a UDF to process the result set on the server.

as_query_where(query, "bin1", as_string_equals("abc"));

The predicates that you can apply to a bin include:

Before adding predicates, the where structure must be initialized. To initialize the where structure, you can choose to use one of the following:

Both functions are given the number of predicates to be added.

A complete example using as_query_where_inita():

as_query_where(query, "bin1", as_string_equals("abc"));

Sorting Results

as_query_orderby() is used to specify ordering of results of a query.

The sort order can be:

Before adding ordering, the orderby structure must be initialized via either:

Both functions are given the number of orderings to be added.

A complete example using as_query_orderby_inita():

Applying a UDF to Query Results

A UDF can be applied to the results of a query.

To define the UDF for the query, use as_query_apply().

as_query_apply(query, "udf_module", "udf_function", arglist);

Definition at line 505 of file as_query.h.

#include "as_query.h"

+ Collaboration diagram for as_query:

Data Fields

as_udf_call apply
 
as_namespace ns
 
as_query_ordering orderby
 
as_query_predexp predexp
 
as_query_bins select
 
as_set set
 
as_query_predicates where
 

Private Attributes

bool _free
 

Related Functions

(Note that these are not member functions.)

#define as_contains(indextype, datatype, __val)   AS_PREDICATE_EQUAL, AS_INDEX_TYPE_ ##indextype, AS_INDEX_ ##datatype, __val
 
#define as_equals(datatype, __val)   AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_ ##datatype, __val
 
#define as_integer_equals(__val)   AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC, (int64_t)__val
 
#define as_integer_range(__min, __max)   AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC, (int64_t)__min, (int64_t)__max
 
bool as_query_apply (as_query *query, const char *module, const char *function, const as_list *arglist)
 
void as_query_destroy (as_query *query)
 
as_queryas_query_init (as_query *query, const as_namespace ns, const as_set set)
 
as_queryas_query_new (const as_namespace ns, const as_set set)
 
bool as_query_orderby (as_query *query, const char *bin, as_order order)
 
bool as_query_orderby_init (as_query *query, uint16_t n)
 
#define as_query_orderby_inita(__query, __n)
 
bool as_query_predexp_add (as_query *query, as_predexp_base *predexp)
 
bool as_query_predexp_init (as_query *query, uint16_t n)
 
#define as_query_predexp_inita(__query, __n)
 
bool as_query_select (as_query *query, const char *bin)
 
bool as_query_select_init (as_query *query, uint16_t n)
 
#define as_query_select_inita(__query, __n)
 
bool as_query_where (as_query *query, const char *bin, as_predicate_type type, as_index_type itype, as_index_datatype dtype,...)
 
bool as_query_where_init (as_query *query, uint16_t n)
 
#define as_query_where_inita(__query, __n)
 
#define as_range(indextype, datatype, __min, __max)   AS_PREDICATE_RANGE, AS_INDEX_TYPE_ ##indextype, AS_INDEX_ ##datatype, __min, __max
 
#define as_string_equals(__val)   AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_STRING, __val
 

Friends And Related Function Documentation

#define as_contains (   indextype,
  datatype,
  __val 
)    AS_PREDICATE_EQUAL, AS_INDEX_TYPE_ ##indextype, AS_INDEX_ ##datatype, __val
related

Macro for setting setting the CONTAINS predicate.

as_query_where(query, "bin1", as_contains(LIST,STRING,"val"));

Definition at line 93 of file as_query.h.

#define as_equals (   datatype,
  __val 
)    AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_ ##datatype, __val
related

Macro for setting setting the EQUALS predicate.

as_query_where(query, "bin1", as_equals(NUMERIC,5));

Definition at line 105 of file as_query.h.

#define as_integer_equals (   __val)    AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC, (int64_t)__val
related

Macro for setting setting the INTEGER_EQUAL predicate.

as_query_where(query, "bin1", as_integer_equals(123));

Definition at line 57 of file as_query.h.

#define as_integer_range (   __min,
  __max 
)    AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC, (int64_t)__min, (int64_t)__max
related

Macro for setting setting the INTEGER_RANGE predicate.

as_query_where(query, "bin1", as_integer_range(1,100));

Definition at line 69 of file as_query.h.

bool as_query_apply ( as_query query,
const char *  module,
const char *  function,
const as_list arglist 
)
related

Apply a function to the results of the query.

as_query_apply(&query, "my_module", "my_function", NULL);
Parameters
queryThe query to apply the function to.
moduleThe module containing the function to invoke.
functionThe function in the module to invoke.
arglistThe arguments to use when calling the function.
Returns
On success, true. Otherwise an error occurred.
void as_query_destroy ( as_query query)
related

Destroy the query and associated resources.

Parameters
queryThe query to destroy.
as_query * as_query_init ( as_query query,
const as_namespace  ns,
const as_set  set 
)
related

Initialize a stack allocated as_query.

as_query query;
as_query_init(&query, "test", "demo");
Parameters
queryThe query to initialize.
nsThe namespace to query.
setThe set to query.
Returns
On success, the initialized query. Otherwise NULL.
as_query * as_query_new ( const as_namespace  ns,
const as_set  set 
)
related

Create and initialize a new heap allocated as_query.

as_query * query = as_query_new("test", "demo");
Parameters
nsThe namespace to query.
setThe set to query.
Returns
On success, the new query. Otherwise NULL.
bool as_query_orderby ( as_query query,
const char *  bin,
as_order  order 
)
related

Add a bin to sort by to the query.

You have to ensure as_query.orderby has sufficient capacity, prior to adding an ordering. If capacity is insufficient then false is returned.

Parameters
queryThe query to modify.
binThe name of the bin to sort by.
orderThe sort order: AS_ORDER_ASCENDING or AS_ORDER_DESCENDING.
Returns
On success, true. Otherwise an error occurred.
bool as_query_orderby_init ( as_query query,
uint16_t  n 
)
related

Initializes as_query.orderby with a capacity of n using malloc().

For stack allocation, use as_query_orderby_inita().

Parameters
queryThe query to initialize.
nThe number of as_orders to allocate.
Returns
On success, true. Otherwise an error occurred.
#define as_query_orderby_inita (   __query,
  __n 
)
related
Value:
do { \
if ( (__query) != NULL && (__query)->orderby.entries == NULL ) {\
(__query)->orderby.entries = (as_ordering*) alloca(sizeof(as_ordering) * (__n));\
if ( (__query)->orderby.entries ) { \
(__query)->orderby._free = false;\
(__query)->orderby.capacity = (__n);\
(__query)->orderby.size = 0;\
}\
} \
} while(0)

Initializes as_query.where with a capacity of n using alloca().

For heap allocation, use as_query_where_init().

Parameters
__queryThe query to initialize.
__nThe number of as_orders to allocate.
Returns
On success, true. Otherwise an error occurred.

Definition at line 898 of file as_query.h.

bool as_query_predexp_add ( as_query query,
as_predexp_base predexp 
)
related

Adds predicate expressions to a query.

You have to ensure as_query.predexp has sufficient capacity, prior to adding a predexp. If capacity is sufficient then false is returned.

Parameters
queryThe query to modify.
predexpPointer to a constructed predicate expression.
Returns
On success, true. Otherwise an error occurred.
bool as_query_predexp_init ( as_query query,
uint16_t  n 
)
related

Initializes as_query.predexp with a capacity of n using malloc().

For stack allocation, use as_query_predexp_inita().

Parameters
queryThe query to initialize.
nThe number of predicate expression slots to allocate.
Returns
On success, the initialized. Otherwise an error occurred.
#define as_query_predexp_inita (   __query,
  __n 
)
related
Value:
if ( (__query) != NULL && (__query)->predexp.entries == NULL ) { \
(__query)->predexp.entries = \
alloca(__n * sizeof(as_predexp_base *)); \
if ( (__query)->predexp.entries ) { \
(__query)->predexp._free = false; \
(__query)->predexp.capacity = __n; \
(__query)->predexp.size = 0; \
} \
}

Initializes as_query.predexp with a capacity of n using alloca

For heap allocation, use as_query_predexp_init().

Parameters
__queryThe query to initialize.
__nThe number of predicate expression slots to allocate.

Definition at line 820 of file as_query.h.

bool as_query_select ( as_query query,
const char *  bin 
)
related

Select bins to be projected from matching records.

You have to ensure as_query.select has sufficient capacity, prior to adding a bin. If capacity is sufficient then false is returned.

as_query_select(&query, "bin1");
as_query_select(&query, "bin2");
Parameters
queryThe query to modify.
binThe name of the bin to select.
Returns
On success, true. Otherwise an error occurred.
bool as_query_select_init ( as_query query,
uint16_t  n 
)
related

Initializes as_query.select with a capacity of n using malloc().

For stack allocation, use as_query_select_inita().

as_query_select(&query, "bin1");
as_query_select(&query, "bin2");
Parameters
queryThe query to initialize.
nThe number of bins to allocate.
Returns
On success, the initialized. Otherwise an error occurred.
#define as_query_select_inita (   __query,
  __n 
)
related
Value:
do { \
if ( (__query) != NULL && (__query)->select.entries == NULL ) {\
(__query)->select.entries = (as_bin_name*) alloca(sizeof(as_bin_name) * (__n));\
if ( (__query)->select.entries ) { \
(__query)->select._free = false;\
(__query)->select.capacity = (__n);\
(__query)->select.size = 0;\
}\
} \
} while(0)

Initializes as_query.select with a capacity of n using alloca

For heap allocation, use as_query_select_init().

as_query_select(&query, "bin1");
as_query_select(&query, "bin2");
Parameters
__queryThe query to initialize.
__nThe number of bins to allocate.

Definition at line 657 of file as_query.h.

bool as_query_where ( as_query query,
const char *  bin,
as_predicate_type  type,
as_index_type  itype,
as_index_datatype  dtype,
  ... 
)
related

Add a predicate to the query.

You have to ensure as_query.where has sufficient capacity, prior to adding a predicate. If capacity is insufficient then false is returned.

String predicates are not owned by as_query. If the string is allocated on the heap, the caller is responsible for freeing the string after the query has been executed. as_query_destroy() will not free this string predicate.

as_query_where(&query, "bin1", as_string_equals("abc"));
as_query_where(&query, "bin1", as_integer_equals(123));
as_query_where(&query, "bin1", as_integer_range(0,123));
Parameters
queryThe query add the predicate to.
binThe name of the bin the predicate will apply to.
typeThe type of predicate.
itypeThe type of index.
dtypeThe underlying data type that the index is based on.
...The values for the predicate.
Returns
On success, true. Otherwise an error occurred.
bool as_query_where_init ( as_query query,
uint16_t  n 
)
related

Initializes as_query.where with a capacity of n using malloc().

For stack allocation, use as_query_where_inita().

as_query_where(&query, "bin1", as_string_equals("abc"));
as_query_where(&query, "bin1", as_integer_equals(123));
as_query_where(&query, "bin1", as_integer_range(0,123));
Parameters
queryThe query to initialize.
nThe number of as_predicate to allocate.
Returns
On success, true. Otherwise an error occurred.
#define as_query_where_inita (   __query,
  __n 
)
related
Value:
do { \
if ( (__query) != NULL && (__query)->where.entries == NULL ) {\
(__query)->where.entries = (as_predicate*) alloca(sizeof(as_predicate) * (__n));\
if ( (__query)->where.entries ) { \
(__query)->where._free = false;\
(__query)->where.capacity = (__n);\
(__query)->where.size = 0;\
}\
} \
} while(0)

Initializes as_query.where with a capacity of n using alloca().

For heap allocation, use as_query_where_init().

as_query_where(&query, "bin1", as_string_equals("abc"));
as_query_where(&query, "bin2", as_integer_equals(123));
as_query_where(&query, "bin3", as_integer_range(0,123));
Parameters
__queryThe query to initialize.
__nThe number of as_predicate to allocate.
Returns
On success, true. Otherwise an error occurred.

Definition at line 735 of file as_query.h.

#define as_range (   indextype,
  datatype,
  __min,
  __max 
)    AS_PREDICATE_RANGE, AS_INDEX_TYPE_ ##indextype, AS_INDEX_ ##datatype, __min, __max
related

Macro for setting setting the RANGE predicate.

as_query_where(query, "bin1", as_range(LIST,NUMERIC,1,100));

Definition at line 81 of file as_query.h.

#define as_string_equals (   __val)    AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_STRING, __val
related

Macro for setting setting the STRING_EQUAL predicate.

as_query_where(query, "bin1", as_string_equals("abc"));

Definition at line 46 of file as_query.h.

Field Documentation

bool as_query::_free
private

If true, then as_query_destroy() will free this instance.

Definition at line 511 of file as_query.h.

as_udf_call as_query::apply

UDF to apply to results of the query

Should be set via as_query_apply().

Definition at line 580 of file as_query.h.

as_namespace as_query::ns

Namespace to be queried.

Should be initialized via either:

Definition at line 520 of file as_query.h.

as_query_ordering as_query::orderby

Bins to order by.

Use either of the following function to initialize:

Use as_query_orderby() to populate.

Definition at line 573 of file as_query.h.

as_query_predexp as_query::predexp

Predicate Expressions for filtering.

Use either of the following function to initialize:

Use as_query_predexp() to populate.

Definition at line 562 of file as_query.h.

as_query_bins as_query::select

Name of bins to select.

Use either of the following function to initialize:

Use as_query_select() to populate.

Definition at line 540 of file as_query.h.

as_set as_query::set

Set to be queried.

Should be initialized via either:

Definition at line 529 of file as_query.h.

as_query_predicates as_query::where

Predicates for filtering.

Use either of the following function to initialize:

Use as_query_where() to populate.

Definition at line 551 of file as_query.h.


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