Lookup API reference¶
This document has the API references of lookups, the Django API for building
the WHERE
clause of a database query. To learn how to use lookups, see
Making queries; to learn how to create new lookups, see
How to write 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 has two base classes that follow the query expression API and from where all Django builtin lookups are derived:
A lookup expression consists of three parts:
- Fields part (e.g.
Book.objects.filter(author__best_friends__first_name...
); - Transforms part (may be omitted) (e.g.
__lower__first3chars__reversed
); - A lookup (e.g.
__icontains
) that, if omitted, defaults to__exact
.
Registration API¶
Django uses RegisterLookupMixin
to give a class the interface to
register lookups on itself. The two prominent examples are
Field
, the base class of all model fields, and
Transform
, the base class of all Django transforms.
-
class
lookups.
RegisterLookupMixin
¶ A mixin that implements the lookup API on a class.
-
classmethod
register_lookup
(lookup, lookup_name=None)¶ Registers a new lookup in the class. For example
DateField.register_lookup(YearExact)
will registerYearExact
lookup onDateField
. It overrides a lookup that already exists with the same name.lookup_name
will be used for this lookup if provided, otherwiselookup.lookup_name
will be used.
-
get_lookup
(lookup_name)¶ Returns the
Lookup
namedlookup_name
registered in the class. The default implementation looks recursively on all parent classes and checks if any has a registered lookup namedlookup_name
, returning the first match.
-
classmethod
For a class to be a lookup, it must follow the Query Expression API. Lookup
and Transform
naturally
follow this API.
The Query Expression API¶
The query expression API is a common set of methods that classes define to be
usable in query expressions to translate themselves into SQL expressions. Direct
field references, aggregates, and Transform
are examples that follow this
API. A class is said to follow the query expression API when it implements the
following methods:
-
as_sql
(compiler, connection)¶ Generates the SQL fragment for the expression. Returns a tuple
(sql, params)
, wheresql
is the SQL string, andparams
is the list or tuple of query parameters. Thecompiler
is anSQLCompiler
object, which has acompile()
method that can be used to compile other expressions. Theconnection
is the connection used to execute the query.Calling
expression.as_sql()
is usually incorrect - insteadcompiler.compile(expression)
should be used. Thecompiler.compile()
method will take care of calling vendor-specific methods of the expression.Custom keyword arguments may be defined on this method if it’s likely that
as_vendorname()
methods or subclasses will need to supply data to override the generation of the SQL string. SeeFunc.as_sql()
for example usage.
-
as_vendorname
(compiler, connection)¶ Works like
as_sql()
method. When an expression is compiled bycompiler.compile()
, Django will first try to callas_vendorname()
, wherevendorname
is the vendor name of the backend used for executing the query. Thevendorname
is one ofpostgresql
,oracle
,sqlite
, ormysql
for Django’s built-in backends.
-
get_lookup
(lookup_name)¶ Must return the lookup named
lookup_name
. For instance, by returningself.output_field.get_lookup(lookup_name)
.
-
get_transform
(transform_name)¶ Must return the lookup named
transform_name
. For instance, by returningself.output_field.get_transform(transform_name)
.
Transform
reference¶
-
class
Transform
¶ A
Transform
is a generic class to implement field transformations. A prominent example is__year
that transforms aDateField
into aIntegerField
.The notation to use a
Transform
in a 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>
. It’s a specialized Func() expression that only accepts one argument. It can also be used on the right hand side of a filter or directly as an annotation.-
bilateral
¶ A boolean indicating whether this transformation should apply to both
lhs
andrhs
. Bilateral transformations will be applied torhs
in the same order as they appear in the lookup expression. By default it is set toFalse
. For example usage, see How to write custom lookups.
-
lhs
¶ The left-hand side - what is being transformed. It must follow the Query Expression API.
-
lookup_name
¶ The name of the lookup, used for identifying it on parsing query expressions. It cannot contain the string
"__"
.
-
Lookup
reference¶
-
class
Lookup
¶ A
Lookup
is a generic class to implement lookups. A lookup is a query expression with a left-hand side,lhs
; a right-hand side,rhs
; and alookup_name
that is used to produce a boolean comparison betweenlhs
andrhs
such aslhs in rhs
orlhs > rhs
.The primary notation to use a lookup in an expression is
<lhs>__<lookup_name>=<rhs>
. Lookups can also be used directly inQuerySet
filters:Book.objects.filter(LessThan(F('word_count'), 7500))
…or annotations:
Book.objects.annotate(is_short_story=LessThan(F('word_count'), 7500))
-
lhs
¶ The left-hand side - what is being looked up. The object typically follows the Query Expression API. It may also be a plain value.
-
rhs
¶ The right-hand side - what
lhs
is being compared against. It can be a plain value, or something that compiles into SQL, typically anF()
object or aQuerySet
.
-
lookup_name
¶ The name of this lookup, used to identify it on parsing query expressions. It cannot contain the string
"__"
.
-
process_lhs
(compiler, connection, lhs=None)¶ Returns a tuple
(lhs_string, lhs_params)
, as returned bycompiler.compile(lhs)
. This method can be overridden to tune how thelhs
is processed.compiler
is anSQLCompiler
object, to be used likecompiler.compile(lhs)
for compilinglhs
. Theconnection
can be used for compiling vendor specific SQL. Iflhs
is notNone
, use it as the processedlhs
instead ofself.lhs
.
-
process_rhs
(compiler, connection)¶ Behaves the same way as
process_lhs()
, for the right-hand side.
Changed in Django 4.0:Support for using lookups in
QuerySet
annotations, aggregations, and directly in filters was added.-