Query: Querying for Objects
[Query Object Framework]


Detailed Description

BASIC QUERY API: With this API you can create arbitrary logical queries to find sets of arbitrary object. To make simple queries (1 term, such as a search for a parameter with one value), create the appropriate QueryTerm structure and stick it in a Query object using xaccInitQuery. The QueryTerm should be malloced but the Query object will handle freeing it. To make compound queries, make multiple simple queries and combine them using qof_query_merge() and the logical operations of your choice.

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 }


Define Documentation

#define QOF_PARAM_BOOK   "book"
 

"Known" Object Parameters -- all objects must support these

Definition at line 103 of file qofquery.h.

#define QOF_PARAM_KVP   "kvp"
 

"Known" Object Parameters -- some objects might support these

Definition at line 107 of file qofquery.h.

#define QOF_QUERY_FIRST_TERM   QOF_QUERY_AND
 

First/only term is same as 'and'

Definition at line 97 of file qofquery.h.

#define QUERY_DEFAULT_SORT   "QofQueryDefaultSort"
 

Default sort object type

Definition at line 100 of file qofquery.h.


Typedef Documentation

typedef struct _QofQuery QofQuery
 

A Query

Definition at line 85 of file qofquery.h.

typedef struct _QofQueryPredData QofQueryPredData
 

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.


Enumeration Type Documentation

enum QofCharMatch
 

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;

enum QofDateMatch
 

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;

enum QofGuidMatch
 

Enumerator:
QOF_GUID_MATCH_ANY  These expect a single object and expect the QofAccessFunc returns GUID*
QOF_GUID_MATCH_ALL  These expect a GList* of objects and calls the QofAccessFunc routine on each item in the list to obtain a GUID* for each object
QOF_GUID_MATCH_LIST_ANY  These expect a single object and expect the QofAccessFunc function to return a GList* of GUID* (the list is the property of the caller)

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;

enum QofNumericMatch
 

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;

enum QofQueryCompare
 

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;

enum QofQueryOp
 

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;

enum QofStringMatch
 

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;


Generated on Fri May 12 18:00:35 2006 for QOF by  doxygen 1.4.4