Subquery 是解决 Django 中 N+1 和跨表聚合的最直接工具，需用 OuterRef 显式关联、values() 返回单列、Coalesce 处理空值，并注意数据库版本兼容性。
Subquery 在 Django 中不是万能的，但它是解决 N+1 和跨表聚合的最直接工具
当你发现 select_related 拉不动、prefetch_related 套太多层还报错，或者需要“对每个 Article 查出它最新一条 Comment 的内容”，这时候就得上 Subquery —— 它本质是把一个 QuerySet 当作字段值嵌进主查询里，由数据库执行子查询。
常见错误现象：ValueError: This queryset contains a reference to an outer query，通常是因为 Subquery 内部没用 OuterRef 关联外层；或者 Subquery returns more than 1 row，说明子查询没加 .first() 或 .order_by().distinct() 约束结果数。
- 必须用
OuterRef('id')显式声明关联字段，不能靠模型关系自动推导 - 子查询本身必须是
.values('field')形式，且只返回单列（否则会报错） - 如果子查询可能为空，记得用
Coalesce(Subquery(...), Value(None))避免字段为 NULL 导致过滤失效
怎么写一个安全的最新评论子查询（带时间排序 + 非空兜底）
场景：给每个 Article 加一个 latest_comment_text 字段，值是它最新一条非删除评论的 content。这不是 annotate 能简单搞定的，因为要先排序再取第一行。
关键点在于子查询必须收敛到单值，且不能因无评论而崩掉主查询：
立即学习“Python免费学习笔记（深入）”；
from django.db.models import OuterRef, Subquery, CharField, Value
from django.db.models.functions import Coalesce
latest_comment_subq = Comment.objects.filter(
article=OuterRef('pk'),
is_deleted=False
).order_by('-created_at').values('content')[:1]
articles = Article.objects.annotate(
latest_comment_text=Coalesce(
Subquery(latest_comment_subq, output_field=CharField()),
Value('')
)
)
-
[:1]比.first()更可靠，后者在 Subquery 中不生效 -
output_field必须显式指定，Django 不会自动推断子查询字段类型 - 如果
Comment.content是TextField，仍可用CharField，数据库会隐式转换；但反过来（如子查询返回长文本却声明为CharField(max_length=100)）可能截断
Subquery 和 PrefetchRelated 哪个更省 DB 查询？
答案取决于你真正要什么：要“每条记录附带一个计算值”，选 Subquery；要“每条记录附带一整组关联对象”，选 prefetch_related。
性能差异很实在：一个 Subquery 是单次 SQL（哪怕内部嵌套），而 prefetch_related 默认是两次查询（主查 + JOIN 查），开启 to_attr 或复杂 Prefetch 对象时可能更多。
- Subquery 的子查询在数据库端执行，网络传输量小，但可能拖慢单条 SQL（尤其子查询没走索引）
- prefetch_related 把拼装逻辑放 Python 层，主查询快，但内存占用高、序列化开销大
- 别在同一个 annotate 里堆多个 Subquery——每个都是一次独立子查询，容易变成“伪 N+1”
PostgreSQL 和 MySQL 对 Subquery 的兼容性差异
Django 的 Subquery 在 PostgreSQL 上几乎全功能支持，MySQL 8.0+ 才支持相关子查询（correlated subquery），5.7 及更早版本会直接报错。
如果你的线上环境还在用 MySQL 5.7，Subquery 里的 OuterRef 基本不可用，得退回到 extra(tables=..., where=...) 或原生 SQL。
- PostgreSQL 支持
LATERAL JOIN，Django 4.2+ 的Subquery在某些场景下会自动转成它，性能更好 - MySQL 8.0+ 要求子查询必须有明确别名（Django 会自动加，不用管），但
GROUP BY子句里不能引用 Subquery 别名 - SQLite 对 Subquery 支持最弱，复杂嵌套容易报
sqlite3.OperationalError: misuse of aggregate
真实项目里，最容易被忽略的是数据库版本卡点和子查询的“单值契约”——它看着像 Python 表达式，实则是数据库 SQL 的硬约束，写错一点就整个 annotate 失效，而且错误提示往往藏在底层，不容易定位。
