Техники загрузки отношений¶

Настройка стратегий загрузчика во время отображения¶

Стратегия загрузчика для конкретного отношения может быть сконфигурирована во время отображения так, чтобы она применялась во всех случаях, когда загружается объект отображаемого типа, при отсутствии каких-либо изменяющих ее опций на уровне запроса. Это настраивается с помощью параметра relationship.lazy в relationship(); обычные значения для этого параметра включают select, joined, subquery и selectin.

Например, для настройки отношения на использование объединенной ускоренной загрузки, когда запрашивается родительский объект:

class Parent(Base):
    __tablename__ = "parent"

    id = Column(Integer, primary_key=True)
    children = relationship("Child", lazy="joined")

Выше, каждый раз, когда загружается коллекция объектов Parent, каждый Parent также будет заполнен коллекцией children, используя строки, полученные путем добавления JOIN к запросу для объектов Parent. Подробнее об этом стиле загрузки см. в Присоединился к Eager Loading.

По умолчанию аргумент relationship.lazy имеет значение "select", что указывает на ленивую загрузку. Дополнительную информацию см. в разделе Ленивая загрузка.

Загрузка отношений с помощью опций загрузчика¶

Другой и, возможно, более распространенный способ настройки стратегий загрузки - это настройка их на основе каждого запроса по определенным атрибутам с помощью метода Query.options(). Очень детальный контроль над загрузкой отношений доступен с помощью опций загрузчика; наиболее распространенными являются joinedload(), subqueryload(), selectinload() и lazyload(). Опция принимает либо строковое имя атрибута в сравнении с родителем, либо для большей специфичности может принимать атрибут, связанный с классом, напрямую:

# set children to load lazily
session.query(Parent).options(lazyload(Parent.children)).all()

# set children to load eagerly with a join
session.query(Parent).options(joinedload(Parent.children)).all()

Опции загрузчика также могут быть «объединены» с помощью метода chaining, чтобы определить, как загрузка должна происходить на более глубоких уровнях:

session.query(Parent).options(
    joinedload(Parent.children).subqueryload(Child.subelements)
).all()

Опции цепного загрузчика могут быть применены к «лениво» загруженной коллекции. Это означает, что когда коллекция или ассоциация лениво загружается при доступе, указанная опция вступает в силу:

session.query(Parent).options(
    lazyload(Parent.children).subqueryload(Child.subelements)
).all()

Выше, запрос вернет Parent объектов без загруженных коллекций children. При первом обращении к коллекции children на конкретном объекте Parent, она будет лениво загружать связанные объекты, но дополнительно применять ускоренную загрузку к коллекции subelements на каждом члене children.

Приведенные выше примеры, использующие Query, теперь называются запросами 1.x style. Система опций доступна и для запросов 2.0 style, использующих метод Select.options():

stmt = select(Parent).options(lazyload(Parent.children).subqueryload(Child.subelements))

result = session.execute(stmt)

Под капотом Query в конечном итоге использует вышеупомянутый механизм, основанный на select.

session.query(A).options(lazyload(A.bs.and_(B.id > 5)))

session.query(A).options(lazyload(A.bs.and_(B.id > 5))).populate_existing()

session.query(A).options(defaultload(A.atob).joinedload(B.btoc)).all()

session.query(A).options(
    defaultload(A.atob).options(joinedload(B.btoc), joinedload(B.btod))
).all()

session.query(Parent).options(
    lazyload(Parent.children).subqueryload(Child.subelements)
).all()

# change the options on Parent objects that were already loaded
session.query(Parent).populate_existing().options(
    lazyload(Parent.children).lazyload(Child.subelements)
).all()

Ленивая загрузка¶

По умолчанию все межобъектные связи имеют ленивую загрузку. Скалярный атрибут или атрибут коллекции, связанный с relationship(), содержит триггер, который срабатывает при первом обращении к атрибуту. Этот триггер обычно выполняет вызов SQL в точке доступа, чтобы загрузить связанный объект или объекты:

>>> jack.addresses
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
FROM addresses
WHERE ? = addresses.user_id
[5]
[<Address(u'jack@google.com')>, <Address(u'j25@yahoo.com')>]

