查找API参考

本文档具有查找的API参考,用于构建数据库查询的WHERE子句的Django API。 To learn how to use lookups, see Making queries; to learn how to create new lookups, see Custom Lookups.

The lookup API has two components: a RegisterLookupMixin class that registers lookups, and the Query Expression API, a set of methods that a class has to implement to be registrable as a lookup.

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聚合的基类。

查找。 RegisterLookupMixin T0> ¶ T1>

在类中实现查找API的mixin。

类方法 register_lookuplookuplookup_name = None

在课程中注册一个新的查询。 For example DateField.register_lookup(YearExact) will register YearExact lookup on DateField. 它覆盖了已经存在的具有相同名称的查找。 lookup_name will be used for this lookup if provided, otherwise lookup.lookup_name will be used.

get_lookup T0>( lookup_name T1>)¶ T2>

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

get_transform T0>( transform_name T1>)¶ T2>

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

对于类来查找,它必须遵循Query Expression API Lookup and Transform naturally follow this API.

查询表达式API

查询表达式API是一组常用的方法,这些方法定义为可在查询表达式中使用,以将自己转换为SQL表达式。 直接字段引用,聚合和Transform是遵循此API的示例。 一个类在执行以下方法时被认为遵循查询表达式API:

as_sql编译器连接

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

调用expression.as_sql()通常是不正确的,应该使用compiler.compile(expression) The compiler.compile() method will take care of calling vendor-specific methods of the expression.

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

as_vendorname编译器连接

as_sql()方法一样工作。 When an expression is compiled by compiler.compile(), Django will first try to call as_vendorname(), where vendorname is the vendor name of the backend used for executing the query. vendorname是Django的postgresqloraclesqlitemysql内置后端。

get_lookup T0>( lookup_name T1>)¶ T2>

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

get_transform T0>( transform_name T1>)¶ T2>

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

output_field T0> ¶ T1>

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

Transform引用

Transform[source]

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

The notation to use a Transform in an lookup expression is <expression>__<transformation> (e.g. date__year).

This class follows the Query Expression API, which implies that you can use <expression>__<transform1>__<transform2>. 这是一个专门的Func() expression,它只接受一个参数。 它也可以在过滤器的右侧使用或直接作为注释使用。

双边 T0> ¶ T1>

一个布尔值,指示这个转换是否应用于lhsrhs Bilateral transformations will be applied to rhs in the same order as they appear in the lookup expression. 默认情况下,它被设置为False 例如用法,请参阅Custom Lookups

LHS T0> ¶ T1>

左侧 - 正在改变。 它必须遵循Query Expression API

lookup_name T0> ¶ T1>

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

output_field T0> ¶ T1>

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

Lookup参考

Lookup[source]

A 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 T0> ¶ T1>

左侧 - 正在抬头。 该对象必须遵循Query Expression API

RHS T0> ¶ T1>

右边 - 正在比较什么lhs 它可以是一个普通的值,也可以是编译成SQL的东西,通常是一个F()对象或一个QuerySet

lookup_name T0> ¶ T1>

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

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

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

compiler is an SQLCompiler object, to be used like compiler.compile(lhs) for compiling lhs. connection可用于编译供应商特定的SQL。 如果lhs不是None,则将其用作已处理的lhs而不是self.lhs

process_rhs tt>(编译器连接[source]

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