From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 19 Jun 2020 15:06:08 +0000 (-0400)
Subject: Add note indicating order of join() calls are important
X-Git-Tag: rel_1_3_18~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7cc22c9bf27f938b550cc57668811f6a427e1287;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add note indicating order of join() calls are important

Fixes: #5406
Change-Id: I186792b32bd156d5ddf256dcd018af32ad5b515e
(cherry picked from commit 332b8b78f6ba728b0994457420cb66e1c9bd5846)
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index ed75fdc8c8..9bc0869b17 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -2121,6 +2121,19 @@ class Query(object):
                     join(Order.items).\
                     join(Item.keywords)
 
+        .. note:: as seen in the above example, **the order in which each
+           call to the join() method occurs is important**.    Query would not,
+           for example, know how to join correctly if we were to specify
+           ``User``, then ``Item``, then ``Order``, in our chain of joins; in
+           such a case, depending on the arguments passed, it may raise an
+           error that it doesn't know how to join, or it may produce invalid
+           SQL in which case the database will raise an error. In correct
+           practice, the
+           :meth:`_query.Query.join` method is invoked in such a way that lines
+           up with how we would want the JOIN clauses in SQL to be
+           rendered, and each call should represent a clear link from what
+           precedes it.
+
         **Joins to a Target Entity or Selectable**
 
         A second form of :meth:`_query.Query.join` allows any mapped entity or