Единственный случай, когда SQL не выдается, это для простых отношений «многие-к-одному», когда связанный объект может быть идентифицирован только по первичному ключу, и этот объект уже присутствует в текущем Session. По этой причине, хотя ленивая загрузка может быть дорогой для связанных коллекций, в случае, когда загружается множество объектов с простыми отношениями «многие-к-одному» против относительно небольшого набора возможных целевых объектов, ленивая загрузка может быть способна ссылаться на эти объекты локально, не выдавая столько операторов SELECT, сколько существует родительских объектов.

Такое поведение по умолчанию «загрузка при обращении к атрибуту» известно как «ленивая» или «выборочная» загрузка - название «выборочная» потому, что оператор «SELECT» обычно выдается при первом обращении к атрибуту.

Ленивая загрузка может быть включена для данного атрибута, который обычно настроен другим способом, с помощью опции lazyload() loader:

from sqlalchemy.orm import lazyload

# force lazy loading for an attribute that is set to
# load some other way normally
session.query(User).options(lazyload(User.addresses))

from sqlalchemy.orm import raiseload

session.query(User).options(raiseload(User.addresses))

session.query(Order).options(joinedload(Order.items), raiseload("*"))

from sqlalchemy.orm import Load

session.query(Order).options(joinedload(Order.items), Load(Order).raiseload("*"))

session.query(Order).options(joinedload(Order.items).raiseload("*"))

Присоединился к Eager Loading¶

Объединенная ускоренная загрузка - это самый фундаментальный стиль ускоренной загрузки в ORM. Он работает путем подключения JOIN (по умолчанию LEFT OUTER join) к оператору SELECT, эмитируемому Query, и заполняет целевой скаляр/коллекцию из того же набора результатов, что и родительский.

На уровне отображения это выглядит следующим образом:

class Address(Base):
    # ...

    user = relationship(User, lazy="joined")

Joined eager loading обычно применяется как опция к запросу, а не как опция загрузки по умолчанию на отображении, в частности, когда используется для коллекций, а не для ссылок «многие к одному». Это достигается с помощью опции загрузчика joinedload():

>>> jack = (
...     session.query(User).options(joinedload(User.addresses)).filter_by(name="jack").all()
... )
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
['jack']

JOIN, создаваемый по умолчанию, является LEFT OUTER JOIN, чтобы позволить ведущему объекту не ссылаться на связанную строку. Для атрибута, который гарантированно имеет элемент, например, ссылка «многие-к-одному» на связанный объект, где ссылающийся внешний ключ NOT NULL, запрос можно сделать более эффективным, используя внутреннее соединение; это доступно на уровне отображения с помощью флага relationship.innerjoin:

class Address(Base):
    # ...

    user_id = Column(ForeignKey("users.id"), nullable=False)
    user = relationship(User, lazy="joined", innerjoin=True)

На уровне опций запроса, с помощью флага joinedload.innerjoin:

session.query(Address).options(joinedload(Address.user, innerjoin=True))

При применении JOIN в цепочке, включающей OUTER JOIN, JOIN будет гнездиться вправо:

>>> session.query(User).options(
...     joinedload(User.addresses).joinedload(Address.widgets, innerjoin=True)
... ).all()
SELECT
    widgets_1.id AS widgets_1_id,
    widgets_1.name AS widgets_1_name,
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN (
    addresses AS addresses_1 JOIN widgets AS widgets_1 ON
    addresses_1.widget_id = widgets_1.id
) ON users.id = addresses_1.user_id

В старых версиях SQLite вышеупомянутый вложенный правый JOIN может быть преобразован как вложенный подзапрос. Старые версии SQLAlchemy во всех случаях преобразуют вложенные справа JOIN в подзапросы.

Предупреждение

Использование with_for_update в контексте отношений нетерпеливой загрузки официально не поддерживается и не рекомендуется SQLAlchemy и может не работать с некоторыми запросами на различных бэкендах баз данных. Когда with_for_update успешно используется с запросом, включающим joinedload(), SQLAlchemy попытается выдать SQL, который блокирует все задействованные таблицы.

>>> jack = (
...     session.query(User)
...     .options(joinedload(User.addresses))
...     .filter(User.name == "jack")
...     .order_by(Address.email_address)
...     .all()
... )
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
ORDER BY addresses.email_address   <-- this part is wrong !
['jack']

