|
upscaledb
2.2.1
|
Include file for upscaledb Query Interface. More...
#include <ups/upscaledb.h>Go to the source code of this file.
Data Structures | |
| struct | uqi_plugin_t |
Macros | |
| #define | UQI_STREAM_KEY 1 |
| #define | UQI_STREAM_RECORD 2 |
| #define | UQI_PLUGIN_PREDICATE 1 |
| #define | UQI_PLUGIN_AGGREGATE 2 |
| #define | UQI_PLUGIN_REQUIRE_BOTH_STREAMS 1 |
Typedefs | |
| typedef struct uqi_result_t | uqi_result_t |
| typedef void *(* | uqi_plugin_init_function) (int flags, int key_type, uint32_t key_size, int record_type, uint32_t record_size, const char *reserved) |
| typedef void(* | uqi_plugin_cleanup_function) (void *state) |
| typedef void(* | uqi_plugin_aggregate_single_function) (void *state, const void *key_data, uint32_t key_size, const void *record_data, uint32_t record_size) |
| typedef void(* | uqi_plugin_aggregate_many_function) (void *state, const void *key_data_list, const void *record_data_list, size_t list_length) |
| typedef int(* | uqi_plugin_predicate_function) (void *state, const void *key_data, uint32_t key_size, const void *record_data, uint32_t record_size) |
| typedef void(* | uqi_plugin_result_function) (void *state, uqi_result_t *result) |
Include file for upscaledb Query Interface.
This API is EXPERIMENTAL!! The interface is not yet stable.
Definition in file upscaledb_uqi.h.
| #define UQI_PLUGIN_AGGREGATE 2 |
Describes a plugin for aggregation
Definition at line 185 of file upscaledb_uqi.h.
Referenced by main().
| #define UQI_PLUGIN_PREDICATE 1 |
Describes a plugin for predicates
Definition at line 182 of file upscaledb_uqi.h.
Referenced by main().
| #define UQI_PLUGIN_REQUIRE_BOTH_STREAMS 1 |
Describes a plugin which requires keys AND records
Definition at line 188 of file upscaledb_uqi.h.
| #define UQI_STREAM_KEY 1 |
Plugin initialization flag
Definition at line 152 of file upscaledb_uqi.h.
| #define UQI_STREAM_RECORD 2 |
Plugin initialization flag
Definition at line 155 of file upscaledb_uqi.h.
| typedef void(* uqi_plugin_aggregate_many_function) (void *state, const void *key_data_list, const void *record_data_list, size_t list_length) |
Performs the actual aggregation on a list of values
Definition at line 166 of file upscaledb_uqi.h.
| typedef void(* uqi_plugin_aggregate_single_function) (void *state, const void *key_data, uint32_t key_size, const void *record_data, uint32_t record_size) |
Performs the actual aggregation on a single value
Definition at line 161 of file upscaledb_uqi.h.
| typedef void(* uqi_plugin_cleanup_function) (void *state) |
Cleans up the state variable and can release resources
Definition at line 158 of file upscaledb_uqi.h.
| typedef void*(* uqi_plugin_init_function) (int flags, int key_type, uint32_t key_size, int record_type, uint32_t record_size, const char *reserved) |
The plugins are stateless and threadsafe. However, the "init" function is called prior to the actual usage, and it can allocate (and return) a state variable.
|flags| specify whether this plugin will work on keys, records or both (UQI_STREAM_KEY, UQI_STREAM_RECORD) |key_type| is the key type specified by the user (i.e. UPS_TYPE_UINT32), |key_size| is the specified key size |record_type| is the record type specified by the user |record_size| is the specified record size
Definition at line 147 of file upscaledb_uqi.h.
| typedef int(* uqi_plugin_predicate_function) (void *state, const void *key_data, uint32_t key_size, const void *record_data, uint32_t record_size) |
Predicate function; returns true if the value matches the predicate, otherwise false
Definition at line 174 of file upscaledb_uqi.h.
| typedef void(* uqi_plugin_result_function) (void *state, uqi_result_t *result) |
Assigns the results to an uqi_result_t structure
Definition at line 179 of file upscaledb_uqi.h.
| typedef struct uqi_result_t uqi_result_t |
Definition at line 41 of file upscaledb_uqi.h.
| UPS_EXPORT ups_status_t UPS_CALLCONV uqi_register_plugin | ( | uqi_plugin_t * | descriptor | ) |
Manually registers a UQI plugiRegisters a UQI plugin
This is the pro-active alternative to exporting a plugin descriptor from a dynamic library. Use this if your plugin is linked statically into your application.
Referenced by main().
| UPS_EXPORT void UPS_CALLCONV uqi_result_add_row | ( | uqi_result_t * | result, |
| const void * | key_data, | ||
| uint32_t | key_size, | ||
| const void * | record_data, | ||
| uint32_t | record_size | ||
| ) |
Adds a new key/value pair to a result set.
This can be used by plugin implementors to assign the results of an aggregation query.
result Pointer to the uqi_result_t object. key_data The data of the new key key_size The size of the new key (in bytes) record_data The data of the new record record_size The size of the new record (in bytes)
Referenced by mycount_results().
| UPS_EXPORT void UPS_CALLCONV uqi_result_close | ( | uqi_result_t * | result | ) |
Releases the resources allocated by an uqi_result_t type.
Call this to avoid memory leaks.
result Pointer to the uqi_result_t object.
Referenced by main().
| UPS_EXPORT void UPS_CALLCONV uqi_result_get_key | ( | uqi_result_t * | result, |
| uint32_t | row, | ||
| ups_key_t * | key | ||
| ) |
Returns a key for the specified row
Referenced by main().
| UPS_EXPORT void* UPS_CALLCONV uqi_result_get_key_data | ( | uqi_result_t * | result, |
| uint32_t * | size | ||
| ) |
Returns a pointer to the serialized key data
If the keys have a fixed-length type (i.e. UPS_TYPE_UINT32) then this corresponds to an array of this type (here: uint32_t).
| UPS_EXPORT uint32_t UPS_CALLCONV uqi_result_get_key_type | ( | uqi_result_t * | result | ) |
Returns the key type
| UPS_EXPORT void UPS_CALLCONV uqi_result_get_record | ( | uqi_result_t * | result, |
| uint32_t | row, | ||
| ups_record_t * | record | ||
| ) |
Returns a record for the specified row
Referenced by main().
| UPS_EXPORT void* UPS_CALLCONV uqi_result_get_record_data | ( | uqi_result_t * | result, |
| uint32_t * | size | ||
| ) |
Returns a pointer to the serialized record data
If the record have a fixed-length type (i.e. UPS_TYPE_UINT32) then this corresponds to an array of this type (here: uint32_t).
| UPS_EXPORT uint32_t UPS_CALLCONV uqi_result_get_record_type | ( | uqi_result_t * | result | ) |
Returns the record type
| UPS_EXPORT uint32_t UPS_CALLCONV uqi_result_get_row_count | ( | uqi_result_t * | result | ) |
Returns the number of rows stored in a query result
| UPS_EXPORT void UPS_CALLCONV uqi_result_initialize | ( | uqi_result_t * | result, |
| int | key_type, | ||
| int | record_type | ||
| ) |
Initializes an uqi_result_t object.
result Pointer to the uqi_result_t object. key_type The key type (i.e. UPS_TYPE_BINARY) record_type The record type (i.e. UPS_TYPE_UINT64)
| UPS_EXPORT void UPS_CALLCONV uqi_result_move | ( | uqi_result_t * | destination, |
| uqi_result_t * | source | ||
| ) |
Efficiently moves a result set's data to another one.
| UPS_EXPORT ups_status_t UPS_CALLCONV uqi_select | ( | ups_env_t * | env, |
| const char * | query, | ||
| uqi_result_t ** | result | ||
| ) |
Performs a "UQI Select" query.
See below for a description of the query syntax. In short, this function can execute aggregation functions like SUM, AVERAGE or COUNT over a database. The result is returned in result, which is allocated by this function and has to be released with uqi_result_close.
Referenced by main().
| UPS_EXPORT ups_status_t UPS_CALLCONV uqi_select_range | ( | ups_env_t * | env, |
| const char * | query, | ||
| ups_cursor_t * | begin, | ||
| const ups_cursor_t * | end, | ||
| uqi_result_t ** | result | ||
| ) |
Performs a paginated "UQI Select" query.
This function is similar to uqi_db_select, but uses two cursors for specifying the range of the data. Make sure that both cursors are operating on the same database as the query. Both cursors are optional; if begin is null then the query will start at the first element (with the lowest key) in the database. If end is null then it will run till the last element of the database.
If begin is not null then it will be moved to the first key behind the processed range.
If the specified Database is not yet opened, it will be reopened in background and immediately closed again after the query. Closing the Database can hurt performance. To avoid this, manually open the Database (see ups_env_open_db) prior to the query. The uqi_select_range method will then re-use the existing Database handle.
The supplied query string has a syntax similar to SQL:
[DISTINCT] <FUNCTION>(<STREAM>) FROM DATABASE <DB> [WHERE <PREDICATE>(<STREAM>)] [LIMIT <LIMIT>]
DISTINCT: an optional key word which strips the query input from all duplicate keys. (This is different from SQL where duplicate results are removed.)
FUNCTION: an identifier for a built-in or an external aggregation function. Built-in functions are SUM, COUNT, AVERAGE, TOP, BOTTOM, MIN and MAX. External identifiers are names of registered plugins (with uqi_register_plugin) or loaded from external libraries.
DB: the numerical id of the database
PREDICATE: an identifier for a predicate function.
STREAM: a literal "$key" or "$record"; decides whether keys or records are aggregated
LIMIT: a limit for the result. Currently ONLY allowed for the built-in functions "TOP" and "BOTTOM"! When used with other functions then an error is returned.
The result object is allocated automatically and has to be released with uqi_result_close by the caller.
1.8.11