查找 API 参考

本文档提供了查找的 API 参考，它是 Django 的 API，用于构建数据库查询的 WHERE 子句。要学习如何 使用 查找，请看 执行查询；要学习如何 创建 新的查找，请看 如何编写自定义的查询器。

查找 API 有两个组成部分：一个是 RegisterLookupMixin 类，用于注册查找；另一个是 查询表达式 API，一个类要想注册为查找，必须实现一组方法。

Django 有两个遵循查询表达式 API 的基类，所有 Django 内置的查找都是从这里派生出来的。

  • Lookup：查找一个字段（例如 field_name__exact 的 exact）
  • Transform：转换一个字段

一个查找表达式由三部分组成：

  • 字段部分（如 Book.objects.filter(author__best_friends__first_name...）；
  • 转换部分（可省略）（如 __lower__first3chars__reversed）；
  • 查找（例如 __icontains），如果省略，默认为 __exact。

注册 API

Django 使用 RegisterLookupMixin 为一个类提供了在其自身或其实例上注册查找的接口。两个显著的例子是 Field，所有模型字段的基类，以及 Transform，所有 Django 转换的基类。

class lookups.RegisterLookupMixin

一个在类上实现查找 API 的混入。

  • classmethod register_lookup(lookup, lookup_name=None)

    在类或类实例中注册一个新的查找。例如：

    1. DateField.register_lookup(YearExact)
    2. User._meta.get_field("date_joined").register_lookup(MonthExact)

    将在 DateField 上注册 YearExact 查找，以及在 User.date_joined 上注册 MonthExact 查找（您可以使用 Field Access API 来检索单个字段实例）。它会覆盖同名的已经存在的查找。在字段实例上注册的查找优先于在类上注册的查找。如果提供了 lookup_name，将用于此查找，否则将使用 lookup.lookup_name。

  • get_lookup(lookup_name)

    返回在调用它的类或类实例中注册的名为 lookup_name 的 Lookup。默认实现递归地查找所有父类，并检查是否有任何一个父类注册了名为 lookup_name 的查找，返回第一个匹配项。实例上的查找将覆盖具有相同 lookup_name 的任何类上的查找。

  • get_lookups()

    返回一个字典，其中包含在类或类实例中注册的每个查找名称，以及与之对应的 Lookup 类。

  • get_transform(transform_name)

    返回在类或类实例中注册的名为 transform_name 的 Transform。默认实现递归地查找所有父类，检查是否有任何一个父类注册了名为 transform_name 的转换，返回第一个匹配项。

一个类要想成为查找，必须遵循 查询表达式 API。 Lookup 和 Transform 自然遵循这个API。

Changed in Django 4.2:

已经添加了在 Field 实例上注册查找的支持。

查询表达式 API

查询表达式 API 是一组通用的方法，这些方法被定义为可用于查询表达式，将自己翻译成 SQL 表达式。直接字段引用、聚合和 Transform 是遵循这个 API 的例子。当一个类实现了以下方法时，就可以说它遵循了查询表达式 API：

as_sql(compiler, connection)

生成表达式的 SQL 片段。返回一个元组 (sql, params)，其中 sql 是 SQL 字符串，params 是查询参数的列表或元组。compiler 是一个 SQLCompiler 对象，它有一个 compile() 方法，可以用来编译其他表达式。connection 是用于执行查询的连接。

调用 expression.as_sql() 通常是不正确的，应该使用 compiler.compile(expression)。compiler.compile() 方法将负责调用特定厂商的表达式方法。

如果 as_vendorname() 方法或子类很可能需要提供数据来覆盖 SQL 字符串的生成，可以在这个方法上定义自定义关键字参数。参见 Func.as_sql() 的用法示例。

as_vendorname(compiler, connection)

和 as_sql() 方法一样工作。当一个表达式被 compiler.compile() 编译后，Django 会先尝试调用 as_vendorname()，其中 vendorname 是执行查询的后端厂商名称。vendorname 是 Django 内置后端的 postgresql、oracle、sqlite、mysql 中的一个。

get_lookup(lookup_name)

必须返回名为 lookup_name 的查找。例如，返回 self.output_field.get_lookup(lookup_name)。

get_transform(transform_name)

必须返回名为 transform_name 的查找。例如，返回 self.output_field.get_transform(transform_name)。

output_field

定义 get_lookup() 方法返回的类的类型。它必须是一个 Field 实例。

Transform 参考

class Transform

Transform 是一个实现字段转换的通用类。一个突出的例子是 __year，它将 DateField 转变为 IntegerField。

在查询表达式中使用 Transform 的符号是 <expression>__<transformation> （例如 date__year）。

这个类遵循 查询表达式 API，这意味着你可以使用 <expression>__<transform1>__<transform2>。它是一个专门的 Func() 表达式，只接受一个参数。 它也可以用在过滤器的右侧，或者直接作为注解使用。

  • bilateral

    一个布尔值，表示这一转换是否应适用于 lhs 和 rhs。双边转换将按照查找表达式中出现的顺序应用于 rhs。默认情况下，它被设置为 False。关于用法示例，请参见 如何编写自定义的查询器。

  • lhs

    左侧——正在转换的内容。它必须遵循 查询表达式 API。

  • lookup_name

    查找的名称，用于在解析查询表达式时识别它。它不能包含字符串 "__"。

  • output_field

    定义这个转换输出的类。它必须是一个 Field 实例。默认情况下是与其 lhs.output_field 相同。

Lookup 参考

class Lookup

Lookup 是一个实现查找的通用类。一个查找是一个查询表达式，它的左侧是 lhs；右侧是 rhs；还有一个 lookup_name，用于在 lhs 和 rhs 之间进行布尔比较，例如 lhs in rhs 或 lhs > rhs。

在表达式中使用查找的主要符号是 <lhs>__<lookup_name>=<rhs>。查询也可以直接在 QuerySet 过滤器中使用：

  1. Book.objects.filter(LessThan(F("word_count"), 7500))

…或注解：

  1. Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500))

  • lhs

    左手边——被查询的内容。该对象通常遵循 查询表达式 API。它也可以是一个普通的值。

  • rhs

    右侧——lhs 与什么进行比较。它可以是一个普通的值，也可以是编译成 SQL 的东西，通常是一个 F() 对象或一个 QuerySet。

  • lookup_name

    这个查询的名称，用于在解析查询表达式时识别它。它不能包含字符串 "__"。

  • process_lhs(compiler, connection, lhs=None)

    返回由 compiler.compile(lhs) 返回的元组 (lhs_string, lhs_params)。这个方法可以被重写来调整 lhs 的处理方式。

    compiler 是一个 SQLCompiler 对象，可以像 compiler.compile(lhs) 一样用来编译 lhs。connection 可以用于编译厂商特定的 SQL。如果 lhs 不是 None，就用它作为处理后的 lhs 代替 self.lhs。

  • process_rhs(compiler, connection)

    右侧的行为与 process_lhs() 相同。