kexi

KexiDB::QuerySchema Class Reference

#include <queryschema.h>

Inheritance diagram for KexiDB::QuerySchema:

KexiDB::FieldList KexiDB::SchemaData List of all members.

Detailed Description

KexiDB::QuerySchema provides information about database query that can be executed using SQL database engine.

Definition at line 77 of file queryschema.h.


Public Member Functions

 QuerySchema ()
 QuerySchema (TableSchema *tableSchema)
virtual ~QuerySchema ()
virtual FieldListinsertField (uint position, Field *field)
FieldListinsertField (uint position, Field *field, bool visible)
FieldListinsertField (uint position, Field *field, int bindToTable, bool visible=true)
FieldListaddField (Field *field, bool visible=true)
FieldListaddField (Field *field, int bindToTable, bool visible=true)
virtual void removeField (Field *field)
bool isColumnVisible (uint position) const
void setColumnVisible (uint position, bool v)
FieldListaddAsterisk (QueryAsterisk *asterisk, bool visible=true)
virtual void clear ()
virtual QString debugString ()
Connectionconnection () const
TableSchemamasterTable () const
void setMasterTable (TableSchema *table)
TableSchema::Listtables () const
void addTable (TableSchema *table, const QCString &alias=QCString())
void removeTable (TableSchema *table)
TableSchematable (const QString &tableName) const
bool contains (TableSchema *table) const
FieldfindTableField (const QString &tableDotFieldName) const
QCString columnAlias (uint position) const
bool hasColumnAlias (uint position) const
void setColumnAlias (uint position, const QCString &alias)
int tableBoundToColumn (uint columnPosition) const
QCString tableAlias (uint position) const
int tablePositionForAlias (const QCString &name) const
int tablePosition (const QString &tableName) const
QValueList< int > tablePositions (const QString &tableName) const
bool hasTableAlias (uint position) const
int columnPositionForAlias (const QCString &name) const
void setTableAlias (uint position, const QCString &alias)
Relationship::Listrelationships () const
RelationshipaddRelationship (Field *field1, Field *field2)
Field::Listasterisks () const
virtual Fieldfield (const QString &name)
QueryColumnInfocolumnInfo (const QString &name)
QueryColumnInfo::Vector fieldsExpanded (bool unique=false)
QMap< QueryColumnInfo *, int > fieldsOrder ()
QValueVector< int > pkeyFieldsOrder ()
uint pkeyFieldsCount ()
QueryColumnInfo::ListautoIncrementFields ()
QString statement () const
void setStatement (const QString &s)
QString autoIncrementSQLFieldsList (Driver *driver)
void setWhereExpression (BaseExpr *expr)
BaseExprwhereExpression () const
void addToWhereExpression (KexiDB::Field *field, const QVariant &value, int relation= '=')
void setOrderByColumnList (const QStringList &columnNames)
void setOrderByColumnList (const QString &column1, const QString &column2=QString::null, const QString &column3=QString::null, const QString &column4=QString::null, const QString &column5=QString::null)
QueryColumnInfo::Vector orderByColumnList () const

Static Public Member Functions

static QString sqlColumnsList (QueryColumnInfo::List *infolist, Driver *driver)

Protected Member Functions

void init ()
void computeFieldsExpanded ()

Protected Attributes

QuerySchemaPrivate * d

Friends

class Connection
class QuerySchemaPrivate

Constructor & Destructor Documentation

QuerySchema::QuerySchema  ) 
 

Creates empty query object (without columns).

Definition at line 269 of file queryschema.cpp.

QuerySchema::QuerySchema TableSchema tableSchema  ) 
 

Creates query schema object that is equivalent to "SELECT * FROM table" sql command. Schema of table is used to contruct this query -- it is defined just by defining "all-tables query asterisk" (see QueryAsterisk) item. Properties such as the name and caption of the query are inherited from table schema.

