基本关系模式¶

基本关系模式的快速浏览，本节使用基于声明式样式映射和 Mapped 注解类型的使用进行说明。

以下各节的设置如下

from __future__ import annotations
from typing import List

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

声明式与命令式形式¶

随着 SQLAlchemy 的发展，出现了不同的 ORM 配置样式。本节以及其他使用带有 Mapped 的注解声明式映射的示例中，相应的非注解形式应使用所需的类或字符串类名作为传递给 relationship() 的第一个参数。下面的示例说明了本文档中使用的形式，这是一个完全声明式的示例，使用了 PEP 484 注解，其中 relationship() 构造也从 Mapped 注解中派生出目标类和集合类型，这是 SQLAlchemy 声明式映射的最现代形式

class Parent(Base):
    __tablename__ = "parent_table"

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


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))
    parent: Mapped["Parent"] = relationship(back_populates="children")

相比之下，使用没有注解的声明式映射是更 “经典” 的映射形式，其中 relationship() 需要将所有参数直接传递给它，如下例所示

class Parent(Base):
    __tablename__ = "parent_table"

    id = mapped_column(Integer, primary_key=True)
    children = relationship("Child", 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="children")

最后，使用命令式映射，这是声明式出现之前 SQLAlchemy 的原始映射形式（尽管如此，仍然受到少数用户的青睐），上述配置看起来像

registry.map_imperatively(
    Parent,
    parent_table,
    properties={"children": relationship("Child", back_populates="parent")},
)

registry.map_imperatively(
    Child,
    child_table,
    properties={"parent": relationship("Parent", back_populates="children")},
)

此外，非注解映射的默认集合样式是 list。要使用 set 或其他没有注解的集合，请使用 relationship.collection_class 参数指示它

class Parent(Base):
    __tablename__ = "parent_table"

    id = mapped_column(Integer, primary_key=True)
    children = relationship("Child", collection_class=set, ...)

有关 relationship() 的集合配置的详细信息，请参阅自定义集合访问。

注解式和非注解式/命令式样式之间的其他差异将在需要时进行说明。

一对多¶

一对多关系在子表上放置一个外键，引用父表。然后在父表上指定 relationship()，作为引用子表表示的项目集合

class Parent(Base):
    __tablename__ = "parent_table"

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


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))

为了在一对多中建立双向关系，其中 “反向” 侧是多对一，请指定一个额外的 relationship()，并使用 relationship.back_populates 参数连接两者，使用每个 relationship() 的属性名称作为另一个 relationship.back_populates 的值

class Parent(Base):
    __tablename__ = "parent_table"

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


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))
    parent: Mapped["Parent"] = relationship(back_populates="children")

Child 将获得一个具有多对一语义的 parent 属性。

为一对多使用集合、列表或其他集合类型¶

使用注解式声明式映射时，用于 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")

当使用非注解形式（包括命令式映射）时，可以用 relationship.collection_class 参数传递要用作集合的 Python 类。

另请参阅

自定义集合访问 - 包含有关集合配置的更多详细信息，包括将 relationship() 映射到字典的一些技术。

配置一对多的删除行为¶

通常情况下，当删除其所属的 Parent 时，应删除所有 Child 对象。要配置此行为，可以使用 delete 中描述的 delete 级联选项。另一个选项是，当 Child 对象与其父对象解除关联时，可以删除该对象。此行为在 delete-orphan 中描述。

另请参阅

delete

将外键 ON DELETE 级联与 ORM 关系一起使用

delete-orphan

多对一¶

多对一在父表中放置一个外键，引用子表。relationship() 在父表上声明，将在其中创建一个新的标量保持属性

class Parent(Base):
    __tablename__ = "parent_table"

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


class Child(Base):
    __tablename__ = "child_table"

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

上面的示例显示了一个多对一关系，它假定非空行为；下一节可为空的多对一说明了一个可为空的版本。

