
本文介绍如何在 SQLAlchemy 中通过 load_only() 配合 joinedload,仅加载一对一双向关联中子表(如 Devices)的特定字段(如 state),避免冗余数据传输,同时保持对象嵌套访问语法(如 obj.device.state)。
本文介绍如何在 sqlalchemy 中通过 `load_only()` 配合 `joinedload`,仅加载一对一双向关联中子表(如 devices)的特定字段(如 `state`),避免冗余数据传输,同时保持对象嵌套访问语法(如 `obj.device.state`)。
在使用 SQLAlchemy 进行一对一双向关联查询时,常遇到这样的需求:主表(如 Objects)需完整加载,而关联表(如 Devices)仅需其中若干字段(例如仅 state,无需 settings 或其他大体积 JSON 字段)。若直接使用 joinedload(Objects.device),SQLAlchemy 默认会加载 Devices 的全部列,造成带宽浪费与内存开销;若改用原生 select() + join(),又会破坏 ORM 对象结构——返回的是元组而非嵌套对象,无法通过 res.device.state 访问。
✅ 正确解法是结合 joinedload 与 load_only:
from sqlalchemy.orm import joinedload, load_only
# 查询单个对象,并仅加载 Devices.state(自动包含 Devices.id 作为外键)
stmt = (
select(Objects)
.options(joinedload(Objects.device).load_only(Devices.state))
.where(Objects.id == device_id)
)
result = session.execute(stmt).scalars().one()
# ✅ 可以自然访问:
print(result.id) # Objects.id
print(result.type) # Objects.type
print(result.device.state) # Devices.state(已加载)
# print(result.device.settings) # ❌ AttributeError: 'Devices' object has no attribute 'settings'⚠️ 注意事项:
- load_only() 必须与 joinedload()(或 selectinload())配合使用,不能单独用于 select() 构建的语句;
- SQLAlchemy 会自动包含关联表的主键/外键列(如 Devices.id),这是关系映射所必需的,不可省略;
- 若需加载多个字段,可传入多个列:.load_only(Devices.state, Devices.type);
- load_only() 仅影响 ORM 加载行为,不会改变 SQL 的 SELECT 列表(底层仍为 SELECT ... FROM objects JOIN devices ON ...),但会将未指定字段设为 None 或延迟未加载状态;
- 确保 Devices 模型中已正确定义 relationship 的 lazy 参数(推荐保持默认 'select' 或显式设为 'joined' 以配合 joinedload)。
? 补充技巧:若需返回字典格式(如 API 序列化),可在查询后手动构造:
data = {
"id": result.id,
"type": result.type,
"name": result.name,
"device": {
"state": result.device.state if result.device else None,
"settings": None, # 显式置空,符合预期结构
"type": None
}
}综上,joinedload(...).load_only(...) 是平衡性能与开发体验的最佳实践——既减少数据库负载与网络传输,又维持清晰、可读的 ORM 对象访问模式。

















