KDb

KDbQuerySchema.h
1/* This file is part of the KDE project
2 Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org>
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
31class KDbConnection;
35class KDbQuerySchemaFieldsExpanded;
37class KDbQuerySchemaPrivate;
38class KDbRelationship;
39class 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. */
45class KDB_EXPORT KDbQuerySchema : public KDbFieldList, public KDbObject
46{
47public:
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
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
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
713protected:
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 */
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
753typedef 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
757KDB_EXPORT QDebug operator<<(QDebug dbg,
758 const KDbConnectionAndQuerySchema &connectionAndSchema);
759
760#endif
Provides database connection, allowing queries and data modification.
Specialized string for escaping.
The KDbExpression class represents a base class for all expressions.
KDbField::List * autoIncrementFields() const
bool addField(KDbField *field)
virtual bool removeField(KDbField *field)
virtual KDbField * field(int id)
virtual void clear()
virtual bool insertField(int index, KDbField *field)
Meta-data for a field.
Definition KDbField.h:72
KDbOrderByColumnList provides list of sorted columns for a query schema.
KDbOrderByColumn provides information about a single query column used for sorting.
KDbQueryAsterisk class encapsulates information about single asterisk in query definition.
Helper class that assigns additional information for the column in a query.
A single parameter of a query schema.
KDbQuerySchema provides information about database query.
KDbQueryColumnInfo::Vector fieldsExpanded(KDbConnection *conn, FieldsExpandedMode mode=FieldsExpandedMode::Default) const
ColumnsOrderMode
Mode for columnsOrder()
void setWhereExpressionInternal(const KDbExpression &expr)
Internal method used by a query parser.
FieldsExpandedMode
Mode for fieldsExpanded() and visibleFieldsExpanded()
KDbQueryColumnInfo::Vector visibleFieldsExpanded(KDbConnection *conn, FieldsExpandedMode options=FieldsExpandedMode::Default) const
ExpandMode
Mode for field() and columnInfo()
A type-safe KDbSQL token It can be used in KDb expressions.
Definition KDbToken.h:37
IdentifierEscapingType
Escaping type for identifiers.
Definition KDbGlobal.h:144
@ DriverEscaping
Identifiers are escaped by driver.
Definition KDbGlobal.h:145
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.