双向行为是通过添加第二个 relationship() 并应用 relationship.back_populates 参数来实现的，在两个方向上都使用，使用每个 relationship() 的属性名称作为另一个 relationship.back_populates 的值

class Parent(Base):
    __tablename__ = "parent_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    child_id: Mapped[int] = mapped_column(ForeignKey("child_table.id"))
    child: Mapped["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 关系未被类型化为允许 None；这源于 Parent.child_id 列本身不可为空，因为它使用 Mapped[int] 类型化。如果我们希望 Parent.child 是一个可为空的多对一，我们可以将 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")

上面，将使用 DDL 创建 Parent.child_id 的列，以允许 NULL 值。当使用带有显式类型声明的 mapped_column() 时，child_id: Mapped[Optional[int]] 的规范等效于将 Column.nullable 设置为 Column 上的 True，而 child_id: Mapped[int] 等效于将其设置为 False。有关此行为的背景信息，请参阅 mapped_column() 从 Mapped 注解派生数据类型和可空性。

提示

如果使用 Python 3.10 或更高版本，则 PEP 604 语法更方便地使用 | None 指示可选类型，当与 PEP 563 推迟注解求值相结合时，这样就不需要字符串引用的类型，看起来会像

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")

一对一¶

从外键的角度来看，一对一本质上是一个一对多关系，但它表示在任何时候都只有一个行引用特定的父行。

当使用带有 Mapped 的注解映射时，“一对一” 约定是通过将非集合类型应用于关系双方的 Mapped 注解来实现的，这将向 ORM 暗示不应在任何一方使用集合，如下例所示

class Parent(Base):
    __tablename__ = "parent_table"

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


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))
    parent: Mapped["Parent"] = relationship(back_populates="child")

上面，当我们加载 Parent 对象时，Parent.child 属性将引用单个 Child 对象，而不是集合。如果我们用一个新的 Child 对象替换 Parent.child 的值，ORM 的工作单元进程将用新的 Child 行替换之前的 Child 行，默认情况下将之前的 child.parent_id 列设置为 NULL，除非设置了特定的级联行为。

提示

如前所述，ORM 将 “一对一” 模式视为一种约定，它假设当它加载 Parent 对象上的 Parent.child 属性时，它只会返回一行。如果返回多于一行，ORM 将发出警告。

但是，上述关系的 Child.parent 侧仍然是 “多对一” 关系。就其本身而言，它不会检测到分配了多个 Child，除非设置了 relationship.single_parent 参数，这可能很有用

class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))
    parent: Mapped["Parent"] = relationship(back_populates="child", single_parent=True)

在设置此参数之外，“一对多” 侧（这里按约定是一对一）也不会可靠地检测到是否将多个 Child 与单个 Parent 关联，例如，在多个 Child 对象处于挂起状态且未持久化到数据库中的情况下。

无论是否使用 relationship.single_parent，建议数据库模式包含唯一约束，以指示 Child.parent_id 列应该是唯一的，以确保在数据库级别，一次只有一个 Child 行可以引用特定的 Parent 行（有关 __table_args__ 元组语法的背景信息，请参阅声明式表配置）

from sqlalchemy import UniqueConstraint


class Child(Base):
    __tablename__ = "child_table"

    id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent_table.id"))
    parent: Mapped["Parent"] = relationship(back_populates="child")

    __table_args__ = (UniqueConstraint("parent_id"),)

2.0 版本新增: relationship() 构造可以从给定的 Mapped 注解中派生出 relationship.uselist 参数的有效值。

为非注解配置设置 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")

多对多¶

多对多在两个类之间添加一个关联表。关联表几乎总是作为核心 Table 对象或其他核心可选择对象（例如 Join 对象）给出，并由 relationship.secondary 参数指示给 relationship()。通常，Table 使用与声明式基类关联的 MetaData 对象，以便 ForeignKey 指令可以找到要链接的远程表

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


