Add note indicating order of join() calls are important

Fixes: #5406
Change-Id: I186792b32bd156d5ddf256dcd018af32ad5b515e

1 files changed, 13 insertions, 0 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index cdad55320..abbba4172 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