Tortoise ORM 的 only() 方法默认不支持直接通过 "related__field" 语法筛选外键关联模型的字段；正确方式是结合 Prefetch 对象显式定义关联模型的查询集，并在其内部调用 only()。
tortoise orm 的 `only()` 方法默认不支持直接通过 `"related__field"` 语法筛选外键关联模型的字段；正确方式是结合 `prefetch` 对象显式定义关联模型的查询集，并在其内部调用 `only()`。
在使用 Tortoise ORM 进行关系查询时，开发者常希望优化数据加载，避免冗余字段传输。例如，查询 Token 模型时仅需获取其关联 Provider 的 id 和 description 字段，而非整个 Provider 实例。但若直接在主查询中使用 .only("id", "provider__description", "expires") 并配合 .select_related("provider")，会触发 KeyError: 'provider__description' —— 因为 only() 不支持跨表字段路径语法（如 provider__description），该语法仅适用于 Django ORM，Tortoise 并未实现此行为。
✅ 正确解法是使用 tortoise.query_utils.Prefetch 显式控制关联模型的查询范围：
from tortoise.query_utils import Prefetch
from models import Provider, Token
async def get_tokens(user_id: Optional[int] = None) -> List[Token]:
query = Token.all().prefetch_related(
Prefetch(
"provider",
queryset=Provider.all().only("id", "description")
)
)
if user_id:
query = query.filter(user_id=user_id)
return await query
⚠️ 注意事项：
-
Prefetch必须与prefetch_related()配合使用，不能与select_related()混用（后者执行 JOIN，不支持字段级粒度控制）； -
Prefetch.queryset中的only()作用于关联模型本身，确保数据库仅返回指定字段； - 若未导入
Prefetch，需显式添加：from tortoise.query_utils import Prefetch； -
only()在Prefetch内部生效，主查询的only()仍仅作用于Token本体字段（如"id","expires"）。
? 补充技巧：若还需关联 User 模型且只取部分字段，可链式添加多个 Prefetch：
.prefetch_related(
Prefetch("provider", queryset=Provider.all().only("id", "description")),
Prefetch("user", queryset=User.all().only("id", "username")),
)
综上，Tortoise ORM 的字段级懒加载依赖 Prefetch 机制，这是实现高效、精准关联查询的关键模式。
