SQLAlchemy多态查询异常：返回父类对象而非子类对象

核心排查点及修复步骤 #

1. 确认多态标识与父类映射配置 #

命令式映射必须显式为子类指定polymorphic_identity，父类需定义polymorphic_on字段，且数据库中标识字段的值要与配置完全匹配：

# 父类Message映射
mapper_registry.map_imperatively(Message, message_table,
    polymorphic_on=message_table.c.type,
    polymorphic_identity='message'  # 父类无实例可省略
)

# UserMessage子类映射
mapper_registry.map_imperatively(UserMessage, user_message_table,
    inherits=Message,
    polymorphic_identity='user'  # 需与数据库type字段值完全一致
)

# BotMessage子类映射同理
mapper_registry.map_imperatively(BotMessage, bot_message_table,
    inherits=Message,
    polymorphic_identity='bot'
)

注意：数据库type字段的字符串大小写、格式必须和polymorphic_identity严格对应，否则无法匹配子类。

2. 修正with_polymorphic的使用方式 #

确保查询时正确指定要加载的子类，两种有效写法：

• 加载所有子类：

session.query(Message).with_polymorphic('*').all()

• 加载指定子类：

session.query(Message).with_polymorphic([UserMessage, BotMessage]).all()

错误写法：with_polymorphic(Message)只会返回父类对象，等于未启用多态加载。

3. 验证子类表的外键关联 #

子类表必须通过外键与父类表关联，映射时inherits参数要正确绑定父类：

# 示例：user_message_table需包含指向message_table的外键
user_message_table = Table(
    'user_message', metadata,
    Column('id', Integer, ForeignKey('message.id'), primary_key=True),
    # 其他子类专属字段
)

外键缺失或关联错误时，SQLAlchemy无法关联父类与子类数据，会默认返回父类对象。

4. 检查查询语句的字段选择 #

不要手动指定仅查询父类表字段，否则会阻断子类数据的加载：

# 错误示例：仅查父类字段，无法加载子类
session.query(Message.id, Message.content).with_polymorphic('*').all()

正确做法：直接查询父类实体Message，让SQLAlchemy自动处理联合查询逻辑。

5. 升级SQLAlchemy版本 #

旧版本（如1.3.x及更早）对命令式映射的多态支持存在bug，建议升级到2.0+稳定版：

pip install --upgrade sqlalchemy

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