SQLAlchemy两种selectinload写法差异及报错原因解析

问题背景 #

在项目中设置了lazy='raise'防止隐式懒加载，遇到以下两种预加载写法表现完全不同：

1. selectinload(JobDto.project, ProjectDto.project_defaults) —— 执行报错
2. selectinload(JobDto.project).selectinload(ProjectDto.project_defaults) —— 正常工作

报错信息：

Issue: 'JobDto.project' is not available due to lazy='raise'

模型定义 #

class JobDto(Base):
    __tablename__ = 'job'
    job_id = Column(BigInteger, primary_key=True)
    project_id = Column(Integer, ForeignKey('project.project_id'))
    project = relationship("ProjectDto", foreign_keys=[project_id], lazy='raise')


class ProjectDto(Base):
    __tablename__ = 'project'
    project_id = Column(Integer, primary_key=True)
    name = Column(String(255))
    project_defaults = relationship(
        "ProjectDefaultDto",
        cascade="save-update, merge, delete, delete-orphan",
        lazy='raise'
    )


class ProjectDefaultDto(Base):
    __tablename__ = 'project_default'
    project_default_id = Column(Integer, primary_key=True)
    project_id = Column(Integer, ForeignKey('project.project_id'))

查询示例 #

stmt = (
    select(JobDto)
    .options(
        # 可行
        selectinload(JobDto.project).selectinload(ProjectDto.project_defaults)

        # 报错："JobDto.project is not available due to lazy='raise'"
        # selectinload(JobDto.project, ProjectDto.project_defaults)
    )
)

内部解析逻辑 #

1. 多参数写法：selectinload(A关联, B关联) #

SQLAlchemy对这种写法的处理是：所有参数都是当前查询模型（这里是JobDto）的直接关联，它不会把第二个参数解析为第一个关联对象的嵌套关联。

在你的案例中，ProjectDto.project_defaults是ProjectDto的关联，但当前上下文是JobDto，SQLAlchemy会尝试从JobDto的角度处理这个参数——要么认为这是JobDto的一个关联（实际不是），要么试图通过未预加载的JobDto.project去访问它，而因为JobDto.project的lazy是raise，直接触发了懒加载限制，所以报错。

简单说：多参数写法是用来批量加载同一模型的多个平级关联，不是嵌套关联。

2. 链式调用写法：selectinload(A关联).selectinload(B关联) #

这种链式调用是SQLAlchemy设计的嵌套预加载语法：

• 第一个selectinload(JobDto.project)告诉SQLAlchemy要预加载JobDto的project关联，同时返回一个针对ProjectDto的加载上下文。
• 接着调用的selectinload(ProjectDto.project_defaults)是在这个ProjectDto的上下文中执行的，明确表示要预加载ProjectDto的project_defaults关联。

整个过程SQLAlchemy会分两步批量查询：先查所有Job对应的Project，再查这些Project对应的ProjectDefaults，全程都是显式预加载，不会触发lazy='raise'的限制。

适用场景 #

• 多参数写法：当需要一次性加载同一模型的多个平级关联时使用，比如同时加载JobDto的project和另一个关联（如JobDto.owner），写法为selectinload(JobDto.project, JobDto.owner)。
• 链式写法：当需要加载嵌套层级的关联时使用，比如Job -> Project -> ProjectDefaults这种多层关联，通过链式调用逐层指定预加载的关联。

内容的提问来源于stack exchange，提问作者Ah_Ch_97