We consider that query schema based on table is not (a least yet) stored in a system table, so query connection is set to NULL (even if tableSchema's connection is not NULL). Id of the created query is set to 0.

Definition at line 277 of file queryschema.cpp.


Member Function Documentation

FieldList & QuerySchema::addAsterisk QueryAsterisk asterisk,
bool  visible = true
 

Adds asterisk at the and of columns list.

Definition at line 445 of file queryschema.cpp.

KexiDB::FieldList & QuerySchema::addField Field field,
int  bindToTable,
bool  visible = true
 

Adds field to the columns list. Also binds to a table at bindToTable position. Use bindToTable==-1 if no table should be bound.

See also:
insertField()

tableBoundToColumn(uint columnPosition)

Definition at line 416 of file queryschema.cpp.

KexiDB::FieldList & QuerySchema::addField Field field,
bool  visible = true
 

Adds field to the columns list.

See also:
insertField()

Definition at line 411 of file queryschema.cpp.

Relationship * QuerySchema::addRelationship Field field1,
Field field2
 

Adds a new relationship defined by field1 and field2. Both fields should belong to two different tables of this query. This is convenience function useful for a typical cases. It automatically creates Relationship object for this query. If one of the fields are primary keys, it will be detected and appropriate master-detail relation will be established. This functiuon does nothing if the arguments are invalid.

Definition at line 962 of file queryschema.cpp.

void QuerySchema::addTable TableSchema table,
const QCString &  alias = QCString()
 

Adds table schema as one of tables used in a query. if alias is not empty, it will be assigned to this table using setTableAlias(position, alias)

Definition at line 594 of file queryschema.cpp.

void QuerySchema::addToWhereExpression KexiDB::Field field,
const QVariant &  value,
int  relation = '='
 

Adds a part to WHERE expression. Simplifies creating of WHERE expression, if used instead of setWhereExpression(BaseExpr *expr).

Definition at line 1032 of file queryschema.cpp.

Field::List * QuerySchema::asterisks  )  const
 

Returns:
list of QueryAsterisk objects defined for this query

Definition at line 768 of file queryschema.cpp.

QueryColumnInfo::List * QuerySchema::autoIncrementFields  ) 
 

Returns:
a list of field infos for all auto-incremented fields from master table of this query. This result is cached for efficiency. fieldsExpanded() is used for that.

Reimplemented from KexiDB::FieldList.

Definition at line 975 of file queryschema.cpp.

QString QuerySchema::autoIncrementSQLFieldsList Driver driver  ) 
 

Returns:
cached sql list created using sqlColumnsList() on a list returned by autoIncrementFields().

Definition at line 1015 of file queryschema.cpp.

void QuerySchema::clear  )  [virtual]
 

Removes all columns and their aliases from the columns list, removes all tables and their aliases from the tables list within this query. Sets master table information to NULL. Does not destroy any objects though. Clears name and all other properties.

See also:
FieldList::clear()

Reimplemented from KexiDB::FieldList.

Definition at line 311 of file queryschema.cpp.

QCString QuerySchema::columnAlias uint  position  )  const
 

Returns:
alias of a column at position or null string If there is no alias for this column or if there is no such column within the query defined. If the column is an expression and has no alias defined, a new unique alias will be generated automatically on this call.

Definition at line 662 of file queryschema.cpp.

int QuerySchema::columnPositionForAlias const QCString &  name  )  const
 

Returns:
column position that has defined alias name. If there is no such alias, -1 is returned.

Definition at line 732 of file queryschema.cpp.

void QuerySchema::computeFieldsExpanded  )  [protected]
 

Todo:
(js): perhaps not all fields should be appended here

Definition at line 820 of file queryschema.cpp.

Connection * QuerySchema::connection  )  const
 

If query was created using a connection, returns this connection object, otherwise NULL.

Definition at line 455 of file queryschema.cpp.

bool QuerySchema::contains TableSchema table  )  const
 

Returns:
true if the query uses table.

Definition at line 646 of file queryschema.cpp.

QString QuerySchema::debugString  )  [virtual]
 

Returns:
string for debugging purposes.

Reimplemented from KexiDB::FieldList.

Definition at line 461 of file queryschema.cpp.

Field * QuerySchema::field const QString &  name  )  [virtual]
 

Returns:
field for name or 0 if no field for this name was found within the query. fieldsExpanded() method is used to lookup expanded list of the query fields, so queries with asterisks are processed well. If a field has alias defined, name is not taken into account, but only it's alias. If a field has no alias:
  • field's name is checked
  • field's table and field's name are checked in a form of "tablename.fieldname", so you can provide name of this form to avoid ambiguity.
If there are more than one fields with the same name equal to name, first-found is returned (checking is performed from first to last query field). Structures needed to compute result of this method are cached, so only first usage costs o(n) - another usages cost o(1).

