From 8c10e29dc7aa2356d0f3f5110b2c9dade9d87096 Mon Sep 17 00:00:00 2001
From: Federico Caselli <cfederico87@gmail.com>
Date: Thu, 14 May 2020 21:51:59 +0200
Subject: [PATCH] Improve error message when using
 :meth:`_query.Query.filter_by` in a query where the first entity is not a
 mapped class.

Fixes: #5260
Change-Id: I18cfccc0f3e587cb3df3e1f5f23b6885d5f2f466
---
 doc/build/changelog/unreleased_13/5260.rst |  6 ++++++
 lib/sqlalchemy/orm/query.py                | 11 ++++++++++-
 test/orm/test_query.py                     | 12 ++++++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 doc/build/changelog/unreleased_13/5260.rst

diff --git a/doc/build/changelog/unreleased_13/5260.rst b/doc/build/changelog/unreleased_13/5260.rst
new file mode 100644
index 0000000000..18e1ddeb01
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/5260.rst
@@ -0,0 +1,6 @@
+.. change::
+    :tags: usecase, orm
+    :tickets: 5326
+
+    Improve error message when using :meth:`_query.Query.filter_by` in
+    a query where the first entity is not a mapped class.
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 6e22a69044..090e3a972c 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1784,8 +1784,17 @@ class Query(Generative):
 
         """
 
+        zero = self._joinpoint_zero()
+        if zero is None:
+            raise sa_exc.InvalidRequestError(
+                "Can't use filter_by when the first entity '%s' of a query "
+                "is not a mapped class. Please use the filter method instead, "
+                "or change the order of the entities in the query"
+                % self._query_entity_zero()
+            )
+
         clauses = [
-            _entity_descriptor(self._joinpoint_zero(), key) == value
+            _entity_descriptor(zero, key) == value
             for key, value in kwargs.items()
         ]
         return self.filter(*clauses)
diff --git a/test/orm/test_query.py b/test/orm/test_query.py
index 150b406e71..8943bfc1f0 100644
--- a/test/orm/test_query.py
+++ b/test/orm/test_query.py
@@ -3345,6 +3345,18 @@ class FilterTest(QueryTest, AssertsCompiledSQL):
             "AS users_name FROM users WHERE name='ed'",
         )
 
+    def test_filter_by_non_entity(self):
+        s = create_session()
+        e = sa.func.count(123)
+        assert_raises_message(
+            sa_exc.InvalidRequestError,
+            r"Can't use filter_by when the first entity 'count\(:count_1\)' of"
+            " a query is not a mapped class. Please use the filter method "
+            "instead, or change the order of the entities in the query",
+            s.query(e).filter_by,
+            col=42,
+        )
+
 
 class HasAnyTest(fixtures.DeclarativeMappedTest, AssertsCompiledSQL):
     __dialect__ = "default"
-- 
2.39.5