add a note to contains_eager re: propcomparator.and_

Change-Id: I5555db3a0e94a92a15759f64b6298c4b2800d183
References: https://github.com/sqlalchemy/sqlalchemy/discussions/9898#discussioncomment-6404539
This commit is contained in:
Mike Bayer
2023-07-10 09:41:45 -04:00
parent d50885d0c9
commit a4e6e13d87
2 changed files with 22 additions and 0 deletions
+16
View File
@@ -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
-----------------------
+6
View File
@@ -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