SQL QUERY API: As an alternative to building queries one predicate at a time, you can use the SQL query interface. This interface will accept a string containing an SQL query, parse it, convert it into the core representation, and execute it.
STRUCTURE OF A QUERY: A Query is a logical function of any number of QueryTerms. A QueryTerm consists of a C function pointer (the Predicate) and a PredicateData structure containing data passed to the predicate funtion. The PredicateData structure is a constant associated with the Term and is identical for every object that is tested.
The terms of the Query may represent any logical function and are stored in canonical form, i.e. the function is expressed as a logical sum of logical products. So if you have QueryTerms a, b, c, d, e and you have the logical function a(b+c) + !(c(d+e)), it gets stored as ab + ac + !c + !c!e +!d!c + !d!e. This may not be optimal for evaluation of some functions but it's easy to store, easy to manipulate, and it doesn't require a complete algebra system to deal with.
The representation is of a GList of GLists of QueryTerms. The "backbone" GList q->terms represents the OR-chain, and every item on the backbone is a GList of QueryTerms representing an AND-chain corresponding to a single product-term in the canonical representation. QueryTerms are duplicated when necessary to fill out the canonical form, and the same predicate may be evaluated multiple times per split for complex queries. This is a place where we could probably optimize.
Evaluation of a Query (see qof_query_run()) is optimized as much as possible by short-circuited evaluation. The predicates in each AND-chain are sorted by predicate type, with Account queries sorted first to allow the evaluator to completely eliminate accounts from the search if there's no chance of them having splits that match. (XXX above no longer applies)
Files | |
file | qofquery-deserial.h |
Convert Qof-Query XML to QofQuery. | |
file | qofquery-serialize.h |
Convert QofQuery to XML. | |
file | qofquery.h |
find objects that match a certain expression. | |
file | qofquerycore.h |
API for providing core Query data types. | |
file | qofsql.h |
QOF client-side SQL parser. | |
Modules | |
group | Serialize Queries to/from XML |
group | SQL Interface to Query |
Data Structures | |
struct | _QofQueryPredData |
Query Subsystem Initialization and Shudown | |
void | qof_query_init (void) |
void | qof_query_shutdown (void) |
Low-Level API Functions | |
GSList * | qof_query_build_param_list (char const *param,...) |
QofQuery * | qof_query_create (void) |
QofQuery * | qof_query_create_for (QofIdTypeConst obj_type) |
void | qof_query_destroy (QofQuery *q) |
void | qof_query_search_for (QofQuery *query, QofIdTypeConst obj_type) |
void | qof_query_set_book (QofQuery *q, QofBook *book) |
void | qof_query_add_term (QofQuery *query, GSList *param_list, QofQueryPredData *pred_data, QofQueryOp op) |
void | qof_query_add_guid_match (QofQuery *q, GSList *param_list, const GUID *guid, QofQueryOp op) |
void | qof_query_add_guid_list_match (QofQuery *q, GSList *param_list, GList *guid_list, QofGuidMatch options, QofQueryOp op) |
void | qof_query_add_boolean_match (QofQuery *q, GSList *param_list, gboolean value, QofQueryOp op) |
GList * | qof_query_run (QofQuery *query) |
GList * | qof_query_last_run (QofQuery *query) |
void | qof_query_clear (QofQuery *query) |
void | qof_query_purge_terms (QofQuery *q, GSList *param_list) |
int | qof_query_has_terms (QofQuery *q) |
int | qof_query_num_terms (QofQuery *q) |
gboolean | qof_query_has_term_type (QofQuery *q, GSList *term_param) |
QofQuery * | qof_query_copy (QofQuery *q) |
QofQuery * | qof_query_invert (QofQuery *q) |
QofQuery * | qof_query_merge (QofQuery *q1, QofQuery *q2, QofQueryOp op) |
void | qof_query_merge_in_place (QofQuery *q1, QofQuery *q2, QofQueryOp op) |
void | qof_query_set_sort_order (QofQuery *q, GSList *primary_sort_params, GSList *secondary_sort_params, GSList *tertiary_sort_params) |
void | qof_query_set_sort_options (QofQuery *q, gint prim_op, gint sec_op, gint tert_op) |
void | qof_query_set_sort_increasing (QofQuery *q, gboolean prim_inc, gboolean sec_inc, gboolean tert_inc) |
void | qof_query_set_max_results (QofQuery *q, int n) |
gboolean | qof_query_equal (QofQuery *q1, QofQuery *q2) |
void | qof_query_print (QofQuery *query) |
QofIdType | qof_query_get_search_for (QofQuery *q) |
GList * | qof_query_get_books (QofQuery *q) |
Core Data Type Predicates | |
QofQueryPredData * | qof_query_string_predicate (QofQueryCompare how, const char *str, QofStringMatch options, gboolean is_regex) |
QofQueryPredData * | qof_query_date_predicate (QofQueryCompare how, QofDateMatch options, Timespec date) |
QofQueryPredData * | qof_query_numeric_predicate (QofQueryCompare how, QofNumericMatch options, gnc_numeric value) |
QofQueryPredData * | qof_query_guid_predicate (QofGuidMatch options, GList *guids) |
QofQueryPredData * | qof_query_int32_predicate (QofQueryCompare how, gint32 val) |
QofQueryPredData * | qof_query_int64_predicate (QofQueryCompare how, gint64 val) |
QofQueryPredData * | qof_query_double_predicate (QofQueryCompare how, double val) |
QofQueryPredData * | qof_query_boolean_predicate (QofQueryCompare how, gboolean val) |
QofQueryPredData * | qof_query_char_predicate (QofCharMatch options, const char *chars) |
QofQueryPredData * | qof_query_kvp_predicate (QofQueryCompare how, GSList *path, const KvpValue *value) |
QofQueryPredData * | qof_query_kvp_predicate_path (QofQueryCompare how, const char *path, const KvpValue *value) |
QofQueryPredData * | qof_query_core_predicate_copy (QofQueryPredData *pdata) |
void | qof_query_core_predicate_free (QofQueryPredData *pdata) |
char * | qof_query_core_to_string (QofType, gpointer object, QofParam *getter) |
Defines | |
#define | QOF_QUERY_FIRST_TERM QOF_QUERY_AND |
#define | QUERY_DEFAULT_SORT "QofQueryDefaultSort" |
#define | QOF_PARAM_BOOK "book" |
#define | QOF_PARAM_GUID "guid" |
#define | QOF_PARAM_ACTIVE "active" |
#define | QOF_DATE_MATCH_ROUNDED QOF_DATE_MATCH_DAY |
#define | QOF_DATE_MATCH_NORMAL QOF_DATE_MATCH_TIME |
Typedefs | |
typedef _QofQuery | QofQuery |
typedef _QofQueryPredData | QofQueryPredData |
Enumerations | |
enum | QofQueryOp { QOF_QUERY_AND = 1, QOF_QUERY_OR, QOF_QUERY_NAND, QOF_QUERY_NOR, QOF_QUERY_XOR } |
enum | QofQueryCompare { QOF_COMPARE_LT = 1, QOF_COMPARE_LTE, QOF_COMPARE_EQUAL, QOF_COMPARE_GT, QOF_COMPARE_GTE, QOF_COMPARE_NEQ } |
enum | QofStringMatch { QOF_STRING_MATCH_NORMAL = 1, QOF_STRING_MATCH_CASEINSENSITIVE } |
enum | QofDateMatch { QOF_DATE_MATCH_NORMAL = 1, QOF_DATE_MATCH_DAY } |
enum | QofNumericMatch { QOF_NUMERIC_MATCH_DEBIT = 1, QOF_NUMERIC_MATCH_CREDIT, QOF_NUMERIC_MATCH_ANY } |
enum | QofGuidMatch { QOF_GUID_MATCH_ANY = 1, QOF_GUID_MATCH_NONE, QOF_GUID_MATCH_NULL, QOF_GUID_MATCH_ALL, QOF_GUID_MATCH_LIST_ANY } |
enum | QofCharMatch { QOF_CHAR_MATCH_ANY = 1, QOF_CHAR_MATCH_NONE } |
|
Comparisons for QOF_TYPE_DATE The QOF_DATE_MATCH_DAY comparison rounds the two time values to mid-day and then compares these rounded values. The QOF_DATE_MATCH_TIME comparison matches teh time values, down to the second. |
|
"Known" Object Parameters -- some objects might support these |
|
"Known" Object Parameters -- all objects must support these |
|
Default sort object type |
|
A Query |
|
PREDICATE DATA TYPES: All the predicate data types are rolled up into the union type PredicateData. The "type" field specifies which type the union is. |
|
A CHAR type is for a RECNCell, Comparisons for QOF_TYPE_CHAR 'ANY' will match any charagter in the string. Match 'ANY' is a convenience/performance-enhanced predicate for the compound statement (value==char1) || (value==char2) || etc. Match 'NONE' is equivalent to (value != char1) && (value != char2) && etc. |
|
|
Standard Query comparitors, for how to compare objects in a predicate. Note that not all core types implement all comparitors |
|
Query Term Operators, for combining Query Terms |
|
List of known core query data-types... Each core query type defines it's set of optional "comparitor qualifiers". |
|
Handy-dandy convenience routines, avoids having to create a separate predicate for boolean matches. We might want to create handy-dandy sugar routines for the other predicate types as well. |
|
DOCUMENT ME !! |
|
DOCUMENT ME !! |
|
This is the general function that adds a new Query Term to a query. It will find the 'obj_type' object of the search item and compare the 'param_list' parameter to the predicate data via the comparitor. The param_list is a recursive list of parameters. For example, you can say 'split->memo' by creating a list of one element, "SPLIT_MEMO". You can say 'split->account->name' by creating a list of two elements, "SPLIT_ACCOUNT" and "ACCOUNT_NAME". The list becomes the property of the Query. For example: acct_name_pred_data = make_string_pred_data(QOF_STRING_MATCH_CASEINSENSITIVE, account_name); param_list = make_list (SPLIT_ACCOUNT, ACCOUNT_NAME, NULL); qof_query_add_term (query, param_list, QOF_COMPARE_EQUAL, acct_name_pred_data, QOF_QUERY_AND); Please note that QofQuery does not, at this time, support joins. That is, one cannot specify a predicate that is a parameter list. Put another way, one cannot search for objects where obja->thingy == objb->stuff |
|
Remove all query terms from query. query matches nothing after qof_query_clear(). |
|
Make a copy of the indicated query |
|
Copy a predicate. |
|
Destroy a predicate. |
|
Return a printable string for a core data object. Caller needs to g_free() the returned string. |
|
Create a new query. Before running the query, a 'search-for' type must be set otherwise nothing will be returned. The results of the query is a list of the indicated search-for type. Allocates and initializes a Query structure which must be freed by the user with qof_query_destroy(). A newly-allocated QofQuery object matches nothing (qof_query_run() will return NULL). |
|
Frees the resources associate with a Query object. |
|
Compare two queries for equality. Query terms are compared each to each. This is a simplistic implementation -- logical equivalences between different and/or trees are ignored. |
|
Return the list of books we're using |
|
Return the type of data we're querying for |
|
DOCUMENT ME !! |
|
Return boolean FALSE if there are no terms in the query Can be used as a predicate to see if the query has been initialized (return value > 0) or is "blank" (return value == 0). |
|
Subsystem initialization and shutdown. Call init() once to initalize the query subsytem; call shutdown() to free up any resources associated with the query subsystem. Typically called during application startup, shutdown. |
|
Make a copy of the indicated query, inverting the sense of the search. In other words, if the original query search for all objects with a certain condition, the inverted query will search for all object with NOT that condition. The union of the results returned by the original and inverted queries equals the set of all searched objects. These to sets are disjoint (share no members in common). This will return a newly allocated QofQuery object, or NULL on error. Free it with qof_query_destroy() when no longer needed. |
|
The qof_query_kvp_predicate() matches the object that has the value 'value' located at the path 'path'. In a certain sense, the 'path' is handled as if it were a paramter. |
|
Same predicate as above, except that 'path' is assumed to be a string containing slash-separated pathname. |
|
Return the results of the last query, without causing the query to be re-run. Do NOT free the resulting list. This list is managed internally by QofQuery. |
|
Combine two queries together using the Boolean set (logical) operator 'op'. For example, if the operator 'op' is set to QUERY_AND, then the set of results returned by the query will will be the Boolean set intersection of the results returned by q1 and q2. Similarly, QUERY_OR maps to set union, etc. Both queries must have compatible search-types. If both queries are set, they must search for the same object type. If only one is set, the resulting query will search for the set type. If neither query has the search-type set, the result will be unset as well. This will return a newly allocated QofQuery object, or NULL on error. Free it with qof_query_destroy() when no longer needed. |
|
Like qof_query_merge, but this will merge a copy of q2 into q1. q2 remains unchanged. |
|
Return the number of terms in the canonical form of the query. |
|
Print the Query in human-readable format. Useful for debugging and development. |
|
Remove query terms of a particular type from q. The "type" of a term is determined by the type of data that gets passed to the predicate function. XXX ??? Huh? remove anything of that predicate type, or just the particular predicate ? |
|
Perform the query, return the results. The returned list is a list of the 'search-for' type that was previously set with the qof_query_search_for() or the qof_query_create_for() routines. The returned list will have been sorted using the indicated sort order, and trimed to the max_results length. Do NOT free the resulting list. This list is managed internally by QofQuery. |
|
Set the object type to be searched for. The results of performuing the query will be a list of this obj_type. |
|
Set the book to be searched. Books contain/identify collections of objects; the search will be performed over those books specified with this function. If no books are set, no results will be returned (since there is nothing to search over). You can search multiple books. To specify multiple books, call this function multiple times with different arguments. XXX needed qof_query_clear_books() to reset the list ... |
|
Set the maximum number of results that should be returned. If 'max-results' is set to -1, then all of the results are returned. If there are more results than 'max-results', then the result list is trimmed. Note that there is an important interplay between 'max-results' and the sort order: only the last bit of results are returned. For example, if the sort order is set to be increasing date order, then only the objects with the most recent dates will be returned. |
|
When a query is run, the results are sorted before being returned. This routine can be used to control the direction of the ordering. A value of TRUE indicates the sort will be in increasing order, a value of FALSE will order results in decreasing order. Note that if there are more results than the 'max-results' value, then only the *last* max-results will be returned. For example, if the sort is set to be increasing date order, then only the objects with the most recent dates will be returned. |
|
When a query is run, the results are sorted before being returned. This routine can be used to set the paramters on which the sort will be performed. Two objects in the result list will be compared using the 'primary_sort_params', and sorted based on that order. If the comparison shows that they are equal, then the 'secondary_sort_params' will be used. If still equal, then the tertiary params will be compared. Any or all of these parameter lists may be NULL. Any of these parameter lists may be set to QUERY_DEFAULT_SORT. Note that if there are more results than the 'max-results' value, then only the *last* max-results will be returned. For example, if the sort is set to be increasing date order, then only the objects with the most recent dates will be returned. The input lists become the property of QofQuery and are managed by it. They will be freed when the query is destroyed (or when new lists are set). |