>>> jack = (
...     session.query(User)
...     .join(User.addresses)
...     .filter(User.name == "jack")
...     .order_by(Address.email_address)
...     .all()
... )
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
JOIN addresses ON users.id = addresses.user_id
WHERE users.name = ?
ORDER BY addresses.email_address
['jack']

>>> jack = (
...     session.query(User)
...     .join(User.addresses)
...     .options(joinedload(User.addresses))
...     .filter(User.name == "jack")
...     .order_by(Address.email_address)
...     .all()
... )
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users JOIN addresses
    ON users.id = addresses.user_id
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ?
ORDER BY addresses.email_address
['jack']

>>> jack = (
...     session.query(User)
...     .join(User.addresses)
...     .options(joinedload(User.addresses))
...     .filter(User.name == "jack")
...     .filter(Address.email_address == "someaddress@foo.com")
...     .all()
... )
SELECT
    addresses_1.id AS addresses_1_id,
    addresses_1.email_address AS addresses_1_email_address,
    addresses_1.user_id AS addresses_1_user_id,
    users.id AS users_id, users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users JOIN addresses
    ON users.id = addresses.user_id
LEFT OUTER JOIN addresses AS addresses_1
    ON users.id = addresses_1.user_id
WHERE users.name = ? AND addresses.email_address = ?
['jack', 'someaddress@foo.com']

>>> jack = (
...     session.query(User)
...     .join(User.addresses)
...     .options(subqueryload(User.addresses))
...     .filter(User.name == "jack")
...     .filter(Address.email_address == "someaddress@foo.com")
...     .all()
... )
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
JOIN addresses ON users.id = addresses.user_id
WHERE
    users.name = ?
    AND addresses.email_address = ?
['jack', 'someaddress@foo.com']

# ... subqueryload() emits a SELECT in order
# to load all address records ...

Подзапрос Eager Loading¶

Ускоренная загрузка Subqueryload настраивается так же, как и объединенная ускоренная загрузка; для параметра relationship.lazy мы указываем "subquery", а не "joined", а для опции мы используем опцию subqueryload(), а не joinedload().

Работа подзапроса eager loading заключается в том, чтобы выдать второй оператор SELECT для каждого отношения, которое необходимо загрузить, по всем объектам результата одновременно. Этот оператор SELECT ссылается на исходный оператор SELECT, обернутый внутри подзапроса, так что мы получаем тот же список первичных ключей для возвращаемого первичного объекта, затем связываем его с суммой всех членов коллекции, чтобы загрузить их одновременно:

>>> jack = (
...     session.query(User)
...     .options(subqueryload(User.addresses))
...     .filter_by(name="jack")
...     .all()
... )
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.name = ?
('jack',)
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id,
    anon_1.users_id AS anon_1_users_id
FROM (
    SELECT users.id AS users_id
    FROM users
    WHERE users.name = ?) AS anon_1
JOIN addresses ON anon_1.users_id = addresses.user_id
ORDER BY anon_1.users_id, addresses.id
('jack',)

Стратегия загрузки подзапросов имеет много преимуществ перед объединенной нетерпеливой загрузкой в области загрузки коллекций. Во-первых, она позволяет продолжить исходный запрос, не изменяя его, не вводя, в частности, LEFT OUTER JOIN, который может сделать его менее эффективным. Во-вторых, это позволяет загружать много коллекций без создания одного запроса, содержащего множество JOIN, что может быть еще менее эффективным; каждое отношение загружается в полностью отдельном запросе. Наконец, поскольку дополнительный запрос должен загружать только элементы коллекции, а не ведущий объект, он может использовать внутренний JOIN во всех случаях для большей эффективности запроса.

К недостаткам подзапроса можно отнести то, что сложность исходного запроса переносится на запросы отношений, что в сочетании с использованием подзапроса может на некоторых бэкендах в некоторых случаях (в частности, MySQL) приводить к значительному замедлению запросов. Кроме того, стратегия загрузки подзапросов может загружать только полное содержимое всех коллекций одновременно, поэтому она несовместима с «пакетной» загрузкой, обеспечиваемой Query.yield_per(), как для коллекций, так и для скалярных отношений.

Более новый стиль загрузки, предоставляемый selectinload(), решает эти ограничения subqueryload().

# incorrect, no ORDER BY
session.query(User).options(subqueryload(User.addresses)).first()

# incorrect if User.name is not unique
session.query(User).options(subqueryload(User.addresses)).order_by(User.name).first()