Example: Let query be defined by "SELECT T.B AS X, * FROM T" statement and T is table containing fields A, B, C. Expanded list of columns for the query is: T.B AS X, T.A, T.B, T.C.

  • Calling field("B") will return a pointer to third query column (not first, because it is covered by "X" alias). Additionally, calling field("X") will return the same pointer.
  • Calling field("T.A") will return the same pointer as field("A").

Reimplemented from KexiDB::FieldList.

Definition at line 783 of file queryschema.cpp.

QueryColumnInfo::Vector QuerySchema::fieldsExpanded bool  unique = false  ) 
 

QuerySchema::fields() returns vector of fields used for the query columns, but in a case when there are asterisks defined for the query, it does not expand QueryAsterisk objects to field lists but return every asterisk as-is. This could be inconvenient when you need just a fully expanded list of fields, so this method does the work for you.

If unique is true, each field is returned in the vector only once (first found field is selected). Note however, that the same field can be returned more than once if it has attached a different alias. For example, let t is TABLE( a, b ) and let query be defined by "SELECT *, a AS alfa FROM t" statement. Either fieldsExpanded(true) and fieldsExpanded(false) will return [ a, b, a (alfa) ] list. On the other hand, for query defined by "SELECT *, a FROM t" statement, fieldsExpanded(true) will return [ a, b ] list and fieldsExpanded(false) will return [ a, b, a ] list.

By default, all fields are returned in the vector even if there are multiple occurences of one or more.

Note: You should assign the resulted vector in your space - it will be shared and implicity copied on any modification. This method's result is cached by QuerySchema object.

Todo:
js: UPDATE CACHE!

Definition at line 796 of file queryschema.cpp.

QMap< QueryColumnInfo *, int > QuerySchema::fieldsOrder  ) 
 

Returns:
a map for fast lookup of query columns' order. This is exactly opposite information compared to vector returned by fieldsExpanded(). This method's result is cached by QuerySchema object.
Todo:
js: UPDATE CACHE!

Definition at line 915 of file queryschema.cpp.

Field * QuerySchema::findTableField const QString &  tableDotFieldName  )  const
 

Convenience function.

Returns:
table field by searching through all tables in this query. The field does not need to be included on the list of query columns. Similarly, query aliases are not taken into account.
tableDotFieldName string must contain table name and field name with '.' character between them, e.g. "mytable.myfield". 0 is returned if the query has no such table defined of the table has no such field defined.

QuerySchema::table("mytable")->field("myfield") could be alternative for findTableField("mytable.myfield") but it can crash if "mytable" is not defined in the query.

Definition at line 651 of file queryschema.cpp.

bool QuerySchema::hasColumnAlias uint  position  )  const
 

Provided for convenience.

Returns:
true if a column at position has non empty alias defined within the query. If there is no alias for this column, or if there is no such column in the query defined, false is returned.

Definition at line 668 of file queryschema.cpp.

bool QuerySchema::hasTableAlias uint  position  )  const
 

Provided for convenience.

Returns:
true if a table at position (within FROM section of the the query) has non empty alias defined. If there is no alias for this table, or if there is no such table in the query defined, false is returned.

Definition at line 727 of file queryschema.cpp.

FieldList & QuerySchema::insertField uint  position,
Field field
[virtual]
 

Inserts field to the columns list at position. Inserted field will not be owned by this QuerySchema object, but still by corresponding TableSchema.

As field object you can also pass KexiDB::QueryAsterisk, (see QueryAsterisk class description).

Note: After inserting a field, corresponding table will be automatically added to query's tables list if it is not present there (see tables()). Field must have its table assigned.

Added field will be visible. Use insertField(position, field, false) to add invisible field.

Reimplemented from KexiDB::FieldList.

Definition at line 324 of file queryschema.cpp.

bool QuerySchema::isColumnVisible uint  position  )  const
 

Returns:
visibility flag for column at position. By default column is visible.

Definition at line 434 of file queryschema.cpp.

TableSchema * QuerySchema::masterTable  )  const
 

Returns:
table that is master to this query. All potentially-editable columns within this query belong just to this table. This method also can return NULL if there are no tables at all, or if previously assigned master table schema has been removed with removeTable(). Every query that has at least one table defined, should have assigned a master table. If no master table is assigned explicitym but this method there is only one table used for this query even if there are table aliases, a single table is returned here. (e.g. "T" table is returned for "SELECT T1.A, T2.B FROM T T1, T T2" statement).

