[Sqlalchemy-tickets] [sqlalchemy] #2724: Unclear documentation for join

[sqlalchemy <mi...@zz...>]

#2724: Unclear documentation for join
---------------------------+-----------------------------------------
 Reporter:  dwt            |           Owner:  zzzeek
     Type:  enhancement    |          Status:  new
 Priority:  medium         |       Milestone:
Component:  documentation  |        Severity:  no triage selected yet
 Keywords:                 |  Progress State:  awaiting triage
---------------------------+-----------------------------------------
 I've found that the documentation for join at
 http://docs.sqlalchemy.org/en/rel_0_8/orm/query.html#sqlalchemy.orm.query.Query.join
 was lacking the information that the direction of the join, i.e. what is
 the left side and what is the righthand side of a join can be decided by
 the way you write the argument to the join call.

 So it makes a difference if you write
 {{{DBSession.query(User).join(Track.user)}}} - that will {{{select * from
 Track join User}}} or if you write
 {{{DBSession.query(User).join(User.tracks)}}} which will {{{select * from
 User join Track}}}.

 As far as my understanding of sql is that shouldn't make a difference, but
 when you switch from join to {{{outerjoin()}}}, suddenly this distinction
 becomes very important as it defines the lefthand side of the left outer
 join and someting you cannot override even with {{{select_from()}}}.

 And that is what cost us quite some time today to figure out - so a
 clearer mention of this in the documentation would be really helpfull.

 Hope this clarifies what I mean,

 Best Regards,
 Martin

-- 
Ticket URL: <http://www.sqlalchemy.org/trac/ticket/2724>
sqlalchemy <http://www.sqlalchemy.org/>
The Database Toolkit for Python