# note for a Core table, we use the sqlalchemy.Column construct,
# not sqlalchemy.orm.mapped_column
association_table = Table(
    "association_table",
    Base.metadata,
    Column("left_id", ForeignKey("left_table.id")),
    Column("right_id", ForeignKey("right_table.id")),
)


class Parent(Base):
    __tablename__ = "left_table"

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


class Child(Base):
    __tablename__ = "right_table"

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

提示

上面的 “关联表” 建立了外键约束，这些约束引用关系两侧的两个实体表。association.left_id 和 association.right_id 中每一个的数据类型通常从被引用表的类型推断出来，可以省略。还建议（尽管 SQLAlchemy 没有任何要求），引用两个实体表的列应在唯一约束或更常见的主键约束中建立；这确保了无论应用程序端出现什么问题，重复行都不会持久化到表中

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),
)

设置双向多对多¶

对于双向关系，关系的双方都包含一个集合。使用 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"
    )

为 “secondary” 参数使用延迟求值形式¶

relationship.secondary 参数 relationship() 也接受两种不同的 “延迟求值” 形式，包括字符串表名以及 lambda 可调用对象。有关背景和示例，请参阅为多对多的 “secondary” 参数使用延迟求值形式一节。

为多对多使用集合、列表或其他集合类型¶

多对多关系的集合配置与一对多的集合配置相同，如为一对多使用集合、列表或其他集合类型中所述。对于使用 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)

当使用非注解形式（包括命令式映射）时，与一对一的情况一样，可以用 relationship.collection_class 参数传递要用作集合的 Python 类。

另请参阅

自定义集合访问 - 包含有关集合配置的更多详细信息，包括将 relationship() 映射到字典的一些技术。

从多对多表中删除行¶

relationship() 的 relationship.secondary 参数的独特行为是，此处指定的 Table 会自动接受 INSERT 和 DELETE 语句，因为对象被添加到集合或从集合中删除。无需手动从此表中删除。从集合中删除记录的行为将导致在刷新时删除该行

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

经常出现的一个问题是，当子对象直接传递给 Session.delete() 时，如何删除 “secondary” 表中的行

session.delete(somechild)

这里有几种可能性

如果存在从 Parent 到 Child 的 relationship()，但没有反向关系将特定的 Child 链接到每个 Parent，则 SQLAlchemy 不会意识到在删除此特定 Child 对象时，它需要维护将其链接到 Parent 的 “secondary” 表。不会发生 “secondary” 表的删除。
如果存在将特定 Child 链接到每个 Parent 的关系，假设它称为 Child.parents，则默认情况下，SQLAlchemy 将加载 Child.parents 集合以查找所有 Parent 对象，并从 “secondary” 表中删除建立此链接的每一行。请注意，此关系不需要是双向的；SQLAlchemy 严格查看与要删除的 Child 对象关联的每个 relationship()。
这里性能更高的选项是将 ON DELETE CASCADE 指令与数据库使用的外键一起使用。假设数据库支持此功能，则可以使数据库本身在删除 “child” 中的引用行时自动删除 “secondary” 表中的行。在这种情况下，可以使用 relationship.passive_deletes 指令在 relationship() 上指示 SQLAlchemy 放弃主动加载 Child.parents 集合；有关此的更多详细信息，请参阅将外键 ON DELETE 级联与 ORM 关系一起使用。

再次注意，这些行为仅与 relationship() 使用的 relationship.secondary 选项相关。如果处理显式映射且不在相关 relationship() 的 relationship.secondary 选项中出现的关联表，则可以使用级联规则来自动删除实体，以响应相关实体被删除 - 有关此功能的信息，请参阅级联。

另请参阅

将删除级联与多对多关系一起使用

将外键 ON DELETE 与多对多关系一起使用

关联对象¶

关联对象模式是多对多的一种变体：当关联表包含除父表和子表（或左表和右表）的外键之外的其他列时使用，这些列最好映射到它们自己的 ORM 映射类。此映射类是针对 Table 映射的，否则在使用多对多模式时，该表将被标记为 relationship.secondary。