# correct
session.query(User).options(subqueryload(User.addresses)).order_by(
    User.name, User.id
).first()

Выберите загрузку IN¶

Загрузка Select IN схожа по принципу работы с нетерпеливой загрузкой подзапросов, однако выдаваемый оператор SELECT имеет гораздо более простую структуру, чем при нетерпеливой загрузке подзапросов. В большинстве случаев загрузка selectin является наиболее простым и эффективным способом ускоренной загрузки коллекций объектов. Единственный сценарий, в котором ускоренная загрузка selectin нецелесообразна, - это когда модель использует составные первичные ключи, а база данных бэкенда не поддерживает кортежи с IN, к которым в настоящее время относится SQL Server.

Загрузка «Select IN» обеспечивается с помощью аргумента "selectin" к relationship.lazy или с помощью опции загрузчика selectinload(). Этот стиль загрузки выдает SELECT, который ссылается на значения первичного ключа родительского объекта или, в случае отношения «многие-к-одному», на значения дочерних объектов, внутри предложения IN, чтобы загрузить связанные ассоциации:

>>> jack = (
...     session.query(User)
...     .options(selectinload(User.addresses))
...     .filter(or_(User.name == "jack", User.name == "ed"))
...     .all()
... )
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.name = ? OR users.name = ?
('jack', 'ed')
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
FROM addresses
WHERE addresses.user_id IN (?, ?)
(5, 7)

Выше, второй SELECT относится к addresses.user_id IN (5, 7), где «5» и «7» являются значениями первичных ключей для предыдущих двух загруженных объектов User; после того, как партия объектов полностью загружена, их значения первичных ключей вводятся в предложение IN для второго SELECT. Поскольку связь между User и Address имеет простое [1] условие первичного соединения и предусматривает, что значения первичного ключа для User могут быть получены из Address.user_id, в операторе вообще нет соединений или подзапросов.

Для простых загрузок [1] многие-к-одному, JOIN также не нужен, так как используется значение внешнего ключа из родительского объекта:

>>> session.query(Address).options(selectinload(Address.user)).all()
SELECT
    addresses.id AS addresses_id,
    addresses.email_address AS addresses_email_address,
    addresses.user_id AS addresses_user_id
    FROM addresses
SELECT
    users.id AS users_id,
    users.name AS users_name,
    users.fullname AS users_fullname,
    users.nickname AS users_nickname
FROM users
WHERE users.id IN (?, ?)
(1, 2)

Загрузка Select IN также поддерживает отношения «многие-ко-многим», где в настоящее время будет JOIN по всем трем таблицам, чтобы сопоставить строки с одной стороны с другой.

О таком виде погрузки следует знать следующее:

• Оператор SELECT, выдаваемый стратегией загрузчика «selectin», в отличие от «subquery», не требует подзапроса и не наследует никаких ограничений производительности исходного запроса; поиск является простым поиском первичного ключа и должен иметь высокую производительность.

• Особые требования к упорядочиванию subqueryload, описанные в Важность заказа, также не применяются к selectin-загрузке; selectin всегда ссылается непосредственно на родительский первичный ключ и не может вернуть неверный результат.

• Загрузка «selectin», в отличие от объединенной или подзапросной загрузки, всегда выдает свой SELECT в терминах непосредственных родительских объектов, только что загруженных, а не исходного типа объекта на вершине цепочки. Таким образом, при многоуровневой загрузке «selectin» загрузка не требует никаких JOIN для простых отношений «один ко многим» или «многие к одному». В сравнении, загрузка с соединением и подзапросом всегда относится к нескольким JOINам вплоть до исходного родителя.

• Стратегия выдает SELECT для 500 значений родительского первичного ключа за раз, поскольку первичные ключи преобразуются в большое выражение IN в SQL-запросе. Некоторые базы данных, например Oracle, имеют жесткое ограничение на размер выражения IN, и в целом размер строки SQL не должен быть произвольно большим.

