Detailed Description

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

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:

as_query_destroy(query);

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:

as_query_select_inita() - Initializes the structure on the stack.
as_query_select_init() - Initializes the structure on the heap.

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

A complete example using as_query_select_inita()

as_query_select_inita(query, 2);
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:

as_string_equals() - Test for string equality.
as_integer_equals() - Test for integer equality.
as_integer_range() - Test for integer within a range.

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

as_query_where_inita() - Initializes the structure on the stack.
as_query_where_init() - Initializes the structure on the heap.

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

A complete example using as_query_where_inita():

as_query_where_inita(query, 1);

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

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 462 of file as_query.h.

#include "as_query.h"

Collaboration diagram for as_query:

Data Fields
as_udf_call	apply

uint64_t	max_records

bool	no_bins

as_namespace	ns

struct as_operations_s *	ops

bool	paginate

as_partitions_status *	parts_all

uint32_t	records_per_second

as_query_bins	select

as_set	set

uint32_t	ttl

as_query_predicates	where

Related Functions
(Note that these are not member functions.)
#define	as_blob_contains(indextype, __val, __size, __free) AS_PREDICATE_EQUAL, AS_INDEX_TYPE_ ##indextype, AS_INDEX_BLOB, __val, __size, __free

#define	as_blob_equals(__val, __size, __free) AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_BLOB, __val, __size, __free

#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_geo_contains(__val) AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_GEO2DSPHERE, __val

#define	as_geo_within(__val) AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_GEO2DSPHERE, __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

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

AS_EXTERN bool	as_query_compare (as_query q1, as_query q2)

AS_EXTERN void	as_query_destroy (as_query *query)

AS_EXTERN bool	as_query_from_bytes (as_query query, const uint8_t bytes, uint32_t bytes_size)

AS_EXTERN as_query *	as_query_from_bytes_new (const uint8_t *bytes, uint32_t bytes_size)

AS_EXTERN as_query *	as_query_init (as_query query, const char ns, const char *set)

static bool	as_query_is_done (as_query *query)

AS_EXTERN as_query *	as_query_new (const char ns, const char set)

AS_EXTERN bool	as_query_select (as_query query, const char bin)

AS_EXTERN bool	as_query_select_init (as_query *query, uint16_t n)

#define	as_query_select_inita(__query, __n)

static void	as_query_set_paginate (as_query *query, bool paginate)

static void	as_query_set_partitions (as_query query, as_partitions_status parts_all)

AS_EXTERN bool	as_query_to_bytes (const as_query query, uint8_t bytes, uint32_t bytes_size)

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

AS_EXTERN bool	as_query_where_init (as_query *query, uint16_t n)

#define	as_query_where_inita(__query, __n)

AS_EXTERN bool	as_query_where_with_ctx (as_query query, const char bin, struct as_cdt_ctx *ctx, as_predicate_type type, as_index_type itype, as_index_datatype dtype,...)

#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_blob_contains	(	indextype,
		__val,
		__size,
		__free
	)	AS_PREDICATE_EQUAL, AS_INDEX_TYPE_ ##indextype, AS_INDEX_BLOB, __val, __size, __free

// as_blob_contains(type, uint8_t* bytes, uint32_t size, bool free)

as_query_where(query, "bin1", as_blob_equals(LIST, bytes, size, true));

Definition at line 122 of file as_query.h.

#define as_blob_equals	(	__val,
		__size,
		__free
	)	AS_PREDICATE_EQUAL, AS_INDEX_TYPE_DEFAULT, AS_INDEX_BLOB, __val, __size, __free

// as_blob_equals(uint8_t* bytes, uint32_t size, bool free)

as_query_where(query, "bin1", as_blob_equals(bytes, size, true));

Definition at line 60 of file as_query.h.

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

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

Definition at line 108 of file as_query.h.

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

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

Definition at line 134 of file as_query.h.

#define as_geo_contains ( __val ) AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_GEO2DSPHERE, __val

as_query_where(query, "bin1", as_geo_contains(region));

Definition at line 158 of file as_query.h.

#define as_geo_within ( __val ) AS_PREDICATE_RANGE, AS_INDEX_TYPE_DEFAULT, AS_INDEX_GEO2DSPHERE, __val

as_query_where(query, "bin1", as_geo_within(region));