Definition at line 563 of file queryschema.cpp.

QueryColumnInfo::Vector QuerySchema::orderByColumnList  )  const
 

Returns:
a list of columns contained in ORDER BY section of the query.
See also:
setOrderBy(const QStringList&)

Definition at line 1112 of file queryschema.cpp.

uint QuerySchema::pkeyFieldsCount  ) 
 

Returns:
number of master table's primary key fields included in this query. This method is useful to quickly check whether the vector returned by pkeyFieldsOrder() if filled completely.
User e.g. in Connection::updateRow() to check if entire primary key information is specified.

Examples: let table T has (ID1 INTEGER, ID2 INTEGER, A INTEGER) fields, and let (ID1, ID2) is T's primary key.

  1. The query defined by "SELECT * FROM T" statement contains all T's primary key's fields as T is the master table, and thus pkeyFieldsCount() will return 2 (both primary key's fields are in the fieldsExpanded() list), and pkeyFieldsOrder() will return vector {0, 1}.
  2. The query defined by "SELECT A, ID2 FROM T" statement, and thus pkeyFieldsCount() will return 1 (only one primary key's field is in the fieldsExpanded() list), and pkeyFieldsOrder() will return vector {-1, 1}, as second primary key's field is at position #1 and first field is not specified at all within the query.

Definition at line 956 of file queryschema.cpp.

QValueVector< int > QuerySchema::pkeyFieldsOrder  ) 
 

Returns:
table describing order of primary key (PKEY) fields within the query. Indexing is performed against vector returned by fieldsExpanded(). It is usable for e.g. Conenction::updateRow(), when we need to locate each primary key's field in a constant time.
Returned vector is owned and cached by QuerySchema object. When you assign it, it is implicity shared. Its size is equal to number of primary key fields defined for master table (masterTable()->primaryKey()->fieldCount()).

Each element of the returned vector:

If there are more than one primary key's field included in the query, only first-found column (oin the fieldsExpanded() list) for each pkey's field is included.

Returns empty vector if there is no master table or no master table's pkey.

See also:
example for pkeyFieldsCount().
Todo:
js: UPDATE CACHE!

Definition at line 922 of file queryschema.cpp.

Relationship::List * QuerySchema::relationships  )  const
 

Returns:
a list of relationships defined for this query

Definition at line 763 of file queryschema.cpp.

void QuerySchema::removeField Field field  )  [virtual]
 

Removes field from the columns list. Use with care.

Reimplemented from KexiDB::FieldList.

Definition at line 422 of file queryschema.cpp.

void QuerySchema::removeTable TableSchema table  ) 
 

Removes table schema from this query. This does not destroy table object but only takes it out of the list. If this table was master for the query, master table information is also invalidated.

Definition at line 626 of file queryschema.cpp.

void QuerySchema::setColumnAlias uint  position,
const QCString &  alias
 

Sets alias for a column at position, within the query. Passing empty string to alias clears alias for a given column.

Definition at line 673 of file queryschema.cpp.

void QuerySchema::setColumnVisible uint  position,
bool  v
 

Sets visibility flag for column at position to v.

Definition at line 439 of file queryschema.cpp.

void QuerySchema::setMasterTable TableSchema table  ) 
 

Sets master table of this query to table. This table should be also added to query's tables list using addTable(). If table equals NULL, nothing is performed.

See also:
masterTable()

Definition at line 583 of file queryschema.cpp.

void QuerySchema::setOrderByColumnList const QString &  column1,
const QString &  column2 = QString::null,
const QString &  column3 = QString::null,
const QString &  column4 = QString::null,
const QString &  column5 = QString::null
 

Convenience method, similar to setOrderByColumnList(const QStringList&).

Definition at line 1100 of file queryschema.cpp.

void QuerySchema::setOrderByColumnList const QStringList &  columnNames  ) 
 

Sets a list of columns for ORDER BY section of the query. Each name on the list must be a field or alias present within the query and must not be covered by aliases. If one or more names cannot be found within the query, the method will have no effect. Any previous ORDER BY settings will be removed.

Definition at line 1088 of file queryschema.cpp.

void QuerySchema::setStatement const QString &  s  ) 
 

