# class Query | Representation of a stored query. More...
Full name | `KDB::Query`
Definition | `#include <query.h>`
Inherits | KDB::DataObject [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

- enum QueryType { Select, Insert, Update, Delete }
- enum ConditionType { And, Or }

#### Public Methods

- ~Query ()
- void setType (QueryType type)
- QueryType type () const
- ParameterList parameters () const
- void setParameter (const QString &prop, const QString &value)
- QString parameter (const QString &prop) const
- bool addField (const QString &table, const QString &name, const QString &value = QString::null, const QString &aggregate = QString::null)
- void removeField ( const QString & table, const QString &name )
- FldList fields () const
- QString addTable (const QString &name, const QString & alias = QString::null)
- void removeTable (const QString &alias)
- QStringList tables ()
- QString tableName (const QString & alias)
- void addCondition (const QString &condition, ConditionType type = And, int level = 0)
- void removeCondition (const QString &condition, int level = 0)
- CondList conditions ()
- QString SQL ()
- KDB_ULONG execute ()
- virtual RecordsetPtr openRecordset ()
- void save ()
- void clear ()
- bool isDirty ()

#### Signals

- void definitionChanged ()
- void created (Query *)

#### Protected Methods

- Query ( Connector * conn, QObject *parent = 0L, const char *name = 0L, const QString &sql = QString::null )
- virtual QString buildSQL ()

## Detailed Description

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

- Version: kdbcore 0.0.2
- Author: Alessandro Praduroux <pradu@thekompany.com>
- Generated: root@i386.ports.openbsd.org on Wed Apr 25 13:59:09 2001, using kdoc 2.0a53.