as_query Struct Reference

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()
• as_query_new()

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 461 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 Symbols
(Note that these are not member symbols.)
#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 Symbol Documentation

as_blob_contains

#define as_blob_contains ( indextype, __val, __size, __free )   AS_PREDICATE_EQUAL, AS_INDEX_TYPE_ ##indextype, AS_INDEX_BLOB, __val, __size, __free

related

Contains blob filter on list/map elements. Requires server version 7.0+.

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

as_blob_equals

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

related

Filter on blob bins. Requires server version 7.0+.

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

as_contains

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

related

Contains filter on list/map elements.

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

Definition at line 108 of file as_query.h.

as_equals

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

related

Filter specified type on bins.

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

Definition at line 134 of file as_query.h.

as_geo_contains

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

related

Contains filter on GEO bins.

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

Definition at line 158 of file as_query.h.

as_geo_within

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

related

Within filter on GEO bins.

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

Definition at line 146 of file as_query.h.

as_integer_equals

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

related

Filter on integer bins.

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

Definition at line 72 of file as_query.h.

as_integer_range

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

related

Ranger filter on integer bins.

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

Definition at line 84 of file as_query.h.

as_query_select_inita

#define as_query_select_inita ( __query, __n )

related

Value:

    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.

as_query_where_inita

#define as_query_where_inita ( __query, __n )

related

Value:

    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_range

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

related

Range filter on list/map elements.

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

Definition at line 96 of file as_query.h.

as_string_equals

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

related

Filter on string bins.

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

Definition at line 46 of file as_query.h.

Field Documentation

apply

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

max_records

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

no_bins

bool as_query::no_bins

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

Default: false.

Definition at line 571 of file as_query.h.

ns

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

ops

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

paginate

bool as_query::paginate

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

Default: false

Definition at line 564 of file as_query.h.

parts_all

as_partitions_status* as_query::parts_all

Status of all partitions.

Definition at line 525 of file as_query.h.

records_per_second

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

select

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

set

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

ttl

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

where

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

---

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

• as_query.h