• Поскольку загрузка «selectin» опирается на IN, для отображения с составными первичными ключами необходимо использовать форму IN «tuple», которая выглядит как WHERE (table.column_a, table.column_b) IN ((?, ?), (?, ?), (?, ?)). Этот синтаксис в настоящее время не поддерживается на SQL Server, а для SQLite требуется как минимум версия 3.15. В SQLAlchemy нет специальной логики для предварительной проверки того, какие платформы поддерживают этот синтаксис, а какие нет; при запуске на неподдерживаемой платформе база данных немедленно выдаст ошибку. Преимущество SQLAlchemy в том, что если SQLAlchemy просто запускает SQL для того, чтобы он не сработал, то если конкретная база данных действительно начнет поддерживать этот синтаксис, она будет работать без каких-либо изменений в SQLAlchemy (как это было в случае с SQLite).

В целом, загрузка «selectin», вероятно, превосходит загрузку «subquery» eager по большинству параметров, за исключением синтаксических требований к составным первичным ключам и, возможно, того, что она может выдавать много операторов SELECT для больших наборов результатов. Как всегда, разработчики должны уделять время просмотру операторов и результатов, генерируемых их приложениями в процессе разработки, чтобы убедиться, что все работает эффективно.

Какой вид загрузки использовать?¶

Выбор типа загрузки обычно сводится к оптимизации компромисса между количеством выполнения SQL, сложностью SQL и количеством получаемых данных. Рассмотрим два примера: relationship(), который ссылается на коллекцию, и relationship(), который ссылается на скалярную ссылку «многие к одному».

• Коллекция «Один ко многим

• При использовании ленивой загрузки по умолчанию, если вы загрузите 100 объектов, а затем обратитесь к коллекции каждого из них, будет выдан 101 SQL-запрос, хотя каждый запрос обычно представляет собой простой SELECT без каких-либо объединений.

• При использовании объединенной загрузки загрузка 100 объектов и их коллекций вызовет только один SQL-запрос. Однако общее количество извлеченных строк будет равно сумме размеров всех коллекций, плюс одна дополнительная строка для каждого родительского объекта, имеющего пустую коллекцию. Каждая строка также будет содержать полный набор столбцов, представленных родительскими объектами, повторяющийся для каждого элемента коллекции - SQLAlchemy не будет повторно получать эти столбцы, кроме столбцов первичного ключа, однако большинство DBAPI (за некоторыми исключениями) в любом случае будут передавать полные данные каждого родителя по проводу на клиентское соединение. Поэтому объединенная ускоренная загрузка имеет смысл только тогда, когда размер коллекций относительно невелик. LEFT OUTER JOIN также может быть более производительным по сравнению с INNER join.

• При использовании загрузки подзапросов загрузка 100 объектов вызовет два SQL-запроса. Во втором операторе будет получено общее количество строк, равное сумме размеров всех коллекций. Используется INNER JOIN, и запрашивается минимум родительских столбцов, только первичные ключи. Поэтому загрузка подзапросов имеет смысл, когда коллекции больше.

• При использовании нескольких уровней глубины с объединенной или подзапросной загрузкой, загрузка коллекций внутри коллекций будет умножать общее количество извлекаемых строк в картезианской форме. И объединенная, и подзапросная загрузка всегда соединяются с исходным родительским классом; при загрузке коллекции на четыре уровня в глубину будет четыре JOIN на родительский класс. Селективная загрузка, с другой стороны, всегда будет иметь только один JOIN на непосредственную родительскую таблицу.

• Используя selectin loading, загрузка 100 объектов также выдаст два SQL-запроса, второй из которых обращается к 100 первичным ключам загруженных объектов. selectin loading, однако, выводит не более 500 значений первичных ключей в один SELECT-запрос; таким образом, для коллекции свинца, превышающей 500, будет выдан SELECT-запрос для каждой партии из 500 выбранных объектов.

• Использование нескольких уровней глубины с селективной загрузкой не приводит к «картезианской» проблеме, которую имеют объединенные и подзапросы с жаждой загрузки; запросы для селективной загрузки имеют наилучшие характеристики производительности и наименьшее количество строк. Единственная оговорка заключается в том, что в зависимости от размера результата вывода может быть выдано более одного SELECT.

• Загрузка selectin, в отличие от объединенной (при использовании коллекций) и нетерпеливой загрузки подзапросов (все виды отношений), потенциально совместима с пакетной обработкой наборов результатов, предоставляемой Query.yield_per() при условии наличия соответствующего драйвера базы данных, поэтому может позволить пакетную обработку больших наборов результатов.

• Ссылка «Многие к одному

