From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 2 Oct 2015 15:23:50 +0000 (-0400)
Subject: - add an additional note regarding select_from, fixes #3546
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=276df23935fe9dfe1b00f1219dba9ace03c596a6;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add an additional note regarding select_from, fixes #3546

(cherry picked from commit d84dea62de3a9c83ad539a5cf2ff4be2c0685a94)
---

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index dc077b1778..31579ef3ba 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -1322,6 +1322,16 @@ The reference documentation for :meth:`~.Query.join` contains detailed informati
 and examples of the calling styles accepted by this method; :meth:`~.Query.join`
 is an important method at the center of usage for any SQL-fluent application.
 
+.. topic:: What does :class:`.Query` select from if there's multiple entities?
+
+    The :meth:`.Query.join` method will **typically join from the leftmost
+    item** in the list of entities, when the ON clause is omitted, or if the
+    ON clause is a plain SQL expression.  To control the first entity in the list
+    of JOINs, use the :meth:`.Query.select_from` method::
+
+        query = Session.query(User, Address).select_from(Address).join(User)
+
+
 .. _ormtutorial_aliases:
 
 Using Aliases