Unclear documentation for join

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

Comments (3)