From 332b8b78f6ba728b0994457420cb66e1c9bd5846 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 --- 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 cdad55320c..abbba41722 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1965,6 +1965,19 @@ class Query( 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