• При использовании ленивой загрузки по умолчанию, загрузка 100 объектов, как в случае с коллекцией, приведет к 101 SQL-запросу. Однако из этого есть существенное исключение, заключающееся в том, что если ссылка «многие-к-одному» является простой ссылкой внешнего ключа на первичный ключ цели, каждая ссылка будет проверяться первой в текущей карте идентификации с помощью Query.get(). Таким образом, если коллекция объектов ссылается на относительно небольшой набор целевых объектов, или полный набор возможных целевых объектов уже загружен в сессию и на них имеются сильные ссылки, использование значения по умолчанию lazy=“select“ является наиболее эффективным способом.

• При использовании объединенной загрузки загрузка 100 объектов вызовет только один SQL-запрос. Объединение будет представлять собой LEFT OUTER JOIN, а общее количество строк во всех случаях будет равно 100. Если вы знаете, что у каждого родителя определенно есть потомок (т.е. ссылка внешнего ключа NOT NULL), то объединенную загрузку можно настроить так, чтобы relationship.innerjoin было установлено значение True, которое обычно указывается в relationship(). Для загрузки объектов, где существует множество возможных целевых ссылок, которые, возможно, еще не были загружены, объединенная загрузка с помощью INNER JOIN является чрезвычайно эффективной.

• При загрузке подзапросов будет выполнена вторая загрузка для всех дочерних объектов, поэтому при загрузке 100 объектов будет выполнено два SQL-запроса. Вероятно, здесь нет особых преимуществ по сравнению с объединенной загрузкой, за исключением, пожалуй, того, что при загрузке подзапросов можно использовать INNER JOIN во всех случаях, в то время как при объединенной загрузке требуется, чтобы внешний ключ был NOT NULL.

• При селективной загрузке также будет выполнена вторая загрузка для всех дочерних объектов (и, как уже говорилось, для больших результатов она будет выдавать SELECT на 500 строк), поэтому для загрузки 100 объектов будет выполнено два SQL-запроса. Сам запрос все равно должен соединиться с родительской таблицей, так что опять же, нет особых преимуществ в селективной загрузке для многих к одному по сравнению с объединенной загрузкой, за исключением использования INNER JOIN во всех случаях.

Полиморфная нетерпеливая загрузка¶

Поддерживается задание полиморфных опций для каждой отдельной нагрузки. Примеры использования метода Стремительная загрузка специфических или полиморфных подтипов в сочетании с функцией PropComparator.of_type() см. в разделе with_polymorphic().

Стратегии загрузки подстановочных знаков¶

Каждый из joinedload(), subqueryload(), lazyload(), selectinload(), noload() и raiseload() может быть использован для установки стиля загрузки relationship() по умолчанию для конкретного запроса, влияющего на все relationship() - сопоставленные атрибуты, не указанные в Query. Эта возможность доступна при передаче строки '*' в качестве аргумента к любой из этих опций:

session.query(MyClass).options(lazyload("*"))

Выше, опция lazyload('*') заменит установку lazy всех конструкций relationship(), используемых для данного запроса, за исключением тех, которые используют стиль загрузки 'dynamic'. Если некоторые отношения указывают lazy='joined' или lazy='subquery', например, использование lazyload('*') в одностороннем порядке заставит все эти отношения использовать загрузку 'select', например, выдавать оператор SELECT при обращении к каждому атрибуту.

Опция не заменяет опции загрузчика, указанные в запросе, такие как eagerload(), subqueryload() и т.д. В приведенном ниже запросе для отношения widget по-прежнему будет использоваться объединенная загрузка:

session.query(MyClass).options(lazyload("*"), joinedload(MyClass.widget))

Если передано несколько опций '*', последняя из них отменяет ранее переданные.

session.query(User, Address).options(Load(Address).lazyload("*"))

Маршрутизация явных соединений/заявлений в загружаемые коллекции¶

Поведение joinedload() таково, что соединения создаются автоматически, используя анонимные псевдонимы в качестве целей, результаты которых направляются в коллекции и скалярные ссылки на загруженные объекты. Часто бывает так, что запрос уже включает необходимые соединения, которые представляют определенную коллекцию или скалярную ссылку, и соединения, добавленные функцией joinedload, являются избыточными - но вы все равно хотите, чтобы коллекции/ссылки были заполнены.

