Tortoise ORM 查询 API 深度解析

Tortoise ORM 查询 API 深度解析

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm

概述

Tortoise ORM 是一个基于 Python 的异步 ORM 框架，提供了强大的查询 API 来操作数据库。本文将深入解析其 Query API 的核心功能和使用方法，帮助开发者高效地进行数据库操作。

基础查询方法

Tortoise ORM 提供了几种基础的查询启动方法：

1. filter() - 创建带有过滤条件的查询集
2. exclude() - 创建排除特定条件的查询集
3. all() - 创建无过滤条件的查询集
4. first() - 获取第一条记录
5. annotate() - 创建带有注解的查询集

这些方法返回的都是 QuerySet 对象，支持链式调用。

对象操作方法

创建对象

• create() - 直接创建对象
• get_or_create() - 查询或创建对象

实例方法

• save() - 保存实例（新增或更新）
• delete() - 删除实例
• fetch_related() - 获取关联对象，支持多级关联查询

QuerySet 详解

QuerySet 是 Tortoise ORM 查询的核心，它支持延迟执行，只有在调用 await 时才会真正执行查询。

基本查询示例

# 查询名称以"FIFA"开头的事件
await Event.filter(name__startswith='FIFA')

# 排除名称中包含"junior"的团队
await Team.exclude(name__icontains='junior')

关联查询

Tortoise ORM 支持强大的关联查询能力：

# 查询"World Cup"赛事的所有事件
await Event.filter(tournament__name='World Cup')

# 查询参与ID为1,2,3的事件的所有团队
await Team.filter(events__id__in=[1,2,3])

预取关联数据

使用 prefetch_related() 可以高效获取关联数据：

# 获取所有事件及其关联的赛事
await Event.all().prefetch_related('tournament')

# 获取所有赛事及其事件和参与者
tournament_list = await Tournament.all().prefetch_related('events__participants')

高级查询技巧

值查询

当性能是关键时，可以使用 values() 或 values_list() 减少查询次数：

# 单次查询获取事件ID、名称和关联赛事名称
events = await Event.filter(id__in=[1,2,3]).values('id', 'name', tournament_name='tournament__name')

聚合与函数

Tortoise ORM 支持丰富的聚合函数：

from tortoise.functions import Count, Trim, Lower, Upper, Coalesce

# 统计事件数量大于10的赛事
await Tournament.annotate(events_count=Count('events')).filter(events_count__gte=10)

# 使用字符串函数
await Tournament.annotate(clean_name=Trim('name')).filter(clean_name='tournament')

关联关系操作

外键关系

Tortoise ORM 提供了完整的外键操作 API，支持正向和反向查询。

多对多关系

多对多关系的操作非常直观：

# 添加参与者到事件
await event.participants.add(participant_1, participant_2)

过滤条件详解

Tortoise ORM 提供了丰富的过滤修饰符：

基本修饰符

• not - 非
• in - 包含在列表中
• gte/gt - 大于等于/大于
• lte/lt - 小于等于/小于
• range - 范围
• isnull - 为空

字符串修饰符

• contains/icontains - 包含（区分/不区分大小写）
• startswith/istartswith - 开头匹配
• endswith/iendswith - 结尾匹配
• iexact - 精确匹配（不区分大小写）
• search - 全文搜索

日期修饰符

支持 year, month, day 等时间维度过滤。

JSON 字段过滤

对于 JSONField，支持特殊过滤操作：

# 包含特定JSON结构
await JSONModel.filter(data__contains=[{"msg": "msg2"}]).first()

# 复杂JSON查询
await JSONModel.filter(data__filter={"owner__other_pets__0__name": "Fishy"}).first()

正则表达式查询

支持 POSIX 正则表达式：

# 正则匹配
await DemoModel.filter(demo_text__posix_regex="^Hello World$").first()

复杂预取查询

使用 Prefetch 对象可以实现复杂的预取逻辑：

# 只预取名称为"First"的事件
await Tournament.all().prefetch_related(
    Prefetch('events', queryset=Event.filter(name='First'))
).first()

总结

Tortoise ORM 的 Query API 提供了强大而灵活的数据库操作能力，从简单的查询到复杂的关联操作都能轻松应对。通过合理使用这些功能，可以构建出既高效又易于维护的数据访问层。

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm