Merge pull request #6572 from bitwombat/doc_changes

Add additional detail and clarifications on SELECT

docs/en/reference/dql-doctrine-query-language.rst

@@ -49,10 +49,6 @@ SELECT queries
 DQL SELECT clause
 ~~~~~~~~~~~~~~~~~
 
-The select clause of a DQL query specifies what appears in the
-query result. The composition of all the expressions in the select
-clause also influences the nature of the query result.
-
 Here is an example that selects all users with an age > 20:
 
 .. code-block:: php
@@ -83,14 +79,58 @@ Lets examine the query:
 The result of this query would be a list of User objects where all
 users are older than 20.
 
-The SELECT clause allows to specify both class identification
-variables that signal the hydration of a complete entity class or
-just fields of the entity using the syntax ``u.name``. Combinations
-of both are also allowed and it is possible to wrap both fields and
-identification values into aggregation and DQL functions. Numerical
-fields can be part of computations using mathematical operations.
-See the sub-section on `Functions, Operators, Aggregates`_ for
-more information.
+Result format
+~~~~~~~~~~~~~
+The composition of the expressions in the SELECT clause also
+influences the nature of the query result. There are three
+cases:
+
+**All objects**
+
+.. code-block:: sql
+
+    SELECT u, p, n FROM Users u...
+
+In this case, the result will be an array of User objects because of
+the FROM clause, with children ``p`` and ``n`` hydrated because of
+their inclusion in the SELECT clause.
+
+**All scalars**
+
+.. code-block:: sql
+
+    SELECT u.name, u.address FROM Users u...
+
+In this case, the result will be an array of arrays.  In the example
+above, each element of the result array would be an array of the
+scalar name and address values. 
+
+You can select scalars from any entity in the query. 
+
+**Mixed**
+
+.. code-block:: sql
+
+    ``SELECT u, p.quantity FROM Users u...``
+
+Here, the result will again be an array of arrays, with each element
+being an array made up of a User object and the scalar value
+``p.quantity``.
+
+Multiple FROM clauses are allowed, which would cause the result
+array elements to cycle through the classes included in the
+multiple FROM clauses.
+
+.. note::
+
+    You cannot select other entities unless you also select the
+    root of the selection (which is the first entity in FROM).
+
+    For example, ``SELECT p,n FROM Users u...`` would be wrong because
+    ``u`` is not part of the SELECT
+
+    Doctrine throws an exception if you violate this constraint.
+
 
 Joins
 ~~~~~
@@ -319,7 +359,8 @@ article-ids:
     $query = $em->createQuery('SELECT u.id, a.id as article_id FROM CmsUser u LEFT JOIN u.articles a');
     $results = $query->getResult(); // array of user ids and every article_id for each user
 
-Restricting a JOIN clause by additional conditions:
+Restricting a JOIN clause by additional conditions specified by
+WITH:
 
 .. code-block:: php
 
@@ -452,6 +493,18 @@ Joins between entities without associations were not possible until version
     <?php
     $query = $em->createQuery('SELECT u FROM User u JOIN Blacklist b WITH u.email = b.email');
 
+.. note::
+    The differences between WHERE, WITH and HAVING clauses may be
+    confusing.
+
+    - WHERE is applied to the results of an entire query
+    - WITH is applied to a join as an additional condition. For
+      arbitrary joins (SELECT f, b FROM Foo f, Bar b WITH f.id = b.id)
+      the WITH is required, even if it is 1 = 1
+    - HAVING is applied to the results of a query after
+      aggregation (GROUP BY)
+
+
 Partial Object Syntax
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -607,6 +660,9 @@ The same restrictions apply for the reference of related entities.
 
 Functions, Operators, Aggregates
 --------------------------------
+It is possible to wrap both fields and identification values into
+aggregation and DQL functions. Numerical fields can be part of
+computations using mathematical operations.
 
 DQL Functions
 ~~~~~~~~~~~~~
@@ -1381,11 +1437,11 @@ Given that there are 10 users and corresponding addresses in the database the ex
 
 .. note::
     Changing the fetch mode during a query mostly makes sense for one-to-one and many-to-one relations. In that case, 
-    all the necessary IDs are available after the root entity (``user`` in the above example) has been loaded. So, one
-    query per association can be executed to fetch all the referred-to entities (``address``).
+    all the necessary IDs are available after the root entity (``user`` in the above example) has been loaded. So, one
+    query per association can be executed to fetch all the referred-to entities (``address``).
     
     For one-to-many relations, changing the fetch mode to eager will cause to execute one query **for every root entity
-    loaded**. This gives no improvement over the ``lazy`` fetch mode which will also initialize the associations on
+    loaded**. This gives no improvement over the ``lazy`` fetch mode which will also initialize the associations on
     a one-by-one basis once they are accessed.