simplify relationship caching options

Clarified the current purpose of the
:paramref:`_orm.relationship.bake_queries` flag, which in 1.4 is to enable
or disable "lambda caching" of statements within the "lazyload" and
"selectinload" loader strategies; this is separate from the more
foundational SQL query cache that is used for most statements.
Additionally, the lazy loader no longer uses its own cache for many-to-one
SQL queries, which was an implementation quirk that doesn't exist for any
other loader scenario. Finally, the "lru cache" warning that the lazyloader
and selectinloader strategies could emit when handling a wide array of
class/relationship combinations has been removed; based on analysis of some
end-user cases, this warning doesn't suggest any significant issue. While
setting ``bake_queries=False`` for such a relationship will remove this
cache from being used, there's no particular performance gain in this case
as using no caching vs. using a cache that needs to refresh often likely
still wins out on the caching being used side.

Fixes: #6072
Fixes: #6487
Change-Id: Ida61f09b837d3acdafa07344d7d747d7f3ab226a

1 files changed, 13 insertions, 13 deletions

diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index 2d1ed6ced..89cc37de5 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -364,20 +364,20 @@ class RelationshipProperty(StrategizedProperty):
                 :ref:`error_qzyx` - usage example
 
         :param bake_queries=True:
-          Use the :class:`.BakedQuery` cache to cache the construction of SQL
-          used in lazy loads.  True by default.   Set to False if the
-          join condition of the relationship has unusual features that
-          might not respond well to statement caching.
-
-          .. versionchanged:: 1.2
-             "Baked" loading is the default implementation for the "select",
-             a.k.a. "lazy" loading strategy for relationships.
-
-          .. versionadded:: 1.0.0
-
-          .. seealso::
+          Enable :ref:`lambda caching <engine_lambda_caching>`_ for loader
+          strategies, if applicable, which adds a performance gain to the
+          construction of SQL constructs used by loader strategies, in addition
+          to the usual SQL statement caching used throughout SQLAlchemy. This
+          parameter currently applies only to the "lazy" and "selectin" loader
+          strategies. There is generally no reason to set this parameter to
+          False.
 
-            :ref:`baked_toplevel`
+          .. versionchanged:: 1.4  Relationship loaders no longer use the
+             previous "baked query" system of query caching.   The "lazy"
+             and "selectin" loaders make use of the "lambda cache" system
+             for the construction of SQL constructs,
+             as well as the usual SQL caching system that is throughout
+             SQLAlchemy as of the 1.4 series.
 
         :param cascade:
           A comma-separated list of cascade rules which determines how