Add additional detail and clarifications on SELECT #6572

bitwombat · 2017-07-22T07:31:11Z

Also the effect of WHERE on result array.

- Also the effect of WHERE on result array.

Ocramius · 2017-07-22T07:34:53Z

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

+The SELECT clause of a DQL query specifies what gets hydrated in
+the query result. You are always returned usable objects, but any
+associated objects not included in the SELECT clause will be
+proxies (ie. unhydrated).  They get hydrated by Doctrine when


Too much information here - this should be detailed somewhere else

Somewhere else in the same doc, or somewhere else on the internet :)

This PR is sort of an inclusion of the things that took me too long to figure out... and accepted SO answers weren't very good.

Possibly, but remember that you are approaching readers that may have no clue about doctrine, so this stuff can be plain confusing until the basics are covered :-)

Basically, ELI5

Actually, near line 181 you already have a description of the lazy-loading and walking the object tree... so you've either changed your mind or I'm duplicating things. :)

Either way I should delete this part. Except I'm not sure it's clear that including things in the SELECT clause is what hydrates them. The discussion of fetch joins at the top is attempting to do that.

What do you think?

Either way I should delete this part. Except I'm not sure it's clear that including things in the SELECT clause is what hydrates them. The discussion of fetch joins at the top is attempting to do that.

As long as it's documented somewhere else, heh.

Ocramius · 2017-07-22T07:36:00Z

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

+  In this case, the result array will be made up of objects of
+  the type in the FROM clause.  In the example above, the query
+  will return an array of User objects, with associated classes
+  identify else where in the query as 'p' and 'n' hydrated.


The wording is a bit confusing here - can you rephrase it so that it is clear that p and n are children of u, and are not going to be selected as separate columns in the result?

Use double backticks around anything that is code-like, such as u, p, n

Wow, typo on my part. Bad news. OK, will fix, rephrase and add backticks.

Ocramius · 2017-07-22T07:36:56Z

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

+  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


Use double backticks around anything that is code-like, such as FROM

I'm following convention. Elsewhere in the doc, the DQL keywords (SELECT, FROM, WITH) are not surrounded by backticks (though entire DQL commands are). Maybe Previous You thought that would clutter the output? Tell me what you want me to do here.

I wrote almost none of the docs, but the separate rendering format of code as code aids readability

So you'd like me to surround all the existing SELECT, FROM, WITH, etc. statements with backticks as part of this PR? No prob, just clarifying.

Ocramius · 2017-07-22T07:37:03Z

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

+    ``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.


Use double backticks around anything that is code-like, such as p.quantity

Ocramius · 2017-07-22T07:37:42Z

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

+
+.. note::
+
+    You cannot select other entities unless you also select the


This case only applies to the scenario where entities are being selected, not the scalars scenario

It's a note, not coupled to the scalars scenario. Unless I'm not seeing something.

Alright then 👍

Ocramius · 2017-07-22T07:38:39Z

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

+    root of the selection (the first entity in FROM).
+
+    Doctrine tells you you have violated this constraint with the
+    exception "Cannot select entity through identification


"with an exception" - the exception message should be improved in the library if it isn't clear enough there.

I would also add an example of when this would fail (example query)

The message does call the same thing an "identification variable" and an "alias" in the same message. As do the docs. I'm wondering if one term should be picked and used throughout.

I'm wondering if one term should be picked and used throughout.

Possibly - it would surely reduce impedance between ORM internals and their documentation (as they are called "identification variable" internally too)

Ocramius · 2017-07-22T07:40:26Z

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

+    exception "Cannot select entity through identification
+    variables without choosing at least one root entity alias."
+
+It is possible to wrap both fields and identification values into


This block is confusing - why is it in this section?

I think you might have selected the wrong lines there, as that's not a block... ??

Sorry, miswording on my side - I mean paragraph. The information about functions being applicable to the selection seems weird if it's redundant with a later section. Maybe move this information directly there?

Line 127 above? That was in the original (unchanged by me).

Didn't hear back from you on this. Leaving it in there since it's yours originally.

Alright 👍

- A per Ocramius' explanation in #6563

Ocramius · 2017-07-22T07:49:04Z

One note on positioning knowledge in the document: after editing, try to scan the entire document again and see if it makes sense or it actually asks the user to jump around "goto" style :-)

Ocramius · 2017-08-18T19:45:14Z

🚢

Thanks @bitwombat!

Add additional detail and clarifications on SELECT

8057303

- Also the effect of WHERE on result array.

Ocramius suggested changes Jul 22, 2017

View reviewed changes

Ocramius added the Documentation label Jul 22, 2017

Ocramius assigned bitwombat Jul 22, 2017

Add note clarifying WHERE, WITH and HAVING

624af3d

- A per Ocramius' explanation in #6563

Ocramius mentioned this pull request Aug 18, 2017

DQL docs - I'll write clarifications in the docs if someone can elaborate a few things #6563

Closed

Fix format and content as-per discussion in PR

74c83f3

Ocramius added this to the 2.6.0 milestone Aug 18, 2017

Ocramius approved these changes Aug 18, 2017

View reviewed changes

Ocramius merged commit 671fd50 into doctrine:master Aug 18, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add additional detail and clarifications on SELECT #6572

Add additional detail and clarifications on SELECT #6572

bitwombat commented Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017 •

edited

Loading

Ocramius Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

Ocramius Aug 18, 2017

Ocramius Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Aug 18, 2017

Ocramius Aug 18, 2017

bitwombat Aug 18, 2017 •

edited

Loading

Ocramius Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

Ocramius Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

Ocramius Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

Ocramius Jul 22, 2017

bitwombat Jul 22, 2017

bitwombat Aug 18, 2017

Ocramius Aug 18, 2017

Ocramius commented Jul 22, 2017

Ocramius commented Aug 18, 2017


		.. note::

		You cannot select other entities unless you also select the

Add additional detail and clarifications on SELECT #6572

Add additional detail and clarifications on SELECT #6572

Conversation

bitwombat commented Jul 22, 2017

Choose a reason for hiding this comment

bitwombat Jul 22, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bitwombat Aug 18, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ocramius commented Jul 22, 2017

Ocramius commented Aug 18, 2017

bitwombat Jul 22, 2017 •

edited

Loading

bitwombat Aug 18, 2017 •

edited

Loading