docs clarification- orm.joinedload

[jvanasco]

I'd like to suggest extending the note in the docs on orm.joined load with something like the following: [http://docs.sqlalchemy.org/en/latest/orm/loading_relationships.html#sqlalchemy.orm.joinedload, http://docs.sqlalchemy.org/en/rel_0_8/orm/loading.html#sqlalchemy.orm.joinedload]

========== If you have already explicitly JOINed a collection onto your query for filtering (or other use), you will likely want to use orm.contains_eager instead of orm.joinedload. joinedload will create a second anonymously aliased join, while contains_eager will more efficiently re-use the existing join. =======

[Mike Bayer]

this note is there right now:

The joins produced by orm.joinedload() are anonymously aliased. The criteria by which the join proceeds cannot be modified, nor can the Query refer to these joins in any way, including ordering.

To produce a specific SQL JOIN which is explicitly available, use Query.join(). To combine explicit JOINs with eager loading of collections, use orm.contains_eager(); see Routing Explicit Joins/Statements into Eagerly Loaded Collections.

[jvanasco]

Yeah, I meant to suggest my sentence as an addition to that note. The idea was to keyword onto the "second" join and "re-use" (vs "combine"). It's a small difference and somewhat redundant for looking at the docs in a narrative context, but is geared to address a wider net on how people will search for help (ie, why is there a second join? how do i re-use the join?" The existing note also doesn't make it obvious that if you don't "combine explicit joins with eager loading" you'll end up with a redundant query -- and that you probably want to use contains_eager.

[Mike Bayer]

can you illustrate the full text ? the sentence you have overlaps with the one that's there.

[Mike Bayer]

i don't have an action to take on this, if you want to propose a patch as a PR feel free. closing out issues :)