Основные модели взаимоотношений¶

Использование наборов, списков или других типов коллекций для «один ко многим¶

При использовании аннотированных декларативных отображений тип коллекции, используемый для relationship(), получается из типа коллекции, переданного типу контейнера Mapped. Пример из предыдущего раздела может быть написан так, чтобы использовать set, а не list для коллекции Parent.children, используя Mapped[Set["Child"]]:

class Parent(Base):
    __tablename__ = "parent_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[Set["Child"]] = relationship(back_populates="parent")

При использовании неаннотированных форм, включая императивные отображения, класс Python для использования в качестве коллекции может быть передан с помощью параметра relationship.collection_class.

Настройка поведения удаления для одного ко многим¶

Часто бывает так, что все объекты Child должны удаляться, когда удаляется принадлежащий им объект Parent. Для настройки такого поведения используется опция каскада delete, описанная в удалить. Дополнительная опция заключается в том, что объект Child может сам удаляться, когда он деассоциирован от своего родителя. Это поведение описано в delete-orphan.

Nullable Many-to-One¶

В предыдущем примере отношение Parent.child не типизировано как допускающее None; это следует из того, что сам столбец Parent.child_id не является нулевым, поскольку он типизирован с помощью Mapped[int]. Если мы хотим, чтобы Parent.child был nullable many-to-one, мы можем установить и Parent.child_id и Parent.child как Optional[], в этом случае конфигурация будет выглядеть так:

from typing import Optional


class Parent(Base):
    __tablename__ = "parent_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    child_id: Mapped[Optional[int]] = mapped_column(ForeignKey("child_table.id"))
    child: Mapped[Optional["Child"]] = relationship(back_populates="parents")


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parents: Mapped[List["Parent"]] = relationship(back_populates="child")

Выше, столбец для Parent.child_id будет создан в DDL, чтобы разрешить значения NULL. При использовании mapped_column() с явными объявлениями типизации, спецификация child_id: Mapped[Optional[int]] эквивалентна установке Column.nullable в True на Column, тогда как child_id: Mapped[int] эквивалентна установке в False. См. раздел mapped_column() берет тип данных и нулевую возможность из аннотации Mapped для получения информации об этом поведении.

from __future__ import annotations


class Parent(Base):
    __tablename__ = "parent_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    child_id: Mapped[int | None] = mapped_column(ForeignKey("child_table.id"))
    child: Mapped[Child | None] = relationship(back_populates="parents")


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parents: Mapped[List[Parent]] = relationship(back_populates="child")

Установка uselist=False для неаннотированных конфигураций¶

При использовании relationship() без использования аннотаций Mapped, шаблон один-к-одному может быть включен с помощью параметра relationship.uselist, установленного на False на той стороне, которая обычно была бы «много», как показано ниже в неаннотированной декларативной конфигурации:

class Parent(Base):
    __tablename__ = "parent_table"

    id = mapped_column(Integer, primary_key=True)
    child = relationship("Child", uselist=False, back_populates="parent")


class Child(Base):
    __tablename__ = "child_table"

    id = mapped_column(Integer, primary_key=True)
    parent_id = mapped_column(ForeignKey("parent_table.id"))
    parent = relationship("Parent", back_populates="child")

Настройка двунаправленных «многие-ко-многим¶

Для двунаправленного отношения обе стороны отношения содержат коллекцию. Укажите, используя relationship.back_populates, и для каждой relationship() укажите общую таблицу ассоциации:

from __future__ import annotations

from sqlalchemy import Column
from sqlalchemy import Table
from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


association_table = Table(
    "association_table",
    Base.metadata,
    Column("left_id", ForeignKey("left_table.id"), primary_key=True),
    Column("right_id", ForeignKey("right_table.id"), primary_key=True),
)


class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[List[Child]] = relationship(
        secondary=association_table, back_populates="parents"
    )


class Child(Base):
    __tablename__ = "right_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parents: Mapped[List[Parent]] = relationship(
        secondary=association_table, back_populates="children"
    )

Использование формы с поздней оценкой для «вторичного» аргумента¶

Параметр relationship.secondary в relationship() также принимает две различные формы «поздней оценки», включая строковое имя таблицы, а также лямбда-вызов. Информацию и примеры см. в разделе Использование формы с поздней оценкой для «вторичного» аргумента многие-ко-многим.

Использование наборов, списков или других типов коллекций для многих ко многим¶

Конфигурация коллекций для отношения Many to Many идентична конфигурации Один ко многим, как описано в Использование наборов, списков или других типов коллекций для «один ко многим. Для аннотированного отображения, использующего Mapped, коллекция может быть указана типом коллекции, используемой в рамках общего класса Mapped, например set:

class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[Set["Child"]] = relationship(secondary=association_table)

