From a4e6e13d87c01c6f1c8e8f64b608d538eff7d56f Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 10 Jul 2023 09:41:45 -0400 Subject: [PATCH] add a note to contains_eager re: propcomparator.and_ Change-Id: I5555db3a0e94a92a15759f64b6298c4b2800d183 References: https://github.com/sqlalchemy/sqlalchemy/discussions/9898#discussioncomment-6404539 --- doc/build/orm/queryguide/relationships.rst | 16 ++++++++++++++++ lib/sqlalchemy/engine/url.py | 6 ++++++ 2 files changed, 22 insertions(+) diff --git a/doc/build/orm/queryguide/relationships.rst b/doc/build/orm/queryguide/relationships.rst index 7642c70a1a..30c8b1906f 100644 --- a/doc/build/orm/queryguide/relationships.rst +++ b/doc/build/orm/queryguide/relationships.rst @@ -1132,6 +1132,17 @@ that we can opt to **modify** what values the collection is intended to store, by writing our SQL to load a subset of elements for collections or scalar attributes. +.. tip:: SQLAlchemy now has a **much simpler way to do this**, by allowing + WHERE criteria to be added directly to loader options such as + :func:`_orm.joinedload` + and :func:`_orm.selectinload` using :meth:`.PropComparator.and_`. See + the section :ref:`loader_option_criteria` for examples. + + The techniques described here still apply if the related collection is + to be queried using SQL criteria or modifiers more complex than a simple + WHERE clause. + + As an example, we can load a ``User`` object and eagerly load only particular addresses into its ``.addresses`` collection by filtering the joined data, routing it using :func:`_orm.contains_eager`, also using @@ -1173,6 +1184,11 @@ in fact associated with the collection. assuming default session settings, or the :meth:`.Session.expire_all` or :meth:`.Session.expire` methods are used. +.. seealso:: + + :ref:`loader_option_criteria` - modern API allowing WHERE criteria directly + within any relationship loader option + Relationship Loader API ----------------------- diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py index 0315737d66..5cf5ec7b4b 100644 --- a/lib/sqlalchemy/engine/url.py +++ b/lib/sqlalchemy/engine/url.py @@ -836,6 +836,12 @@ def make_url(name_or_url: Union[str, URL]) -> URL: if isinstance(name_or_url, str): return _parse_url(name_or_url) + elif not isinstance(name_or_url, URL) and not hasattr( + name_or_url, "_sqla_is_testing_if_this_is_a_mock_object" + ): + raise exc.ArgumentError( + f"Expected string or URL object, got {name_or_url!r}" + ) else: return name_or_url -- 2.39.5