Skip to main content

查找API参考

本文档包含lookup的API参考,用于构建数据库查询的 WHERE 子句的Django API。要了解如何进行 use 查找,请参阅 进行查询;学习如何 create 新的查找,参见 自定义查找

查找API有两个组件:注册查找的 RegisterLookupMixin 类和 查询表达式API,一个类必须实现为可注册为查找的一组方法。

Django有两个基类,遵循查询表达式API和从中导出所有Django内置查找:

  • Lookup:查找字段(例如 field_name__exactexact

  • Transform:转换字段

查找表达式由三部分组成:

  • 字段部分(例如 Book.objects.filter(author__best_friends__first_name...);

  • 变换部分(可以省略)(例如 __lower__first3chars__reversed);

  • 查找(例如 __icontains),如果省略,则默认为 __exact

注册API

Django使用 RegisterLookupMixin 给一个类接口来注册自己的查找。两个突出的例子是 Field,所有模型字段的基类,以及 Aggregate,所有Django聚合的基类。

class lookups.RegisterLookupMixin

一个在类上实现lookup API的mixin。

classmethod register_lookup(lookup, lookup_name=None)

在类中注册一个新的查找。例如 DateField.register_lookup(YearExact) 将在 DateField 上注册 YearExact 查找。它覆盖已存在的具有相同名称的查找。 lookup_name 将用于此查找(如果提供),否则将使用 lookup.lookup_name

Changed in Django 1.9:

添加了 lookup_name 参数。

get_lookup(lookup_name)

返回在类中注册的名为 lookup_nameLookup。默认实现在所有父类上递归查找,并检查是否有任何注册的查找命名为 lookup_name,返回第一个匹配。

get_transform(transform_name)

返回名为 transform_nameTransform。默认实现在所有父类上递归查看,以检查是否有任何注册变换命名为 transform_name,返回第一个匹配。

对于要作为查找的类,它必须遵循 查询表达式APILookupTransform 自然遵循这个API。

查询表达式API

查询表达式API是一组常见的方法,类定义为在查询表达式中可用于将自身转换为SQL表达式。直接字段引用,聚合和 Transform 是遵循此API的示例。当实现以下方法时,类被称为遵循查询表达式API:

as_sql(self, compiler, connection)

负责生成表达式的查询字符串和参数。 compiler 是一个 SQLCompiler 对象,它有一个 compile() 方法,可用于编译其他表达式。 connection 是用于执行查询的连接。

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

如果 as_vendorname() 方法或子类可能需要提供数据以覆盖SQL字符串的生成,则可以在此方法上定义自定义关键字参数。有关使用示例,请参阅 Func.as_sql()

as_vendorname(self, compiler, connection)

as_sql() 方法。当表达式由 compiler.compile() 编译时,Django将首先尝试调用 as_vendorname(),其中 vendorname 是用于执行查询的后端的供应商名称。 vendorname 是Django内置后端的 postgresqloraclesqlitemysql 之一。

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 是实现字段转换的通用类。一个突出的例子是将 DateField 转换为 IntegerField__year

在查找表达式中使用 Transform 的符号是 <expression>__<transformation> (例如 date__year)。

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

Changed in Django 1.9:

Transform 现在是 Func 的子类。

bilateral

一个布尔值,表示此转换是否应应用于 lhsrhs。双向变换将以与查找表达式中出现的顺序相同的顺序应用于 rhs。默认情况下,它设置为 False。例如用法,参见 自定义查找

lhs

左手边 - 正在变换。它必须遵循 查询表达式API

lookup_name

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

output_field

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

Lookup 参考

class Lookup[源代码]

Lookup 是实现查找的通用类。查找是具有左侧的查询表达式,lhs;右手侧,rhs;以及用于产生 lhsrhs (例如 lhs in rhslhs > rhs)之间的布尔比较的 lookup_name

在表达式中使用查找的符号是 <lhs>__<lookup_name>=<rhs>

这个类不遵循 查询表达式API,因为它的结构有 =<rhs>:查找总是查找表达式的结尾。

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) 一样用于编译 lhsconnection 可以用于编译供应商特定的SQL。如果 lhs 不是 None,则将其用作处理的 lhs 而不是 self.lhs

process_rhs(compiler, connection)[源代码]

行为与 process_lhs() 相同,在右侧。