|
|
Representation of a stored query.
Through this object we access the fields and parameters of the query, if any.
Each query is stored in the database as an XML definition. This definition will contain the list of fields, calculated fields (not implemented yet), tables, filters - join expressions and parameters. One exception to that is done when the query is built using an SQL expression in Database::newQuery . In this case, the SQL is stored.
Queries are of two types: select queries and command queries. Select queries can be used to obtain a recordset using openRecordset , while command queries are executed using execute . Command queries have different types: Update, Insert, Delete. By default, a newly built query is a Select query. You can change the query type using setType
Queries can be parametrized. While building the query, the user can use the special construct %name, and provide a corresponding value using the setParameter call. Before the execution (through openRecordset or execute ), a parameter substitution is done. When there is no corresponding parameter value, the %xxx keyword is removed. This can lead to incorrect SQL. Parameter substitution is done on the complete SQL statement, allowing creation of queries that access data with similar definition in different tables with only one query definition.
enum QueryType { Select, Insert, Update, Delete } | QueryType |
The type of query. Select queries can be executed using openRecordset, while command queries through execute. the opposite will generate an error.
enum ConditionType { And, Or } | ConditionType |
Type of conditional expression.
~Query ()
| ~Query |
void setType (QueryType type)
| setType |
Sets the query type.
QueryType type ()
| type |
[const]
Returns the query type
ParameterList parameters ()
| parameters |
[const]
Return the list of known properties. This is a QDict<char> where the keys are the parameter names and the items are the parameter values
void setParameter (const QString &prop, const QString &value)
| setParameter |
Set the value of a parameter
QString parameter (const QString &prop)
| parameter |
[const]
Return the actual value of a parameter
bool addField (const QString &table,
const QString &name,
const QString &value = QString::null,
const QString &aggregate = QString::null)
| addField |
Append a new field to the field list of the query. WARNING! aggregate functions aren't yet supported. The sig is here but the SQL ignores aggregates.
Parameters:
table | The table to which this field belongs. Ignored for command queries. |
name | The name of the field |
aggregate | The aggregate function to apply to this field |
value | The value this field should get (useful only for update and insert queries, ignored otherwhise). |
Returns: true if the field has been appended, false oterwise
void removeField ( const QString & table, const QString &name )
| removeField |
Remove a field from the list of fields
FldList fields ()
| fields |
[const]
Returns the list of fields
QString addTable (const QString &name, const QString & alias = QString::null)
| addTable |
Add a table to the existing list of tables. For insert, update and delete queries only the first table is taken into consideration. All others will be discarded silently. If this table is already present in the table list, and an alias isn't supplied, it will be created based on the table name.
Returns: the alias of the table added.
void removeTable (const QString &alias)
| removeTable |
Remove a table from the list of tables, by alias. This will also remove all fields for the removed table
QStringList tables ()
| tables |
Return the list of table aliases.
QString tableName (const QString & alias)
| tableName |
given an alias, retrieve the corresponding table name
void addCondition (const QString &condition, ConditionType type = And, int level = 0)
| addCondition |
Add a condition to the query. Ignored for insert queries.
Conditions can be nested to an arbitrary level. Proper use of the level parameter can lead to complex conditional expressions.
for example:
qry->addCondition("A = B", And, 0); qry->addCondition("B = C", And, 1); qry->addCondition("C = D", Or, 2); qry->addCondition("E = C", And, 2); qry->addCondition("F = A", And, 0); |
will lead to the following SQL condition:
WHERE A = B AND (B = C OR (C = D AND E = C ) ) AND F = A |
Parameters:
condition | The condition without 'where', 'and', or parenthesis. Something like "table1.field1 is null" or "table1.field1 = table2.field1" |
type | Wether the condition should be ANDed or ORed with other same level conditions |
level | The nesting level of the condition |
void removeCondition (const QString &condition, int level = 0)
| removeCondition |
Remove a condition from the query. It will be removed the first condition that matches
CondList conditions ()
| conditions |
Return a list of conditions
QString SQL ()
| SQL |
Return the SQL code associated to the query. The statement is computed on the fly using the stored definition, and parameter parsing is performed.
KDB_ULONG execute ()
| execute |
Executes a command query, and return the number of rows affected by this query. If called on a select query, it will fail and generate an error.
RecordsetPtr openRecordset ()
| openRecordset |
[virtual]
Creates a recordset based on this query. If called on a command query, it will fail and generate an error.
void save ()
| save |
Saves the query into the database as XML definition or SQL, depending on how it is created
void clear ()
| clear |
Clear the content of all list (parameters, fields, tables) and the SQL
bool isDirty ()
| isDirty |
Return true if the query has been modified somewhat
void definitionChanged ()
| definitionChanged |
[signal]
This signal is emitted whenever the definition of the query changes. That means a field or table or condition is added or removed
void created (Query *)
| created |
[signal]
This signal is emitted once when the query is saved the first time into the database. It is used by Database to add the query name to the list of database queries
Query ( Connector * conn, QObject *parent = 0L, const char *name = 0L, const QString &sql = QString::null )
| Query |
[protected]
QString buildSQL ()
| buildSQL |
[protected virtual]
This function will create the SQL string to pass to the DBMS engine. It can be overridden by special types of queries ?? dunno if it will help