查找API参考

这篇文档是"查找"的 API 参考，Django 用这些API 构建数据库查询的WHERE 子句。 要了解如何使用查找，请参阅执行查询；了解如何创建新查找，请参阅自定义查找。

查找 API 由两个部分组成：RegisterLookupMixin 类，它用于注册查找；Query Expression API，它是一个方法集，类必须实现它们才可以注册成一个查找。

Django 有两个类遵循查询表达式API，且Django 所有内建的查找都继承自它们：

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

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

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

注册API

Django 使用RegisterLookupMixin 来为类提供接口，注册它自己的查找。 两个最突出的例子是Field（所有模型字段的基类）和 Aggregate（Django 所有聚合函数的基类）。

class lookups.RegisterLookupMixin

一个mixin，实现一个类上的查找API。

classmethod register_lookup(lookup, lookup_name=None)

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

get_lookup(lookup_name)

返回类中注册的名为lookup_name 的 Lookup。 默认的实现会递归查询所有的父类，并检查它们中的任何一个是否具有名称为lookup_name的查找，并返回第一个匹配。

get_transform(transform_name)

返回一个名为transform_name 的Transform。 默认的实现会递归查找所有的父类，并检查它们中的任何一个是否具有名称为transform_name的查找，并返回第一个匹配。

一个类如果想要成为查找，它必须实现Query Expression API。 Lookup 和Transform一开始就遵循这个API。

查询表达式API

查询表达式API是一个通用的方法集，定义了这些方法的类可以使用该方法集来将它们自身转换为SQL表达式。 直接的字段引用，聚合，以及Transform类都是遵循这个API的示例。 当一个对象实现以下方法时，就被称为遵循查询表达式API：

as_sql(compiler, connection)

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

调用expression.as_sql()一般是不对的 -- 而是应该调用compiler.compile(expression)。 compiler.compile()方法应该在调用表达式的供应商特定方法时格外小心。

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

as_vendorname(compiler, connection)

和as_sql()的工作方式类似。 当一个表达式经过vendorname编译之后， Django会首先尝试调用as_vendorname()，其中compiler.compile()是用于执行查询的后端供应商。 vendorname是postgresql，oracle，sqlite，或者mysql是Django内建的后端，之一。

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[source]

Transform是用于实现字段转换的通用类。 一个显然的例子是IntegerField会把DateField转换为__year。

在表达式中执行查找的标记是date__year<expression>__<transformation> (例如 Transform)。

这个类遵循Query Expression API，也就是说你可以使用 <expression>__<transform1>__<transform2>。 这是一个专门的Func() expression，它只接受一个参数。 它也可以在滤波器的右侧使用，也可以直接用作注释。

bilateral

一个布尔值，表明是否对lhs和 rhs都应用这个转换。 如果对两侧都应用转换，应用在rhs的顺序和在查找表达式中的出现顺序相同。 默认这个属性为False。 使用方法的实例请见Custom Lookups。

lhs

在左边，也就是被转换的东西。 必须遵循Query Expression API。

lookup_name

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

output_field

为这个类定义转换后的输出。 必须为Field的实例。 默认情况下和lhs.output_field相同。

Lookup参考

class Lookup[source]

Lookup是实现查找的通用的类。 A lookup is a query expression with a left-hand side, lhs; a right-hand side, rhs; and a lookup_name that is used to produce a boolean comparison between lhs and rhs such as lhs in rhs or lhs > rhs.

在表达式中执行查找的标记是<lhs>__<lookup_name>=<rhs>。

这个类并不遵循Query Expression API，因为在它构造的时候出现了=<rhs>：查找总是在查找表达式的最后。

lhs

在左边，也就是被查找的东西。 这个对象必须遵循Query Expression API。

rhs

在右边，也就是用来和lhs比较的东西。 它可以是个简单的值，也可以是在SQL中编译的一些东西，比如 F() 对象或者QuerySet。

lookup_name

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

process_lhs(compiler, connection, lhs=None)[source]

返回元组(lhs_string, lhs_params)，和compiler.compile(lhs)所返回的一样。 这个方法可以被覆写，来调整lhs的处理方式。

compiler.compile(lhs)是一个SQLCompiler对象，可以像 compiler这样使用来编译lhs。 connection可以用于编译供应商特定的SQL语句。 lhs如果不为None, 会代替lhs作为处理后的self.lhs使用。

process_rhs(compiler, connection)[source]

对于右边的东西，和process_lhs()的行为相同。