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.
Files | |
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, interfacing with libgda. | |
Modules | |
SQL Interface to Query | |
Data Structures | |
struct | _QofQueryPredData |
Defines | |
#define | QOF_MOD_QUERY "qof-query" |
#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_KVP "kvp" |
#define | QOF_PARAM_ACTIVE "active" |
#define | QOF_PARAM_VERSION "version" |
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 } |
|
"Known" Object Parameters -- all objects must support these Definition at line 103 of file qofquery.h. |
|
"Known" Object Parameters -- some objects might support these Definition at line 107 of file qofquery.h. |
|
First/only term is same as 'and' Definition at line 97 of file qofquery.h. |
|
Default sort object type Definition at line 100 of file qofquery.h. |
|
A Query Definition at line 85 of file qofquery.h. |
|
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. Definition at line 45 of file qofquerycore.h. |
|
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. Definition at line 121 of file qofquerycore.h. 00121 { 00122 QOF_CHAR_MATCH_ANY = 1, 00123 QOF_CHAR_MATCH_NONE 00124 } QofCharMatch;
|
|
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_NORMAL comparison matches the time values, down to the second. Definition at line 75 of file qofquerycore.h. 00075 { 00076 QOF_DATE_MATCH_NORMAL = 1, 00077 QOF_DATE_MATCH_DAY 00078 } QofDateMatch;
|
|
Definition at line 99 of file qofquerycore.h. 00099 { 00102 QOF_GUID_MATCH_ANY = 1, 00103 QOF_GUID_MATCH_NONE, 00104 QOF_GUID_MATCH_NULL, 00107 QOF_GUID_MATCH_ALL, 00110 QOF_GUID_MATCH_LIST_ANY, 00111 } QofGuidMatch;
|
|
Comparisons for QOF_TYPE_NUMERIC, QOF_TYPE_DEBCRED XXX Should be deprecated, or at least wrapped up as a convenience function, this is based on the old bill gribble code, which assumed the amount was always positive, and then specified a funds-flow direction (credit, debit, or either). The point being that 'match credit' is equivalent to the compound predicate (amount >= 0) && (amount 'op' value) while the 'match debit' predicate is equivalent to (amount <= 0) && (abs(amount) 'op' value) Definition at line 92 of file qofquerycore.h. 00092 { 00093 QOF_NUMERIC_MATCH_DEBIT = 1, 00094 QOF_NUMERIC_MATCH_CREDIT, 00095 QOF_NUMERIC_MATCH_ANY 00096 } QofNumericMatch;
|
|
Standard Query comparitors, for how to compare objects in a predicate. Note that not all core types implement all comparitors Definition at line 50 of file qofquerycore.h. 00050 { 00051 QOF_COMPARE_LT = 1, 00052 QOF_COMPARE_LTE, 00053 QOF_COMPARE_EQUAL, 00054 QOF_COMPARE_GT, 00055 QOF_COMPARE_GTE, 00056 QOF_COMPARE_NEQ 00057 } QofQueryCompare;
|
|
Query Term Operators, for combining Query Terms Definition at line 88 of file qofquery.h. 00088 { 00089 QOF_QUERY_AND=1, 00090 QOF_QUERY_OR, 00091 QOF_QUERY_NAND, 00092 QOF_QUERY_NOR, 00093 QOF_QUERY_XOR 00094 } QofQueryOp;
|
|
List of known core query data-types... Each core query type defines it's set of optional "comparitor qualifiers". Definition at line 63 of file qofquerycore.h. 00063 { 00064 QOF_STRING_MATCH_NORMAL = 1, 00065 QOF_STRING_MATCH_CASEINSENSITIVE 00066 } QofStringMatch;
|