При использовании неаннотированных форм, включая императивные отображения, как в случае с one-to-many, класс Python для использования в качестве коллекции может быть передан с помощью параметра relationship.collection_class.

Удаление строк из таблицы «Многие ко многим¶

Поведение, уникальное для аргумента relationship.secondary в relationship(), заключается в том, что указанная здесь таблица Table автоматически подвергается операциям INSERT и DELETE, поскольку объекты добавляются или удаляются из коллекции. Нет необходимости удалять из этой таблицы вручную. Акт удаления записи из коллекции будет иметь эффект удаления строки на flush:

# row will be deleted from the "secondary" table
# automatically
myparent.children.remove(somechild)

Часто возникает вопрос, как можно удалить строку во «вторичной» таблице, когда дочерний объект передается непосредственно в Session.delete():

session.delete(somechild)

Здесь есть несколько вариантов:

• Если есть relationship() от Parent к Child, но нет **** обратной связи, которая связывает конкретный Child с каждым Parent, то SQLAlchemy не будет знать, что при удалении этого конкретного объекта Child нужно сохранить «вторичную» таблицу, которая связывает его с Parent. Удаление «вторичной» таблицы не произойдет.

• Если существует отношение, связывающее конкретный Child с каждым Parent, предположим, он называется Child.parents, SQLAlchemy по умолчанию загрузит коллекцию Child.parents, чтобы найти все объекты Parent, и удалит каждую строку из «вторичной» таблицы, которая устанавливает эту связь. Обратите внимание, что эта связь не обязательно должна быть двунаправленной; SQLAlchemy строго просматривает каждый relationship(), связанный с удаляемым Child объектом.

• Более эффективным вариантом здесь является использование директив ON DELETE CASCADE для внешних ключей, используемых базой данных. Если база данных поддерживает эту функцию, то можно заставить саму базу данных автоматически удалять строки во «вторичной» таблице по мере удаления ссылающихся на нее строк в «дочерней». SQLAlchemy можно дать указание отказаться от активной загрузки коллекции Child.parents в этом случае, используя директиву relationship.passive_deletes на relationship(); подробнее об этом см. в Использование каскада внешних ключей ON DELETE с отношениями ORM.

Заметьте еще раз, что это поведение относится только к опции relationship.secondary, используемой с relationship(). Если вы имеете дело с таблицами ассоциаций, которые отображаются явно и не присутствуют в опции relationship.secondary соответствующей опции relationship(), вместо этого можно использовать каскадные правила для автоматического удаления сущностей в ответ на удаление связанной сущности - смотрите Каскады для информации об этой возможности.

Объединение ассоциативного объекта с шаблонами доступа «многие ко многим¶

Как уже упоминалось в предыдущем разделе, модель ассоциативных объектов не интегрируется автоматически с использованием модели «многие ко многим» в отношении одних и тех же таблиц/столбцов в одно и то же время. Из этого следует, что операции чтения могут возвращать противоречивые данные, а операции записи могут также пытаться стирать противоречивые изменения, вызывая либо ошибки целостности, либо неожиданные вставки или удаления.

Для примера ниже настроено двунаправленное отношение «многие-ко-многим» между Parent и Child через Parent.children и Child.parents. В то же время также настраивается объектная связь ассоциации между Parent.child_associations -> Association.child и Child.parent_associations -> Association.parent:

from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class Association(Base):
    __tablename__ = "association_table"

    left_id: Mapped[int] = mapped_column(ForeignKey("left_table.id"), primary_key=True)
    right_id: Mapped[int] = mapped_column(
        ForeignKey("right_table.id"), primary_key=True
    )
    extra_data: Mapped[Optional[str]]

    # association between Assocation -> Child
    child: Mapped["Child"] = relationship(back_populates="parent_associations")

    # association between Assocation -> Parent
    parent: Mapped["Parent"] = relationship(back_populates="child_associations")


class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)

    # many-to-many relationship to Child, bypassing the `Association` class
    children: Mapped[List["Child"]] = relationship(
        secondary="association_table", back_populates="parents"
    )

    # association between Parent -> Association -> Child
    child_associations: Mapped[List["Association"]] = relationship(
        back_populates="parent"
    )


class Child(Base):
    __tablename__ = "right_table"

    id: Mapped[int] = mapped_column(primary_key=True)

    # many-to-many relationship to Parent, bypassing the `Association` class
    parents: Mapped[List["Parent"]] = relationship(
        secondary="association_table", back_populates="children"
    )

    # association between Child -> Association -> Parent
    parent_associations: Mapped[List["Association"]] = relationship(
        back_populates="child"
    )

При использовании этой модели ORM для внесения изменений, изменения, внесенные в Parent.children, не будут согласованы с изменениями, внесенными в Parent.child_associations или Child.parent_associations в Python; хотя все эти отношения будут продолжать нормально функционировать сами по себе, изменения в одном из них не будут отображаться в другом, пока не истечет срок действия Session, что обычно происходит автоматически после Session.commit().

Кроме того, если вносятся противоречивые изменения, например, добавляется новый объект Association и одновременно добавляется такой же связанный объект Child в Parent.children, это приведет к ошибкам целостности при выполнении процесса промывки единицы работы, как в примере ниже:

p1 = Parent()
c1 = Child()
p1.children.append(c1)

# redundant, will cause a duplicate INSERT on Association
p1.child_associations.append(Association(child=c1))

Прямое добавление Child к Parent.children также подразумевает создание строк в таблице association без указания значения для столбца association.extra_data, который получит значение NULL.

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

class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)

    # many-to-many relationship to Child, bypassing the `Association` class
    children: Mapped[List["Child"]] = relationship(
        secondary="association_table", back_populates="parents", viewonly=True
    )

    # association between Parent -> Association -> Child
    child_associations: Mapped[List["Association"]] = relationship(
        back_populates="parent"
    )


class Child(Base):
    __tablename__ = "right_table"

    id: Mapped[int] = mapped_column(primary_key=True)

    # many-to-many relationship to Parent, bypassing the `Association` class
    parents: Mapped[List["Parent"]] = relationship(
        secondary="association_table", back_populates="children", viewonly=True
    )

    # association between Child -> Association -> Parent
    parent_associations: Mapped[List["Association"]] = relationship(
        back_populates="child"
    )

Приведенное выше отображение не будет записывать изменения в Parent.children или Child.parents в базу данных, предотвращая конфликтующие записи. Однако, чтение из Parent.children или Child.parents не обязательно будет соответствовать данным, которые читаются из Parent.child_associations или Child.parent_associations, если изменения в этих коллекциях производятся в той же транзакции или Session, в которой читаются коллекции viewonly. Если использование отношений ассоциативных объектов нечастое и тщательно организовано против кода, который обращается к коллекциям «многие ко многим», чтобы избежать неактуальных чтений (в крайнем случае, прямое использование Session.expire(), чтобы заставить коллекции обновляться в пределах текущей транзакции), паттерн может быть осуществим.

Популярной альтернативой приведенной выше схеме является та, в которой прямые отношения «многие-ко-многим» Parent.children и Child.parents заменяются расширением, которое будет прозрачно проксировать класс Association, сохраняя все последовательным с точки зрения ORM. Это расширение известно как Association Proxy.

Добавление отношений к сопоставленным классам после объявления¶

Следует также отметить, что аналогично тому, как это описано в Добавление дополнительных столбцов к существующему декларативному сопоставленному классу, любая конструкция MapperProperty может быть добавлена к декларативному базовому отображению в любое время (следует отметить, что аннотированные формы не поддерживаются в этом контексте). Если бы мы хотели реализовать эту relationship() после того, как класс Address был доступен, мы могли бы применить ее и после этого:

# first, module A, where Child has not been created yet,
# we create a Parent class which knows nothing about Child


class Parent(Base):
    ...


# ... later, in Module B, which is imported after module A:


class Child(Base):
    ...


from module_a import Parent

# assign the User.addresses relationship as a class variable.  The
# declarative base class will intercept this and map the relationship.
Parent.children = relationship(Child, primaryjoin=Child.parent_id == Parent.id)

Как и в случае сопоставленных колонок ORM, аннотационный тип Mapped не может участвовать в этой операции; поэтому связанный класс должен быть указан непосредственно в конструкции relationship(), либо как сам класс, либо как строковое имя класса, либо как вызываемая функция, возвращающая ссылку на целевой класс.

Использование формы с поздней оценкой для «вторичного» аргумента многие-ко-многим¶

В отношениях «многие-ко-многим» используется параметр relationship.secondary, который обычно указывает на ссылку на обычно не отображаемый объект Table или другой объект Core selectable. Поддерживается поздняя оценка с помощью лямбда-вызова или строкового имени, где разрешение строк работает путем оценки данного выражения Python, которое связывает имена идентификаторов с одноименными объектами Table, которые присутствуют в той же коллекции MetaData, на которую ссылается текущий registry.

Для примера, приведенного в Многие ко многим, если мы предположили, что объект association_table Table будет определен в более поздней точке модуля, чем сам отображаемый класс, мы можем написать relationship(), используя лямбду as:

class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[List["Child"]] = relationship(
        "Child", secondary=lambda: association_table
    )

Или для иллюстрации нахождения одного и того же объекта Table по имени, в качестве аргумента используется имя Table. С точки зрения Python, это выражение Python, оцениваемое как переменная с именем «association_table», которая разрешается по именам таблиц в коллекции MetaData:

class Parent(Base):
    __tablename__ = "left_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[List["Child"]] = relationship(secondary="association_table")