在关联对象模式中，不使用 relationship.secondary 参数；相反，一个类直接映射到关联表。然后，两个单独的 relationship() 构造首先通过一对多将父侧链接到映射的关联类，然后通过多对一将映射的关联类链接到子侧，从而形成从父级到关联对象再到子级的单向关联对象关系。对于双向关系，使用四个 relationship() 构造，以在两个方向上将映射的关联类链接到父级和子级。

以下示例展示了一个新的类 Association，它映射到名为 association 的 Table；这个表现在包含一个名为 extra_data 的额外列，它是一个字符串值，与 Parent 和 Child 之间的每个关联一起存储。通过将表映射到一个显式的类，从 Parent 到 Child 的基本访问显式地使用了 Association

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]]
    child: Mapped["Child"] = relationship()


class Parent(Base):
    __tablename__ = "left_table"
    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[List["Association"]] = relationship()


class Child(Base):
    __tablename__ = "right_table"
    id: Mapped[int] = mapped_column(primary_key=True)

为了说明双向版本，我们添加了另外两个 relationship() 构造，使用 relationship.back_populates 链接到现有的构造

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]]
    child: Mapped["Child"] = relationship(back_populates="parents")
    parent: Mapped["Parent"] = relationship(back_populates="children")


class Parent(Base):
    __tablename__ = "left_table"
    id: Mapped[int] = mapped_column(primary_key=True)
    children: Mapped[List["Association"]] = relationship(back_populates="parent")


class Child(Base):
    __tablename__ = "right_table"
    id: Mapped[int] = mapped_column(primary_key=True)
    parents: Mapped[List["Association"]] = relationship(back_populates="child")

直接形式的关联模式要求子对象在附加到父对象之前与关联实例关联；同样，从父对象到子对象的访问也需要通过关联对象

# create parent, append a child via association
p = Parent()
a = Association(extra_data="some data")
a.child = Child()
p.children.append(a)

# iterate through child objects via association, including association
# attributes
for assoc in p.children:
    print(assoc.extra_data)
    print(assoc.child)

为了增强关联对象模式，以便可以直接访问 Association 对象成为可选操作，SQLAlchemy 提供了 Association Proxy 扩展。此扩展允许配置属性，这些属性将通过单次访问实现两次“跳跃”，一次“跳跃”到关联对象，第二次“跳跃”到目标属性。

另请参阅

Association Proxy - 允许在父对象和子对象之间进行直接的“多对多”样式访问，用于三类关联对象映射。

警告

避免将关联对象模式与直接的多对多模式混合使用，因为这会产生在没有特殊步骤的情况下，数据可能以不一致的方式读取和写入的情况；association proxy 通常用于提供更简洁的访问。有关这种组合引入的注意事项的更详细背景信息，请参阅下一节将关联对象与多对多访问模式结合使用。

将关联对象与多对多访问模式结合使用¶

如上一节所述，关联对象模式不会自动与同时对相同表/列使用多对多模式集成。由此可见，读取操作可能会返回冲突的数据，写入操作也可能尝试刷新冲突的更改，从而导致完整性错误或意外的插入或删除。

为了说明这一点，以下示例配置了 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 所做的更改不会与对 Python 中 Parent.child_associations 或 Child.parent_associations 所做的更改协调；虽然所有这些关系本身将继续正常运行，但除非 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 语句中“secondary”表的使用方式。至少最好将 relationship.viewonly 参数应用于“secondary”关系，以避免发生冲突更改的问题，并防止将 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，从而防止冲突的写入。但是，如果在一个事务或与读取 viewonly 集合的 Session 相同的事务或 Session 中对这些集合进行了更改，则从 Parent.children 或 Child.parents 读取的数据不一定与从 Parent.child_associations 或 Child.parent_associations 读取的数据匹配。如果关联对象关系的使用频率不高，并且针对访问多对多集合的代码进行了仔细组织以避免过时读取（在极端情况下，直接使用 Session.expire() 以使集合在当前事务中刷新），则此模式可能是可行的。

