Lookup API参考

这篇文档是"查找"的 API 参考,Django 用这些API 构建数据库查询的WHERE 子句。 要了解如何使用查找,请参阅Making queries;了解如何创建新查找,请参阅Custom Lookups

查找 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_nameLookup 默认的实现会递归查询所有的父类,并检查它们中的任何一个是否具有名称为lookup_name的查找,并返回第一个匹配。

get_transform(transform_name)

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

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

查询表达式API

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

as_sql(compiler, connection)

负责从表达式中产生查询字符串和参数。 compile()是一个SQLCompiler对象,它拥有可以编译其它表达式的compiler方法。 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()是用于执行查询的后端供应商。 对于Django内建的后端,oraclepostgresqlvendornamesqlite,或者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[source]

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

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

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

bilateral

一个布尔值,表明是否对lhsrhs都应用这个转换。 如果对两侧都应用转换,应用在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()的行为相同。