Forces a query statement (i.e. no statement is composed from QuerySchema's content)

Definition at line 778 of file queryschema.cpp.

void QuerySchema::setTableAlias uint  position,
const QCString &  alias
 

Sets alias for a table at position (within FROM section of the the query). Passing empty sting to alias clears alias for a given table (only for specified position).

Definition at line 740 of file queryschema.cpp.

void QuerySchema::setWhereExpression BaseExpr expr  ) 
 

Sets a WHERE expression exp. It will be owned by this query, so you can forget about it. Previously set WHERE expression will be deleted. You can pass 0 to remove expresssion.

Definition at line 1026 of file queryschema.cpp.

QString QuerySchema::sqlColumnsList QueryColumnInfo::List infolist,
Driver driver
[static]
 

Returns:
a string that is a result of concatenating all column names for infolist, with "," between each one. This is usable e.g. as argument like "field1,field2" for "INSERT INTO (xxx) ..". The result of this method is effectively cached, and it is invalidated when set of fields changes (e.g. using clear() or addField()).
This method is similar to FieldList::sqlFieldsList() it just uses QueryColumnInfo::List instead of Field::List.

Definition at line 997 of file queryschema.cpp.

QString QuerySchema::statement  )  const
 

Returns:
a preset statement (if any).

Definition at line 773 of file queryschema.cpp.

TableSchema * QuerySchema::table const QString &  tableName  )  const
 

Returns:
table with name tableName or 0 if this query has no such table.

Definition at line 636 of file queryschema.cpp.

QCString QuerySchema::tableAlias uint  position  )  const
 

Returns:
alias of a table at position (within FROM section) or null string if there is no alias for this table or if there is no such table within the query defined.

Definition at line 690 of file queryschema.cpp.

int QuerySchema::tableBoundToColumn uint  columnPosition  )  const
 

Returns:
a table position (within FROM section), that is bound to column at columnPosition (within SELECT section). This information can be used to find if there is alias defined for a table that is referenced by a given column.
For example, for "SELECT t2.id FROM table1 t1, table2 t2" query statement, columnBoundToTable(0) returns 1, what means that table at position 1 (within FROM section) is bound to column at position 0, so we can now call tableAlias(1) to see if we have used alias for this column (t2.d) or just a table name (table2.d).

These checkings are performed e.g. by Connection::queryStatement() to construct a statement string maximally identical to originally defined query statement.

-1 is returned if:

  • columnPosition is out of range (i.e. < 0 or >= fieldCount())
  • a column at columnPosition is not bound to any table (i.e. no database field is used for this column, e.g. "1" constant for "SELECT 1 from table" query statement)

Definition at line 401 of file queryschema.cpp.

int QuerySchema::tablePosition const QString &  tableName  )  const
 

Returns:
table position (within FROM section) for tableName. -1 is returend if there's no such table declared in the FROM section.
See also:
tablePositions()

Definition at line 704 of file queryschema.cpp.

int QuerySchema::tablePositionForAlias const QCString &  name  )  const
 

Returns:
table position (within FROM section) that has attached alias name. If there is no such alias, -1 is returned. Only first table's position attached for this alias is returned. It is not especially bad, since aliases rarely can be duplicated, what leads to ambiguity. Duplicated aliases are only allowed for trivial queries that have no database fields used within their columns, e.g. "SELECT 1 from table1 t, table2 t" is ok but "SELECT t.id from table1 t, table2 t" is not.

Definition at line 696 of file queryschema.cpp.

QValueList< int > QuerySchema::tablePositions const QString &  tableName  )  const
 

Returns:
a list of all tableName table occurences (within FROM section). E.g. for "SELECT * FROM table t, table t2" [0, 1] list is returned. Empty list is returned there's no such table declared in the FROM section at all.
See also:
tablePosition()

Definition at line 714 of file queryschema.cpp.

TableSchema::List * QuerySchema::tables  )  const
 

Returns:
list of tables used in a query. This also includes master table.
See also:
masterTable()

Definition at line 589 of file queryschema.cpp.

BaseExpr * QuerySchema::whereExpression  )  const
 

Returns:
WHERE expression or 0 if this query has no WHERE expression

Definition at line 1083 of file queryschema.cpp.


Member Data Documentation

QuerySchemaPrivate* KexiDB::QuerySchema::d [protected]
 

Automatically retrieves query schema via connection.

Definition at line 502 of file queryschema.h.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys