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 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.
- Transforms part (may be omitted) (e.g.
- A lookup (e.g.
__icontains) that, if omitted, defaults to
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
Aggregate, the base class of all Django aggregates.
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. It overrides a lookup that already exists with the same name.
lookup_namewill be used for this lookup if provided, otherwise
lookup.lookup_namewill be used.
lookup_nameparameter was added.
lookup_nameregistered in the class. The default implementation looks recursively on all parent classes and checks if any has a registered lookup named
lookup_name, returning the first match.
transform_name. The default implementation looks recursively on all parent classes to check if any has the registered transform named
transform_name, returning the first match.
For a class to be a lookup, it must follow the Query Expression API.
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(self, compiler, connection)
Responsible for producing the query string and parameters for the expression. The
SQLCompilerobject, which has a
compile()method that can be used to compile other expressions. The
connectionis the connection used to execute the query.
expression.as_sql()is usually incorrect - instead
compiler.compile(expression)should be used. The
compiler.compile()method will take care of calling vendor-specific methods of the expression.
as_vendorname(self, compiler, connection)
as_sql()method. When an expression is compiled by
compiler.compile(), Django will first try to call
vendornameis the vendor name of the backend used for executing the query. The
vendornameis one of
mysqlfor Django’s built-in backends.
Must return the lookup named
lookup_name. For instance, by returning
Must return the lookup named
transform_name. For instance, by returning
Defines the type of class returned by the
get_lookup()method. It must be a
Transformis a generic class to implement field transformations. A prominent example is
__yearthat transforms a
The notation to use a
Transformin an lookup expression is
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.
Transformis now a subclass of
A boolean indicating whether this transformation should apply to both
rhs. Bilateral transformations will be applied to
rhsin the same order as they appear in the lookup expression. By default it is set to
False. For example usage, see Custom Lookups.
The left-hand side - what is being transformed. It must follow the Query Expression API.
The name of the lookup, used for identifying it on parsing query expressions. It cannot contain the string
Defines the class this transformation outputs. It must be a
Fieldinstance. By default is the same as its
Lookupis a generic class to implement lookups. A lookup is a query expression with a left-hand side,
lhs; a right-hand side,
rhs; and a
lookup_namethat is used to produce a boolean comparison between
lhs in rhsor
lhs > rhs.
The notation to use a lookup in an expression is
This class doesn’t follow the Query Expression API since it has
=<rhs>on its construction: lookups are always the end of a lookup expression.
The left-hand side - what is being looked up. The object must follow the Query Expression API.
The right-hand side - what
lhsis being compared against. It can be a plain value, or something that compiles into SQL, typically an
F()object or a
The name of this lookup, used to identify it on parsing query expressions. It cannot contain the string
process_lhs(compiler, connection, lhs=None)[source]
Returns a tuple
(lhs_string, lhs_params), as returned by
compiler.compile(lhs). This method can be overridden to tune how the
SQLCompilerobject, to be used like
connectioncan be used for compiling vendor specific SQL. If
None, use it as the processed
Behaves the same way as
process_lhs(), for the right-hand side.
© Django Software Foundation and individual contributors
Licensed under the BSD License.