Add QueryBuilder support for UNION clause

[sbuerk]

Q	A
Type	feature
Fixed issues	#6368

Summary

The UNION operator is used to combine the result-set
of two or more SELECT statements, which all database
vendors supports with usual specialities for each.

Still, there is a common shared subset which works for
all of them:

    SELECT column_name(s) FROM table1
    WHERE ...

    UNION <ALL | DISTINCT>

    SELECT column_name(s) FROM table2
    WHERE ...

    ORDER BY ...
    LIMIT x OFFSET y

with shared common requirements:

• Each SELECT must return the same fields
  in number, naming and order.

• Each SELECT must not have ORDER BY,
  expect MySQL allowing it to be used as sub
  query expression encapsulated in parenthesis.

It is now possible to build UNION queries using
following additional QueryBuilder API methods:

• union(string|QueryBuilder $part) to create a UNION
  query retrieving unique rows
• addUnion(string|QueryBuilder $part, UnionType $type)
  to add UNION (ALL|DISTINCT) query with the selected
  union query type.

This follows the generic logic of select(...) and
addSelect(...) along with introducing new UnionType
enum and internal QueryType::UNION enum case.

Technically, the SQL build process is dispatched to a
DefaultUnionSQLBuilder along with an UnionSQLBuilder
interface, which also allows application to implement
custom behaviour if required. Union SQL keyword and part
SQL generation is handled through added methods on the
Platforms to allow adjustment for furture versions if
needed - or throw a Exception if a Platform does not
support it anymore.

Example:

$platform = $connection->getDatabasePlatform();
$qb       = $>connection->createQueryBuilder();
$select10 = $platform->getDummySelectSQL('2 as field_one');
$select20 = $platform->getDummySelectSQL('1 as field_one');
$qb->union($select10)
   ->addUnion($select20, UnionType::ALL)
   ->setMaxResults(1)
   ->setFirstResult(1)
   ->orderBy('field_one', 'ASC');
$rows = $qb->executeQuery()->fetchAllAssociative();

Unit and functional tests are added to demonstrate the
implementation and cover it for future changes.

Resolves: #6368

[stof]

The current API with ->addUnion() and ->addUnionAll() is confusing IMO. The implementation will remember the DISTINCT/ALL behavior of the last call and apply it to all unions being added. If the SQL standard does not allow mixing both modes when having several union clauses, a separate flag would be a much better API.

I'm also wondering whether the QueryBuilder should throw exceptions when using incompatible methods together (adding select and where clauses and then using addUnion would silently ignore the select and where clauses right now, while the proper usage is to put those on the query builder used inside the union clause)

[sbuerk]

The current API with ->addUnion() and ->addUnionAll() is confusing IMO. The implementation will remember the DISTINCT/ALL behavior of the last call and apply it to all unions being added. If the SQL standard does not allow mixing both modes when having several union clauses, a separate flag would be a much better API.

I'm also wondering whether the QueryBuilder should throw exceptions when using incompatible methods together (adding select and where clauses and then using addUnion would silently ignore the select and where clauses right now, while the proper usage is to put those on the query builder used inside the union clause)

@stof Thanks for your feedback.

The standard in fact allows to mix UNION DISTINCT and UNION ALL to add the next part, which was not reflected in the first API implementation.

I changed and further reduced that to union() and addUnion() methods, now dealing only with one part. The addUnion() enforces to define the time for the added part using a enum class. Not sure if a boolean would be more favourized over the enum, while I'm personally think the enum is more speaking in that case).

After talking with @derrabus about this PR, I moved the SQL generation into the platform classes and surround union parts on platforms supporting it (default), removing it for SQLite for now.

Platforms behave differently for additional stuff on the union select parts, which are mostly reduced using the part parenthesis surrounding excpet sqlite. Due to the nature that either string or QueryBuilder parts could be added, it is hard to scan for platform incompatible part queries - and left to be reported from the database. We have at least an excpetion in place if only one part is provided.

Not sure if we should really throw an exception if unsupported properties are set for the outer union query (for example set() or values() which is not done yet. I'd say this should be done in a dedicated change to throw exception for all types if unsupported properties and information are set beforehand and not properly cleared. What do you think ?

Not sure about the codecoverage upload error in the checks or what is needed to do to make it happy.

[derrabus]

LGTM, so I start nit-picking. 😉