Definition at line 146 of file as_query.h.

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

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

Definition at line 72 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

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

Definition at line 84 of file as_query.h.

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

as_query_apply(&query, "my_module", "my_function", NULL);

Parameters

query	The query to apply the function to.
module	The module containing the function to invoke.
function	The function in the module to invoke.
arglist	The arguments to use when calling the function.

Returns: On success, true. Otherwise an error occurred.

AS_EXTERN bool as_query_compare	(	as_query *	q1,
		as_query *	q2
	)

AS_EXTERN void as_query_destroy ( as_query * query )

AS_EXTERN bool as_query_from_bytes	(	as_query *	query,
		const uint8_t *	bytes,
		uint32_t	bytes_size
	)

Returns: true on success and false on failure.

AS_EXTERN as_query * as_query_from_bytes_new	(	const uint8_t *	bytes,
		uint32_t	bytes_size
	)

Returns: query definition on success and NULL on failure.

AS_EXTERN as_query * as_query_init	(	as_query *	query,
		const char *	ns,
		const char *	set
	)

as_query query;

as_query_init(&query, "test", "demo");

Parameters

query	The query to initialize.
ns	The namespace to query.
set	The set to query.

Returns: On success, the initialized query. Otherwise NULL.

static bool as_query_is_done ( as_query * query )

Definition at line 889 of file as_query.h.

References as_partitions_status::done, and parts_all.

AS_EXTERN as_query * as_query_new	(	const char *	ns,
		const char *	set
	)

as_query* query = as_query_new("test", "demo");

Parameters

ns	The namespace to query.
set	The set to query.

Returns: On success, the new query. Otherwise NULL.

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

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_init(&query, 2);
as_query_select(&query, "bin1");
as_query_select(&query, "bin2");

Parameters

query	The query to modify.
bin	The name of the bin to select.

Returns: On success, true. Otherwise an error occurred.

AS_EXTERN bool as_query_select_init	(	as_query *	query,
		uint16_t	n
	)

For stack allocation, use as_query_select_inita().

as_query_select_init(&query, 2);
as_query_select(&query, "bin1");
as_query_select(&query, "bin2");

Parameters

query	The query to initialize.
n	The number of bins to allocate.

Returns: On success, the initialized. Otherwise an error occurred.

#define as_query_select_inita	(	__query,
		__n
	)

do { \
        if ((__query)->select.entries == NULL) {\
            (__query)->select.entries = (as_bin_name*) alloca(sizeof(as_bin_name) * (__n));\
            if ( (__query)->select.entries ) { \
                (__query)->select.capacity = (__n);\
                (__query)->select.size = 0;\
                (__query)->select._free = false;\
            }\
        } \
    } while(0)

Initializes as_query.select with a capacity of n using alloca

For heap allocation, use as_query_select_init().

as_query_select_inita(&query, 2);
as_query_select(&query, "bin1");
as_query_select(&query, "bin2");

Parameters

__query	The query to initialize.
__n	The number of bins to allocate.

Definition at line 647 of file as_query.h.

static void as_query_set_paginate	(	as_query *	query,
		bool	paginate
	)

Definition at line 863 of file as_query.h.

References paginate.

static void as_query_set_partitions	(	as_query *	query,
		as_partitions_status *	parts_all
	)

Definition at line 876 of file as_query.h.

References as_partitions_status_reserve(), and parts_all.

AS_EXTERN bool as_query_to_bytes	(	const as_query *	query,
		uint8_t **	bytes,
		uint32_t *	bytes_size
	)

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

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_init(&query, 3);
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

query	The query add the predicate to.
bin	The name of the bin the predicate will apply to.
type	The type of predicate.
itype	The type of index.
dtype	The underlying data type that the index is based on.
...	The values for the predicate.

Returns: On success, true. Otherwise an error occurred.

AS_EXTERN bool as_query_where_init	(	as_query *	query,
		uint16_t	n
	)

For stack allocation, use as_query_where_inita().

as_query_where_init(&query, 1);

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

Parameters

query	The query to initialize.
n	The number of as_predicate to allocate.

Returns: On success, true. Otherwise an error occurred.

#define as_query_where_inita	(	__query,
		__n
	)

