Tortoise ORM 的 filter() 方法返回的 QuerySet 对象

Tortoise ORM 的 filter() 方法返回的是一个 QuerySet 对象，它是 Tortoise ORM 中用于构建数据库查询的核心组件之一。以下是对 QuerySet 的详细解读：

1. QuerySet 是什么？

• 定义：QuerySet 是 Tortoise ORM 中的一个类，用于表示数据库查询的条件集合。它类似于 Django ORM 中的 QuerySet，但专为异步操作设计。

• 作用：它提供了一种链式调用的方式来构建数据库查询条件，直到你显式地执行查询（如 .first()、.all()、.get() 等）时，才会实际向数据库发送 SQL 请求。

2. QuerySet 的特性

• 懒加载（Lazy Evaluation）：

  • QuerySet 是惰性的，不会立即执行数据库查询。只有在你调用异步方法（如 .first()、.all()、.get()）时，才会触发实际的数据库操作。

  • 示例：

    queryset = User.filter(username="test_user")  # 不会执行查询
    user = await queryset.first()  # 此时才会执行查询
    

• 链式调用：

  • 可以通过链式调用的方式逐步添加查询条件。

  • 示例：

    queryset = User.filter(username="test_user").filter(is_active=True)
    user = await queryset.first()
    

• 异步操作：

  • Tortoise ORM 是异步的，所有查询操作都需要通过 await 来执行。

  • 示例：

    user = await User.filter(username="test_user").first()
    

3. QuerySet 的方法

以下是一些常用的 QuerySet 方法：

1. first()

• 返回查询结果中的第一个对象。如果没有结果，返回 None。

• 示例：

  user = await User.filter(username="test_user").first()
  

2. all()

• 返回查询结果中的所有对象。

• 示例：

  users = await User.filter(is_active=True).all()
  

3. get()

• 返回匹配查询条件的唯一对象。如果没有找到或找到多个对象，会抛出异常。

• 示例：

  user = await User.filter(username="test_user").get()
  

4. count()

• 返回查询结果的数量。

• 示例：

  count = await User.filter(is_active=True).count()
  

5. order_by()

• 对查询结果进行排序。

• 示例：

  users = await User.filter(is_active=True).order_by("created_at").all()
  

6. limit() 和 offset()

• 用于分页查询。

• 示例：

  users = await User.filter(is_active=True).limit(10).offset(20).all()
  

4. QuerySet 的操作流程

1. 构建查询条件：

   queryset = User.filter(username="test_user")
   

2. 执行查询：

   user = await queryset.first()
   

5. QuerySet 与数据库操作

• 构建查询条件：

  • filter() 方法会将条件添加到 QuerySet 对象中，但不会立即执行查询。

  • 示例：

    queryset = User.filter(username="test_user").filter(email="test@example.com")
    

• 执行查询：

  • 当调用异步方法（如 .first()、.all()）时，Tortoise ORM 会根据 QuerySet 中的条件生成 SQL 语句并执行查询。

  • 示例：

    user = await queryset.first()  # 生成 SQL 并执行查询
    

6. QuerySet 的优点

• 灵活性：支持链式调用和逐步构建查询条件。

• 性能优化：延迟执行查询，可以在构建查询条件时进行逻辑判断，避免不必要的数据库操作。

• 异步支持：完美适配 FastAPI 的异步架构，提升系统性能。

7. 示例代码

以下是一个完整的示例，展示 QuerySet 的使用：

from tortoise.models import Model
from tortoise import fields

class User(Model):
    id = fields.IntField(pk=True)
    username = fields.CharField(max_length=50)
    email = fields.CharField(max_length=50)
    is_active = fields.BooleanField(default=True)
    created_at = fields.DatetimeField(auto_now_add=True)

# 构建查询条件
queryset = User.filter(username="test_user").filter(is_active=True).order_by("created_at")

# 执行查询
user = await queryset.first()
users = await queryset.all()
count = await queryset.count()

总结

• QuerySet 是什么：它是 Tortoise ORM 中用于构建数据库查询条件的对象，支持链式调用和异步操作。

• 何时执行查询：只有在调用异步方法（如 .first()、.all()）时，才会实际执行数据库查询。

• 优点：灵活性高、支持异步操作、延迟执行查询，适合构建复杂的查询逻辑。

在 Tortoise ORM 中，QuerySet 是理解和使用 ORM 的关键，它提供了一种简洁而强大的方式来操作数据库。