上述模式的一种流行的替代方案是，直接的多对多 Parent.children 和 Child.parents 关系被一个扩展取代，该扩展将透明地代理 Association 类，同时从 ORM 的角度保持一切一致。此扩展称为 Association Proxy。

另请参阅

Association Proxy - 允许在父对象和子对象之间进行直接的“多对多”样式访问，用于三类关联对象映射。

关系参数的延迟评估¶

前面章节中的大多数示例都展示了各种 relationship() 构造使用字符串名称而不是类本身来引用其目标类的情况，例如在使用 Mapped 时，会生成一个仅在运行时作为字符串存在的前向引用

class Parent(Base):
    # ...

    children: Mapped[List["Child"]] = relationship(back_populates="parent")


class Child(Base):
    # ...

    parent: Mapped["Parent"] = relationship(back_populates="children")

类似地，当使用非注解形式（例如非注解声明式或命令式映射）时，relationship() 构造也直接支持字符串名称

registry.map_imperatively(
    Parent,
    parent_table,
    properties={"children": relationship("Child", back_populates="parent")},
)

registry.map_imperatively(
    Child,
    child_table,
    properties={"parent": relationship("Parent", back_populates="children")},
)

这些字符串名称在映射器解析阶段被解析为类，这是一个内部过程，通常在定义所有映射之后发生，并且通常由映射本身的首次使用触发。registry 对象是存储这些名称并将其解析为它们引用的映射类的容器。

除了 relationship() 的主类参数之外，其他依赖于尚未定义的类上存在的列的参数也可以指定为 Python 函数，或更常见的是字符串。对于除主参数之外的大多数这些参数，字符串输入被评估为使用 Python 内置 eval() 函数的 Python 表达式，因为它们旨在接收完整的 SQL 表达式。

警告

由于 Python 的 eval() 函数用于解释传递给 relationship() 映射器配置构造的延迟评估的字符串参数，因此不应重新调整这些参数的用途，使其接收不受信任的用户输入；eval() 对于不受信任的用户输入是不安全的。

此评估中可用的完整命名空间包括为此声明性基类映射的所有类，以及 sqlalchemy 包的内容，包括诸如 desc() 和 sqlalchemy.sql.functions.func 之类的表达式函数

class Parent(Base):
    # ...

    children: Mapped[List["Child"]] = relationship(
        order_by="desc(Child.email_address)",
        primaryjoin="Parent.id == Child.parent_id",
    )

对于多个模块包含同名类的情况，字符串类名也可以在任何这些字符串表达式中指定为模块限定路径

class Parent(Base):
    # ...

    children: Mapped[List["myapp.mymodel.Child"]] = relationship(
        order_by="desc(myapp.mymodel.Child.email_address)",
        primaryjoin="myapp.mymodel.Parent.id == myapp.mymodel.Child.parent_id",
    )

在上面的示例中，传递给 Mapped 的字符串可以通过将类位置字符串直接传递给 relationship.argument 来与特定的类参数区分开。下面说明了 Child 的仅类型导入，以及将在 registry 中搜索正确名称的目标类的运行时说明符

import typing

if typing.TYPE_CHECKING:
    from myapp.mymodel import Child


class Parent(Base):
    # ...

    children: Mapped[List["Child"]] = relationship(
        "myapp.mymodel.Child",
        order_by="desc(myapp.mymodel.Child.email_address)",
        primaryjoin="myapp.mymodel.Parent.id == myapp.mymodel.Child.parent_id",
    )

限定路径可以是任何消除名称歧义的部分路径。例如，为了消除 myapp.model1.Child 和 myapp.model2.Child 之间的歧义，我们可以指定 model1.Child 或 model2.Child

class Parent(Base):
    # ...

    children: Mapped[List["Child"]] = relationship(
        "model1.Child",
        order_by="desc(mymodel1.Child.email_address)",
        primaryjoin="Parent.id == model1.Child.parent_id",
    )

relationship() 构造也接受 Python 函数或 lambda 作为这些参数的输入。Python 函数式方法可能如下所示

import typing

from sqlalchemy import desc

if typing.TYPE_CHECKING:
    from myapplication import Child


def _resolve_child_model():
    from myapplication import Child

    return Child


class Parent(Base):
    # ...

    children: Mapped[List["Child"]] = relationship(
        _resolve_child_model,
        order_by=lambda: desc(_resolve_child_model().email_address),
        primaryjoin=lambda: Parent.id == _resolve_child_model().parent_id,
    )

接受 Python 函数/lambda 或将传递给 eval() 的字符串的完整参数列表是

警告

如前所述，relationship() 的上述参数被评估为使用 eval() 的 Python 代码表达式。请勿将不受信任的输入传递给这些参数。

在声明后向映射类添加关系¶

还应该注意的是，与向现有声明式映射类追加额外的列中描述的方式类似，任何 MapperProperty 构造都可以在任何时候添加到声明性基类映射中（注意在这种上下文中不支持注解形式）。如果我们想在 Address 类可用后实现此 relationship()，我们也可以在之后应用它

# 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() 构造中指定，可以是类本身、类的字符串名称，也可以是返回对目标类引用的可调用函数。

注意

与 ORM 映射列的情况一样，只有在使用“声明性基类”类（即 DeclarativeBase 的用户定义子类或由 declarative_base() 或 registry.generate_base() 返回的动态生成的类）时，将映射属性分配给已映射的类才能正常工作。这个“基类”类包含一个 Python 元类，该元类实现了一个特殊的 __setattr__() 方法来拦截这些操作。

如果类是使用装饰器（如 registry.mapped()）或命令式函数（如 registry.map_imperatively()）映射的，则运行时将类映射的属性分配给映射类将不起作用。

对多对多的“secondary”参数使用延迟评估形式¶

多对多关系使用 relationship.secondary 参数，该参数通常指示对通常未映射的 Table 对象或其他 Core 可选对象的引用。使用 lambda 可调用对象的延迟评估是典型的。

对于多对多中给出的示例，如果我们假设 association_table Table 对象将在模块中晚于映射类本身的点定义，我们可以使用 lambda 将 relationship() 编写为

class Parent(Base):
    __tablename__ = "left_table"

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

作为也是有效 Python 标识符的表名的快捷方式，relationship.secondary 参数也可以作为字符串传递，其中解析的工作方式是通过评估字符串作为 Python 表达式，简单的标识符名称链接到当前 registry 引用的同一 MetaData 集合中存在的同名 Table 对象。

在下面的示例中，表达式 "association_table" 被评估为一个名为 “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")

注意

当作为字符串传递时，传递给 relationship.secondary 的名称必须是有效的 Python 标识符，以字母开头，并且仅包含字母数字字符或下划线。其他字符（例如破折号等）将被解释为 Python 运算符，这些运算符将无法解析为给定的名称。请考虑使用 lambda 表达式而不是字符串以提高清晰度。

警告

当作为字符串传递时，relationship.secondary 参数是使用 Python 的 eval() 函数解释的，即使它通常是表名。请勿将不受信任的输入传递给此字符串。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

项目版本

基本关系模式¶

声明式与命令式形式¶

一对多¶

为一对多使用集合、列表或其他集合类型¶

配置一对多的删除行为¶

多对一¶

可为空的多对一¶

一对一¶

为非注解配置设置 uselist=False¶

多对多¶

设置双向多对多¶

为 “secondary” 参数使用延迟求值形式¶

为多对多使用集合、列表或其他集合类型¶

从多对多表中删除行¶

关联对象¶

将关联对象与多对多访问模式结合使用¶

关系参数的延迟评估¶

在声明后向映射类添加关系¶

对多对多的“secondary”参数使用延迟评估形式¶