do { \
        if ((__query)->where.entries == NULL) {\
            (__query)->where.entries = (as_predicate*) alloca(sizeof(as_predicate) * (__n));\
            if ( (__query)->where.entries ) {\
                (__query)->where.capacity = (__n);\
                (__query)->where.size = 0;\
                (__query)->where._free = false;\
            }\
        } \
    } while(0)

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

For heap allocation, use as_query_where_init().

as_query_where_inita(&query, 1);

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

Parameters

__query	The query to initialize.
__n	The number of as_predicate to allocate.

Returns: On success, true. Otherwise an error occurred.

Definition at line 725 of file as_query.h.

AS_EXTERN bool as_query_where_with_ctx	(	as_query *	query,
		const char *	bin,
		struct as_cdt_ctx *	ctx,
		as_predicate_type	type,
		as_index_type	itype,
		as_index_datatype	dtype,
			...
	)

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_cdt_ctx ctx;
as_cdt_ctx_init(&ctx, 1);
as_cdt_ctx_add_list_rank(&ctx, -1);
as_query_where_init(&query, 3);
as_query_where_with_ctx(&query, "bin1", &ctx, as_string_equals("abc"));
as_query_where_with_ctx(&query, "bin1", &ctx, as_integer_equals(123));
as_query_where_with_ctx(&query, "bin1", &ctx, as_integer_range(0,123));

Parameters

query	The query add the predicate to.
bin	The name of the bin the predicate will apply to.
ctx	The CDT context describing the path to locate the data to be indexed.
type	The type of predicate.
itype	The type of index.
dtype	The underlying data type that the index is based on.
...	The values for the predicate.

Returns: On success, true. Otherwise an error occurred.

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

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

Definition at line 96 of file as_query.h.

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

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

Definition at line 46 of file as_query.h.

Field Documentation

as_udf_call as_query::apply

UDF to apply to results of a background query or a foreground aggregation query.

Should be set via as_query_apply().

Definition at line 515 of file as_query.h.

uint64_t as_query::max_records

Approximate number of records to return to client. This number is divided by the number of nodes involved in the query. The actual number of records returned may be less than max_records if node record counts are small and unbalanced across nodes.

Default: 0 (do not limit record count)

Definition at line 536 of file as_query.h.

bool as_query::no_bins

Set to true if query should only return keys and no bin data.

Default: false.

Definition at line 572 of file as_query.h.

as_namespace as_query::ns

Namespace to be queried.

Should be initialized via either:

as_query_init() - To initialize a stack allocated query.
as_query_new() - To heap allocate and initialize a query.

Definition at line 477 of file as_query.h.

struct as_operations_s* as_query::ops

Perform write operations on a background query. If ops is set, ops will be destroyed when as_query_destroy() is called.

Definition at line 521 of file as_query.h.

bool as_query::paginate

Should records be read in pages in conjunction with max_records policy.

Default: false

Definition at line 565 of file as_query.h.

as_partitions_status* as_query::parts_all

Status of all partitions.

Definition at line 526 of file as_query.h.

uint32_t as_query::records_per_second

Limit returned records per second (rps) rate for each server. Do not apply rps limit if records_per_second is zero.

Default: 0

Definition at line 544 of file as_query.h.

as_query_bins as_query::select

Name of bins to select.

Use either of the following function to initialize:

as_query_select_init() - To initialize on the heap.
as_query_select_inita() - To initialize on the stack.

Use as_query_select() to populate.

Definition at line 497 of file as_query.h.

as_set as_query::set

Set to be queried.

Should be initialized via either:

as_query_init() - To initialize a stack allocated query.
as_query_new() - To heap allocate and initialize a query.

Definition at line 486 of file as_query.h.

uint32_t as_query::ttl

The time-to-live (expiration) of the record in seconds. Note that ttl is only used on background query writes.

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_write.

Definition at line 558 of file as_query.h.

as_query_predicates as_query::where

Predicates for filtering.

Use either of the following function to initialize:

as_query_where_init() - To initialize on the heap.
as_query_where_inita() - To initialize on the stack.

Use as_query_where() to populate.

Definition at line 508 of file as_query.h.

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

as_query.h

Detailed Description

Initialization

Destruction

Usage

Selecting Bins

Predicates on Bins

Applying a UDF to Query Results

Data Fields

Related Functions

Friends And Related Function Documentation

Field Documentation