From 7cc22c9bf27f938b550cc57668811f6a427e1287 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 19 Jun 2020 11:06:08 -0400 Subject: [PATCH] Add note indicating order of join() calls are important Fixes: #5406 Change-Id: I186792b32bd156d5ddf256dcd018af32ad5b515e (cherry picked from commit 332b8b78f6ba728b0994457420cb66e1c9bd5846) --- lib/sqlalchemy/orm/query.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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 -- 2.39.5