KDb

KDbQuerySchema.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2017 JarosÅ‚aw Staniek <[email protected]>
3 
4  This library is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License as published by the Free Software Foundation; either
7  version 2 of the License, or (at your option) any later version.
8 
9  This library is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  Library General Public License for more details.
13 
14  You should have received a copy of the GNU Library General Public License
15  along with this library; see the file COPYING.LIB. If not, write to
16  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18 */
19 
20 #ifndef KDB_QUERYSCHEMA_H
21 #define KDB_QUERYSCHEMA_H
22 
23 #include <QVector>
24 #include <QHash>
25 
26 #include "KDbFieldList.h"
27 #include "KDbObject.h"
28 #include "KDbQueryColumnInfo.h"
29 #include "KDbToken.h"
30 
31 class KDbConnection;
32 class KDbOrderByColumn;
34 class KDbQueryAsterisk;
35 class KDbQuerySchemaFieldsExpanded;
37 class KDbQuerySchemaPrivate;
38 class KDbRelationship;
39 class KDbTableSchema;
40 
41 //! @short KDbQuerySchema provides information about database query
42 /*! The query that can be executed using KDb-compatible SQL database engine
43  or used as an introspection tool. KDb parser builds KDbQuerySchema objects
44  by parsing SQL statements. */
45 class KDB_EXPORT KDbQuerySchema : public KDbFieldList, public KDbObject
46 {
47 public:
48  /*! Creates empty query object (without columns). */
50 
51  /*! Creates query schema object that is equivalent to "SELECT * FROM table"
52  sql command. Schema of @a table is used to contruct this query --
53  it is defined by just adding all the fields to the query in natural order.
54  To avoid problems (e.g. with fields added outside of Kexi using ALTER TABLE)
55  we do not use "all-tables query asterisk" (see KDbQueryAsterisk) item to achieve
56  this effect.
57 
58  Properties such as the name and caption of the query are inherited
59  from table schema.
60 
61  We consider that query schema based on @a table is not (a least yet) stored
62  in a system table, so query connection is set to @c nullptr
63  (even if @a tableSchema's connection is not @c nullptr).
64  Id of the created query is set to 0. */
65  explicit KDbQuerySchema(KDbTableSchema *tableSchema);
66 
67  /*! Copy constructor. Creates deep copy of @a querySchema.
68  KDbQueryAsterisk objects are deeply copied while only pointers to KDbField objects are copied. */
69  KDbQuerySchema(const KDbQuerySchema& querySchema, KDbConnection *conn);
70 
71  ~KDbQuerySchema() override;
72 
73  /*! Inserts @a field to the columns list at @a position.
74  Inserted field will not be owned by this KDbQuerySchema object,
75  but by the corresponding KDbTableSchema.
76 
77  KDbQueryAsterisk can be also passed as @a field. See the KDbQueryAsterisk class
78  description.
79 
80  @note After inserting a field, corresponding table will be automatically
81  added to query's tables list if it is not present there (see tables()).
82  KDbField must have its table assigned.
83 
84  The inserted field will be visible. Use insertInvisibleField(position, field)
85  to add an invisible field.
86 
87  The field is not bound to any particular table within the query.
88  */
89  bool insertField(int position, KDbField *field) override;
90 
91  /**
92  * @overload bool insertField(int position, KDbField *field)
93  * Inserts @a field to the columns list at @a position.
94  * @a bindToTable is a table index within the query for which the field should be bound.
95  * If @a bindToTable is -1, no particular table will be bound.
96  * @see tableBoundToColumn(int columnPosition)
97  */
98  bool insertField(int position, KDbField *field, int bindToTable);
99 
100  /**
101  * @overload bool insertField(int position, KDbField *field)
102  * Inserts @a field to the columns list at @a position.
103  * In addition sets field's visibility to @c false. It will not be bound to any table in this query.
104  * @since 3.1
105  */
106  bool insertInvisibleField(int position, KDbField *field);
107 
108  /**
109  * @overload bool insertInvisibleField(int position, KDbField *field)
110  * Inserts @a field to the columns list at @a position.
111  * In addition sets field's visibility to @c false.
112  * @a bindToTable is a table index within the query for which the field should be bound.
113  * If @a bindToTable is -1, no particular table will be bound.
114  * @see tableBoundToColumn(int columnPosition)
115  * @since 3.1
116  */
117  bool insertInvisibleField(int position, KDbField *field, int bindToTable);
118 
119  /**
120  * Appends @a field to the columns list.
121  * The field will be visible. Use addInvisibleField(field) to add an invisible field.
122  * The field is not bound to any particular table within the query.
123  * @see insertField()
124  */
125  bool addField(KDbField* field);
126 
127  /*! Appends @a field to the columns list. Also binds to a table at @a bindToTable position.
128  * Use bindToTable==-1 if no table should be bound.
129  * The field will be visible. Use addInvisibleField(field, bindToTable) to add
130  * an invisible field.
131  * @see insertField()
132  * @see tableBoundToColumn(int columnPosition)
133  */
134  bool addField(KDbField* field, int bindToTable);
135 
136  /**
137  * @overload bool addField(KDbField* field)
138  * Appends @a field to the columns list.
139  * The field is not bound to any particular table within the query.
140  * In addition sets field's visibility to @c false. It will not be bound to any table in this query.
141  * @since 3.1
142  */
143  bool addInvisibleField(KDbField* field);
144 
145  /**
146  * @overload bool addField(KDbField* field, int bindToTable)
147  * Appends @a field to the columns list. Also binds to a table at @a bindToTable position.
148  * In addition sets field's visibility to @c false.
149  * @see tableBoundToColumn(int columnPosition)
150  * @since 3.1
151  */
152  bool addInvisibleField(KDbField* field, int bindToTable);
153 
154  /*! Removes field from the columns list. Use with care. */
155  bool removeField(KDbField *field) override;
156 
157  /**
158  * Appends a column built on top of @a expr expression.
159  * This creates a new KDbField object and adds it to the query schema using addField().
160  */
161  bool addExpression(const KDbExpression& expr);
162 
163  /**
164  * @overload bool addExpression(const KDbExpression& expr)
165  * Appends a column built on top of @a expr expression.
166  * In addition sets column's visibility to @c false.
167  * @since 3.1
168  */
169  bool addInvisibleExpression(const KDbExpression& expr);
170 
171  /*! @return visibility flag for column at @a position.
172  By default column is visible. */
173  bool isColumnVisible(int position) const;
174 
175  //! Sets visibility flag for column at @a position to @a visible.
176  void setColumnVisible(int position, bool visible);
177 
178  /*! Appends @a asterisk at the and of columns list. */
179  bool addAsterisk(KDbQueryAsterisk *asterisk);
180 
181  /**
182  * @overload bool addAsterisk(KDbQueryAsterisk *asterisk)
183  * Appends @a asterisk at the and of columns list.
184  * Sets the asterisk as invisible.
185  * @since 3.1
186  */
187  bool addInvisibleAsterisk(KDbQueryAsterisk *asterisk);
188 
189  /*! Removes all columns and their aliases from the columns list,
190  removes all tables and their aliases from the tables list within this query.
191  Sets master table information to @c nullptr.
192  Does not destroy any objects though. Clears name and all other properties.
193  @see KDbFieldList::clear() */
194  void clear() override;
195 
196  /*! @return table that is master to this query.
197  All potentially-editable columns within this query belong just to this table.
198  This method also can return @c nullptr if there are no tables at all,
199  or if previously assigned master table schema has been removed
200  with removeTable().
201  Every query that has at least one table defined, should have
202  assigned a master table.
203  If no master table is assigned explicitly, but only one table used in this query,
204  a single table is returned here, even if there are table aliases,
205  (e.g. "T" table is returned for "SELECT T1.A, T2.B FROM T T1, T T2" statement). */
206  KDbTableSchema* masterTable() const;
207 
208  /*! Sets master table of this query to @a table.
209  This table should be also added to query's tables list
210  using addTable(). If @a table equals @c nullptr, nothing is performed.
211  @see masterTable() */
212  void setMasterTable(KDbTableSchema *table);
213 
214  /*! @return list of tables used in this query.
215  It is never @c nullptr. The list also includes master table.
216  @see masterTable() */
217  QList<KDbTableSchema*>* tables() const;
218 
219  /*! Appends @a table schema as one of tables used in a query.
220  If @a alias is not empty, it will be assigned to this table
221  using setTableAlias(position, alias). */
222  void addTable(KDbTableSchema *table, const QString& alias = QString());
223 
224  /*! Removes @a table schema from this query.
225  This does not destroy @a table object but only takes it out of the list.
226  If this table was master for the query, master table information is also
227  invalidated. */
228  void removeTable(KDbTableSchema *table);
229 
230  /*! @return table with name @a tableName or 0 if this query has no such table. */
231  KDbTableSchema* table(const QString& tableName) const;
232 
233  /*! @return @c true if the query uses @a table. */
234  bool contains(KDbTableSchema *table) const;
235 
236  /*! Convenience function.
237  @return table field by searching through all tables in this query.
238  The field does not need to be included on the list of query columns.
239  Similarly, query aliases are not taken into account.
240 
241  @a fieldOrTableAndFieldName string may contain table name and field name
242  with '.' character between them, e.g. "mytable.myfield".
243  This is recommended way to avoid ambiguity.
244  0 is returned if the query has no such
245  table defined of the table has no such field defined.
246  If you do not provide a table name, the first field found is returned.
247 
248  KDbQuerySchema::table("mytable")->field("myfield") could be
249  alternative for findTableField("mytable.myfield") but it can crash
250  if "mytable" is not defined in the query.
251 
252  @see KDb::splitToTableAndFieldParts()
253  */
254  KDbField* findTableField(const QString &fieldOrTableAndFieldName) const;
255 
256  /*! @return alias of a column at @a position or empty string if there is no alias for this column
257  or if there is no such column within the query defined. If the column is an expression and has
258  no alias defined, a new unique alias will be generated automatically on this call.
259  */
260  QString columnAlias(int position) const;
261 
262  /*! @return number of column aliases */
263  int columnAliasesCount() const;
264 
265  /*! Provided for convenience.
266  @return @c true if a column at @a position has non empty alias defined
267  within the query.
268  If there is no alias for this column,
269  or if there is no such column in the query defined, @c false is returned. */
270  bool hasColumnAlias(int position) const;
271 
272  /*! Sets @a alias for a column at @a position, within the query.
273  Passing empty string to @a alias clears alias for a given column. */
274  bool setColumnAlias(int position, const QString& alias);
275 
276  /*! @return a table position (within FROM section),
277  that is bound to column at @a columnPosition (within SELECT section).
278  This information can be used to find if there is alias defined for
279  a table that is referenced by a given column.
280 
281  For example, for "SELECT t2.id FROM table1 t1, table2 t2" query statement,
282  columnBoundToTable(0) returns 1, what means that table at position 1
283  (within FROM section) is bound to column at position 0, so we can
284  now call tableAlias(1) to see if we have used alias for this column (t2.id)
285  or just a table name (table2.id).
286 
287  These checks are performed e.g. by KDbConnection::selectStatement()
288  to construct a statement string maximally identical to originally
289  defined query statement.
290 
291  -1 is returned if:
292  - @a columnPosition is out of range (i.e. < 0 or >= fieldCount())
293  - a column at @a columnPosition is not bound to any table (i.e.
294  no database field is used for this column,
295  e.g. "1" constant for "SELECT 1 from table" query statement)
296  */
297  int tableBoundToColumn(int columnPosition) const;
298 
299  /*! @return number of table aliases */
300  int tableAliasesCount() const;
301 
302  /*! @return alias of a table at @a position (within FROM section)
303  or null string if there is no alias for this table
304  or if there is no such table within the query defined. */
305  QString tableAlias(int position) const;
306 
307  /*! @return alias of a table @a tableName (within FROM section)
308  or empty value if there is no alias for this table
309  or if there is no such table within the query defined. */
310  QString tableAlias(const QString& tableName) const;
311 
312  /*! @return alias of a table @a tableName (within FROM section).
313  If there is no alias for this table, its name is returned.
314  Empty value is returned if there is no such table within the query defined. */
315  QString tableAliasOrName(const QString& tableName) const;
316 
317  /*! @return table position (within FROM section) that has attached
318  alias @a name.
319  If there is no such alias, -1 is returned.
320  Only first table's position attached for this alias is returned.
321  It is not especially bad, since aliases rarely can be duplicated,
322  what leads to ambiguity.
323  Duplicated aliases are only allowed for trivial queries that have
324  no database fields used within their columns,
325  e.g. "SELECT 1 from table1 t, table2 t" is ok
326  but "SELECT t.id from table1 t, table2 t" is not.
327  */
328  int tablePositionForAlias(const QString& name) const;
329 
330  /*! @return position (within the FROM section) of table @a tableName.
331  -1 is returned if there's no such table declared in the FROM section.
332  @see tablePositions()
333  */
334  int tablePosition(const QString& tableName) const;
335 
336  /*! @return a list of all occurrences of table @a tableName (within the FROM section).
337  E.g. for "SELECT * FROM table t, table t2" tablePositions("table") returns {0, 1} list.
338  Empty list is returned if there's no table @a tableName used in the FROM section at all.
339  @see tablePosition() */
340  QList<int> tablePositions(const QString& tableName) const;
341 
342  /*! Provided for convenience.
343  @return @c true if a table at @a position (within FROM section of the query)
344  has non empty alias defined.
345  If there is no alias for this table,
346  or if there is no such table in the query defined, @c false is returned. */
347  bool hasTableAlias(int position) const;
348 
349  /*! Provided for convenience.
350  @return @c true if non empty table alias @a name is defined for a table. */
351  bool hasTableAlias(const QString &name) const;
352 
353  /*! @return column position that has defined alias @a name.
354  If there is no such alias, -1 is returned. */
355  int columnPositionForAlias(const QString& name) const;
356 
357  /*! Provided for convenience.
358  @return @c true if non empty alias @a name is defined for any column. */
359  bool hasColumnAlias(const QString &name) const;
360 
361  /*! Sets @a alias for a table at @a position (within FROM section
362  of the query).
363  Passing empty sting to @a alias clears alias for a given table
364  (only for specified @a position). */
365  bool setTableAlias(int position, const QString& alias);
366 
367  /*! @return a list of relationships defined for this query.
368  It is never @c nullptr.*/
369  QList<KDbRelationship*>* relationships() const;
370 
371  /*! Appends a new relationship defined by @a field1 and @a field2.
372  Both fields should belong to two different tables of this query.
373  This is convenience function useful for a typical cases.
374  It automatically creates KDbRelationship object for this query.
375  If one of the fields are primary keys, it will be detected
376  and appropriate master-detail relation will be established.
377  This functiuon does nothing if the arguments are invalid. */
378  KDbRelationship* addRelationship(KDbField *field1, KDbField *field2);
379 
380  /*! @return list of KDbQueryAsterisk objects defined for this query.
381  It is never @c nullptr. */
382  KDbField::List* asterisks() const;
383 
384  //! Mode for field() and columnInfo()
385  //! @since 3.1
386  enum class ExpandMode {
387  Unexpanded, //!< All fields are returned even if duplicated
388  Expanded //!< Expanded list of the query fields is computed so queries with asterisks
389  //!< are processed well
390  };
391 
392  /*! @return field for @a identifier or @c nullptr if no field for this name
393  was found within the query. fieldsExpanded() method is used
394  to lookup expanded list of the query fields, so queries with asterisks
395  are processed well.
396  If a field has alias defined, name is not taken into account,
397  but only its alias. If a field has no alias:
398  - field's name is checked
399  - field's table and field's name are checked in a form of "tablename.fieldname",
400  so you can provide @a identifier in this form to avoid ambiguity.
401 
402  If there are more than one fields with the same name equal to @a identifier,
403  first-found is returned (checking is performed from first to last query field).
404  Structures needed to compute result of this method are cached,
405  so only first usage costs o(n) - another usages cost o(1).
406 
407  Example:
408  Let query be defined by "SELECT T.B AS X, T.* FROM T" statement and let T
409  be table containing fields A, B, C.
410  Expanded list of columns for the query is: T.B AS X, T.A, T.B, T.C.
411  - Calling field("B") will return a pointer to third query column (not the first,
412  because it is covered by "X" alias). Additionally, calling field("X")
413  will return the same pointer.
414  - Calling field("T.A") will return the same pointer as field("A").
415 
416  This method is also a product of inheritance from KDbFieldList.
417  */
418  const KDbField *field(KDbConnection *conn, const QString &identifier,
419  ExpandMode mode = ExpandMode::Expanded) const;
420 
421  /**
422  * @overload
423  */
424  KDbField *field(KDbConnection *conn, const QString &identifier,
425  ExpandMode mode = ExpandMode::Expanded);
426 
427  /*! @return field id or @c nullptr if there is no such a field. */
428  KDbField* field(int id) override;
429 
430  using KDbFieldList::field;
431 
432  /*! @overload KDbField* field(int id) */
433  const KDbField* field(int id) const override;
434 
435  /*! Like KDbQuerySchema::field(const QString& name) but returns not only KDbField
436  object for @a identifier but entire KDbQueryColumnInfo object.
437  @a identifier can be:
438  - a fieldname
439  - an aliasname
440  - a tablename.fieldname
441  - a tablename.aliasname
442  Note that if there are two occurrrences of the same name,
443  only the first is accessible using this method. For instance,
444  calling columnInfo("name") for "SELECT t1.name, t2.name FROM t1, t2" statement
445  will only return the column related to t1.name and not t2.name, so you'll need to
446  explicitly specify "t2.name" as the identifier to get the second column. */
447  KDbQueryColumnInfo *columnInfo(KDbConnection *conn, const QString &identifier,
448  ExpandMode mode = ExpandMode::Expanded) const;
449 
450  //! Mode for fieldsExpanded() and visibleFieldsExpanded()
451  //! @since 3.1
452  enum class FieldsExpandedMode {
453  Default, //!< All fields are returned even if duplicated
454  Unique, //!< Unique list of fields is returned
455  WithInternalFields, //!< Like Default but internal fields (for lookup) are appended
456  WithInternalFieldsAndRecordId //!< Like WithInternalFields but record ID (big int type) field
457  //!< is appended after internal fields
458  };
459 
460  /*! @return fully expanded list of fields.
461  KDbQuerySchema::fields() returns vector of fields used for the query columns,
462  but in a case when there are asterisks defined for the query,
463  it does not expand KDbQueryAsterisk objects to field lists but return every
464  asterisk as-is.
465  This could be inconvenient when you need just a fully expanded list of fields,
466  so this method does the work for you.
467 
468  If @a options is Unique, each field is returned in the vector only once
469  (first found field is selected).
470  Note however, that the same field can be returned more than once if it has attached
471  a different alias.
472  For example, let t be TABLE( a, b ) and let query be defined
473  by "SELECT *, a AS alfa FROM t" statement. Both fieldsExpanded(Default)
474  and fieldsExpanded(Unique) will return [ a, b, a (alfa) ] list.
475  On the other hand, for query defined by "SELECT *, a FROM t" statement,
476  fieldsExpanded(Default) will return [ a, b, a ] list while
477  fieldsExpanded(Unique) will return [ a, b ] list.
478 
479  If @a options is WithInternalFields or WithInternalFieldsAndRecordID,
480  additional internal fields are also appended to the vector.
481 
482  If @a options is WithInternalFieldsAndRecordId,
483  one fake BigInteger column is appended to make space for Record ID column used
484  by KDbCursor implementations. For example, let city_id in TABLE persons(surname, city_id)
485  reference cities.id in TABLE cities(id, name) and let query q be defined
486  by "SELECT * FROM persons" statement. We want to display persons' city names instead of city_id's.
487  To do this, cities.name has to be retrieved as well, so the following statement should be used:
488  "SELECT * FROM persons, cities.name LEFT OUTER JOIN cities ON persons.city_id=cities.id".
489  Thus, calling fieldsExpanded(WithInternalFieldsAndRecordId) will return 4 elements instead of 2:
490  persons.surname, persons.city_id, cities.name, {ROWID}. The {ROWID} item is the placeholder
491  used for fetching ROWID by KDb cursors.
492 
493  By default, all fields are returned in the vector even
494  if there are multiple occurrences of one or more (options == Default).
495 
496  Note: You should assign the resulted vector in your space - it will be shared
497  and implicity copied on any modification.
498  This method's result is cached by KDbQuerySchema object.
499  @todo js: UPDATE CACHE!
500  */
502  KDbConnection *conn, FieldsExpandedMode mode = FieldsExpandedMode::Default) const
503  {
504  return fieldsExpandedInternal(conn, mode, false);
505  }
506 
507  /*! Like fieldsExpanded() but returns only visible fields. */
509  KDbConnection *conn, FieldsExpandedMode options = FieldsExpandedMode::Default) const
510  {
511  return fieldsExpandedInternal(conn, options, true);
512  }
513 
514  /*! @return list of internal fields used for lookup columns. */
515  KDbQueryColumnInfo::Vector internalFields(KDbConnection *conn) const;
516 
517  /*! @return info for expanded of internal field at index @a index.
518  The returned field can be either logical or internal (for lookup),
519  the latter case is @c true if @a index &gt;= fieldsExpanded().count().
520  Equivalent of KDbQuerySchema::fieldsExpanded(WithInternalFields).at(index). */
521  KDbQueryColumnInfo* expandedOrInternalField(KDbConnection *conn, int index) const;
522 
523  //! Mode for columnsOrder()
524  //! @since 3.1
525  enum class ColumnsOrderMode {
526  UnexpandedList, //!< A map for unexpanded list is created
527  UnexpandedListWithoutAsterisks, //!< A map for unexpanded list is created, with asterisks skipped
528  ExpandedList //!< A map for expanded list is created
529  };
530 
531  /*! @return a hash for fast lookup of query columns' order.
532  - If @a options is UnexpandedList, each KDbQueryColumnInfo pointer is mapped to the index
533  within (unexpanded) list of fields, i.e. "*" or "table.*" asterisks are considered
534  to be single items.
535  - If @a options is UnexpandedListWithoutAsterisks, each KDbQueryColumnInfo pointer
536  is mapped to the index within (unexpanded) list of columns that come from asterisks
537  like "*" or "table.*" are not included in the map at all.
538  - If @a options is ExpandedList (the default) this method provides is exactly opposite
539  information compared to vector returned by fieldsExpanded().
540 
541  This method's result is cached by the KDbQuerySchema object.
542  Note: indices of internal fields (see internalFields()) are also returned
543  here - in this case the index is counted as a sum of size(e) + i (where "e" is
544  the list of expanded fields and i is the column index within internal fields list).
545  This feature is used eg. at the end of KDbConnection::updateRecord() where need indices of
546  fields (including internal) to update all the values in memory.
547 
548  Example use: let t be table (int id, name text, surname text) and q be query
549  defined by a statement "select * from t".
550 
551  - columnsOrder(ExpandedList) will return the following map: KDbQueryColumnInfo(id)->0,
552  KDbQueryColumnInfo(name)->1, KDbQueryColumnInfo(surname)->2.
553  - columnsOrder(UnexpandedList) will return the following map: KDbQueryColumnInfo(id)->0,
554  KDbQueryColumnInfo(name)->0, KDbQueryColumnInfo(surname)->0 because the column
555  list is not expanded. This way you can use the returned index to get KDbField*
556  pointer using field(int) method of KDbFieldList superclass.
557  - columnsOrder(UnexpandedListWithoutAsterisks) will return the following map:
558  KDbQueryColumnInfo(id)->0,
559  */
561  ColumnsOrderMode mode = ColumnsOrderMode::ExpandedList) const;
562 
563  /*! @return table describing order of primary key (PKEY) fields within the query.
564  Indexing is performed against vector returned by fieldsExpanded().
565  It is usable for e.g. Connection::updateRecord(), when we need
566  to locate each primary key's field in a constant time.
567 
568  Returned vector is owned and cached by KDbQuerySchema object. When you assign it,
569  it is implicity shared. Its size is equal to number of primary key
570  fields defined for master table (masterTable()->primaryKey()->fieldCount()).
571 
572  Each element of the returned vector:
573  - can belong to [0..fieldsExpanded().count()-1] if there is such
574  primary key's field in the fieldsExpanded() list.
575  - can be equal to -1 if there is no such primary key's field
576  in the fieldsExpanded() list.
577 
578  If there are more than one primary key's field included in the query,
579  only first-found column (oin the fieldsExpanded() list) for each pkey's field is included.
580 
581  Returns empty vector if there is no master table or no master table's pkey.
582  @see example for pkeyFieldCount().
583  @todo js: UPDATE CACHE!
584  */
585  QVector<int> pkeyFieldsOrder(KDbConnection *conn) const;
586 
587  /*! @return number of master table's primary key fields included in this query.
588  This method is useful to quickly check whether the vector returned by pkeyFieldsOrder()
589  if filled completely.
590 
591  User e.g. in KDbConnection::updateRecord() to check if entire primary
592  key information is specified.
593 
594  Examples: let table T has (ID1 INTEGER, ID2 INTEGER, A INTEGER) fields,
595  and let (ID1, ID2) is T's primary key.
596  -# The query defined by "SELECT * FROM T" statement contains all T's
597  primary key's fields as T is the master table, and thus pkeyFieldCount()
598  will return 2 (both primary key's fields are in the fieldsExpanded() list),
599  and pkeyFieldsOrder() will return vector {0, 1}.
600  -# The query defined by "SELECT A, ID2 FROM T" statement, and thus pkeyFieldCount()
601  will return 1 (only one primary key's field is in the fieldsExpanded() list),
602  and pkeyFieldsOrder() will return vector {-1, 1}, as second primary key's field
603  is at position #1 and first field is not specified at all within the query.
604  */
605  int pkeyFieldCount(KDbConnection *conn);
606 
607  /*! @return a list of field infos for all auto-incremented fields
608  from master table of this query. This result is cached for efficiency.
609  fieldsExpanded() is used for that.
610  */
612 
613  /*! @return a preset statement (if any). */
614  KDbEscapedString statement() const;
615 
616  /*! Forces a raw SQL statement @a sql for the query. This means that no statement is composed
617  * from KDbQuerySchema's content. */
618  void setStatement(const KDbEscapedString& sql);
619 
620  /*! @return a string that is a result of concatenating all column names
621  for @a infolist, with "," between each one.
622  This is usable e.g. as argument like "field1,field2"
623  for "INSERT INTO (xxx) ..". The result of this method is effectively cached,
624  and it is invalidated when set of fields changes (e.g. using clear()
625  or addField()).
626 
627  This method is similar to KDbFieldList::sqlFieldsList() it just uses
628  KDbQueryColumnInfo::List instead of KDbField::List.
629 
630  @a escapingType can be used to alter default escaping type.
631  If @a conn is not provided for DriverEscaping, no escaping is performed. */
632  static KDbEscapedString
633  sqlColumnsList(const KDbQueryColumnInfo::List &infolist, KDbConnection *conn = nullptr,
635 
636  /*! @return cached list of autoincrement fields created using sqlColumnsList()
637  on a list returned by autoIncrementFields(). The field names are escaped using
638  driver escaping. */
639  KDbEscapedString autoIncrementSqlFieldsList(KDbConnection *conn) const;
640 
641  /**
642  * @brief Sets a WHERE expression @a exp.
643  *
644  * Previously set WHERE expression will be removed. A null expression
645  * (KDbExpression()) can be passed to remove existing WHERE expresssion.
646  * @return @c false if @a expr is not a valid WHERE expression. validate() is called
647  * to check this. On failure the WHERE expression for this query is cleared. In this
648  * case a string pointed by @a errorMessage (if provided) is set to a general error
649  * message and a string pointed by @a errorDescription (if provided) is set to a
650  * detailed description of the error.
651  */
652  bool setWhereExpression(const KDbExpression &expr, QString *errorMessage = nullptr,
653  QString *errorDescription = nullptr);
654 
655  /*! @return WHERE expression or 0 if this query has no WHERE expression */
656  KDbExpression whereExpression() const;
657 
658  /**
659  * @brief Appends a part to WHERE expression.
660  *
661  * Simplifies creating of WHERE expression if used instead of setWhereExpression().
662  * @return @c false if the newly constructed WHERE expression is not valid.
663  * validate() is called to check this. On failure the WHERE expression for this query
664  * is left unchanged. In this case a string pointed by @a errorMessage (if provided)
665  * is set to a general error message and a string pointed by @a errorDescription
666  * (if provided) is set to a detailed description of the error.
667  */
668  bool addToWhereExpression(KDbField *field, const QVariant &value,
669  KDbToken relation = '=', QString *errorMessage = nullptr,
670  QString *errorDescription = nullptr);
671 
672  /*! Sets a list of columns for ORDER BY section of the query.
673  Each name on the list must be a field or alias present within the query
674  and must not be covered by aliases. If one or more names cannot be found
675  within the query, the method will have no effect.
676  Any previous ORDER BY settings will be removed.
677 
678  Note that this information is cleared whenever you call methods that
679  modify list of columns (KDbQueryColumnInfo), i.e. insertField(),
680  addField(), removeField(), addExpression(), etc.
681  (because KDbOrderByColumn items can point to a KDbQueryColumnInfo that's removed by these
682  methods), so you should use setOrderByColumnList() method after the query
683  is completely built. */
684  void setOrderByColumnList(const KDbOrderByColumnList& list);
685 
686  /*! @return a list of columns listed in ORDER BY section of the query.
687  Read notes for @ref setOrderByColumnList(). */
688  KDbOrderByColumnList* orderByColumnList();
689 
690  /*! @see orderByColumnList() */
691  const KDbOrderByColumnList* orderByColumnList() const;
692 
693  /*! @return query schema parameters. These are taked from the WHERE section
694  (a tree of expression items). */
695  QList<KDbQuerySchemaParameter> parameters(KDbConnection *conn) const;
696 
697  //! @return @c true if this query is valid
698  /*! Detailed validation is performed in the same way as parsing of query statements
699  * by the KDbParser.
700  * Example :Let the query be "SELECT <fields> FROM <tables> WHERE <whereExpression>".
701  * First each field from <fields> (@see fields()) is validated using
702  * KDbField::expression().validate(). Then the <whereExpression> (@see
703  * whereExpression())
704  * is validated using KDbExpression::validate().
705  *
706  * On error a string pointed by @a errorMessage (if provided) is set to a general
707  * error message and a string pointed by @a errorDescription (if provided) is set to a
708  * detailed description of the error.
709  */
710  //! @todo add tests
711  bool validate(QString *errorMessage = nullptr, QString *errorDescription = nullptr);
712 
713 protected:
714  KDbQuerySchemaFieldsExpanded *computeFieldsExpanded(KDbConnection *conn) const;
715 
716  //! Used by fieldsExpanded(KDbConnection*, FieldsExpandedMode)
717  //! and visibleFieldsExpanded(KDbConnection*, FieldsExpandedMode).
718  KDbQueryColumnInfo::Vector fieldsExpandedInternal(KDbConnection *conn,
719  FieldsExpandedMode mode,
720  bool onlyVisible) const;
721 
722  /** Internal method used by all insert*Field methods.
723  * The new column can also be explicitly bound to a specific position on tables list.
724  * @a bindToTable is a table index within the query for which the field should be bound.
725  * If @a bindToTable is -1, no particular table will be bound.
726  * @see tableBoundToColumn(int columnPosition)
727  */
728  bool insertFieldInternal(int position, KDbField *field, int bindToTable, bool visible);
729 
730  /**
731  * Internal method used by add*Asterisk() methods.
732  * Appends @a asterisk at the and of columns list, sets visibility.
733  */
734  bool addAsteriskInternal(KDbQueryAsterisk *asterisk, bool visible);
735 
736  /** Internal method used by all add*Expression methods.
737  * Appends expression @a expr at the and of columns list, sets visibility.
738  */
739  bool addExpressionInternal(const KDbExpression& expr, bool visible);
740 
741  /** Internal method used by a query parser.
742  */
743  void setWhereExpressionInternal(const KDbExpression &expr);
744 
745  friend class KDbQuerySchemaPrivate;
746 
747  Q_DISABLE_COPY(KDbQuerySchema)
748  KDbQuerySchemaPrivate * const d;
749 };
750 
751 //! A pair (connection, table-or-schema) for QDebug operator<<
752 //! @since 3.1
753 typedef std::tuple<KDbConnection*, const KDbQuerySchema&> KDbConnectionAndQuerySchema;
754 
755 //! Sends connection and query schema information @a connectionAndSchema to debug output @a dbg.
756 //! @since 3.1
757 KDB_EXPORT QDebug operator<<(QDebug dbg,
758  const KDbConnectionAndQuerySchema &connectionAndSchema);
759 
760 #endif
KDbField::List * autoIncrementFields() const
KDbQueryColumnInfo::Vector fieldsExpanded(KDbConnection *conn, FieldsExpandedMode mode=FieldsExpandedMode::Default) const
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
KDbOrderByColumn provides information about a single query column used for sorting.
A type-safe KDbSQL token It can be used in KDb expressions.
Definition: KDbToken.h:36
virtual KDbField * field(int id)
Specialized string for escaping.
A single parameter of a query schema.
@ DriverEscaping
Identifiers are escaped by driver.
Definition: KDbGlobal.h:145
virtual bool insertField(int index, KDbField *field)
KDbQueryColumnInfo::Vector visibleFieldsExpanded(KDbConnection *conn, FieldsExpandedMode options=FieldsExpandedMode::Default) const
bool addField(KDbField *field)
ColumnsOrderMode
Mode for columnsOrder()
virtual bool removeField(KDbField *field)
ExpandMode
Mode for field() and columnInfo()
FieldsExpandedMode
Mode for fieldsExpanded() and visibleFieldsExpanded()
KDbQuerySchema provides information about database query.
Meta-data for a field.
Definition: KDbField.h:71
KDbQueryAsterisk class encapsulates information about single asterisk in query definition.
KDbOrderByColumnList provides list of sorted columns for a query schema.
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
The KDbExpression class represents a base class for all expressions.
Definition: KDbExpression.h:51
Helper class that assigns additional information for the column in a query.
IdentifierEscapingType
Escaping type for identifiers.
Definition: KDbGlobal.h:144
virtual void clear()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:08:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.