Для этого SQLAlchemy предоставляет опцию contains_eager(). Эта опция используется так же, как и опция joinedload(), за исключением того, что предполагается, что в Query будут явно указаны соответствующие соединения. Ниже мы указываем соединение между User и Address и дополнительно устанавливаем его в качестве основы для нетерпеливой загрузки User.addresses:

class User(Base):
    __tablename__ = "user"
    id = Column(Integer, primary_key=True)
    addresses = relationship("Address")


class Address(Base):
    __tablename__ = "address"

    # ...


q = session.query(User).join(User.addresses).options(contains_eager(User.addresses))

Если часть оператора «eager» является «aliased», путь должен быть указан с помощью PropComparator.of_type(), что позволяет передать конкретную конструкцию aliased():

# use an alias of the Address entity
adalias = aliased(Address)

# construct a Query object which expects the "addresses" results
query = (
    session.query(User)
    .outerjoin(User.addresses.of_type(adalias))
    .options(contains_eager(User.addresses.of_type(adalias)))
)

# get results normally
r = query.all()
SELECT
    users.user_id AS users_user_id,
    users.user_name AS users_user_name,
    adalias.address_id AS adalias_address_id,
    adalias.user_id AS adalias_user_id,
    adalias.email_address AS adalias_email_address,
    (...other columns...)
FROM users
LEFT OUTER JOIN email_addresses AS email_addresses_1
ON users.user_id = email_addresses_1.user_id

Путь, указанный в качестве аргумента для contains_eager(), должен быть полным путем от начальной сущности. Например, если бы мы загружали Users->orders->Order->items->Item, опция использовалась бы как:

query(User).options(contains_eager(User.orders).contains_eager(Order.items))

q = (
    session.query(User)
    .join(User.addresses)
    .filter(Address.email_address.like("%@aol.com"))
    .options(contains_eager(User.addresses))
    .populate_existing()
)

Создание пользовательских правил загрузки¶

ORM имеет различные граничные случаи, когда значение атрибута доступно локально, однако сам ORM об этом не знает. Существуют также случаи, когда желательна определяемая пользователем система загрузки атрибутов. Для поддержки случаев использования пользовательских систем загрузки предусмотрена ключевая функция set_committed_value(). Эта функция в основном эквивалентна собственной функции Python setattr(), за исключением того, что при ее применении к целевому объекту обходится система «истории атрибутов» SQLAlchemy, которая используется для определения изменений во время промывки; атрибут назначается таким же образом, как если бы ORM загружал его из базы данных.

Использование set_committed_value() может быть объединено с другим ключевым событием, известным как InstanceEvents.load(), для создания поведения атрибутов-населения при загрузке объекта. Одним из таких примеров является двунаправленный случай «один-к-одному», когда загрузка стороны «многие-к-одному» объекта «один-к-одному» должна также подразумевать значение стороны «один-ко-многим». SQLAlchemy ORM не учитывает обратные ссылки при загрузке связанных объектов, и рассматривает «один-к-одному» как еще один «один-ко-многим», который просто оказывается одной строкой.

Учитывая следующее отображение:

from sqlalchemy import Integer, ForeignKey, Column
from sqlalchemy.orm import relationship, backref
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class A(Base):
    __tablename__ = "a"
    id = Column(Integer, primary_key=True)
    b_id = Column(ForeignKey("b.id"))
    b = relationship("B", backref=backref("a", uselist=False), lazy="joined")


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)

Если мы запросим строку A, а затем запросим a.b.a, мы получим дополнительный SELECT:

>>> a1.b.a
SELECT a.id AS a_id, a.b_id AS a_b_id
FROM a
WHERE ? = a.b_id

Этот SELECT является избыточным, поскольку b.a является тем же значением, что и a1. Мы можем создать правило загрузки, которое будет заполнять его для нас:

from sqlalchemy import event
from sqlalchemy.orm import attributes


@event.listens_for(A, "load")
def load_b(target, context):
    if "b" in target.__dict__:
        attributes.set_committed_value(target.b, "a", target)

Теперь при запросе A мы получим A.b из объединенного eager load, и A.b.a из нашего события:

a1 = s.query(A).first()
SELECT
    a.id AS a_id,
    a.b_id AS a_b_id,
    b_1.id AS b_1_id
FROM a
LEFT OUTER JOIN b AS b_1 ON b_1.id = a.b_id
 LIMIT ? OFFSET ?
(1, 0)
assert a1.b.a is a1

API загрузчика отношений¶