This document has the API references of lookups, the Django API for building\nthe WHERE clause of a database query. To learn how to use lookups, see\nMaking queries; to learn how to create new lookups, see\nΠαραμετροποιήσιμα Lookups.
The lookup API has two components: a RegisterLookupMixin class\nthat registers lookups, and the Query Expression API, a\nset 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\nall Django builtin lookups are derived:
\nLookup: to lookup a field (e.g. the exact of field_name__exact)
Transform: to transform a field
A lookup expression consists of three parts:
\nFields 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.
Django uses RegisterLookupMixin to give a class the interface to\nregister lookups on itself. The two prominent examples are\nField, the base class of all model fields, and\nTransform, the base class of all Django transforms.
A mixin that implements the lookup API on a class.
\nRegisters a new lookup in the class. For example\nDateField.register_lookup(YearExact) will register YearExact\nlookup on DateField. It overrides a lookup that already exists with\nthe same name. lookup_name will be used for this lookup if\nprovided, otherwise lookup.lookup_name will be used.
Returns the Lookup named lookup_name registered in the class.\nThe default implementation looks recursively on all parent classes\nand checks if any has a registered lookup named lookup_name, returning\nthe first match.
Returns a dictionary of each lookup name registered in the class mapped\nto the Lookup class.
Returns a Transform named transform_name. The default\nimplementation looks recursively on all parent classes to check if any\nhas the registered transform named transform_name, returning the first\nmatch.
For a class to be a lookup, it must follow the Query Expression API. Lookup and Transform naturally\nfollow this API.
The query expression API is a common set of methods that classes define to be\nusable in query expressions to translate themselves into SQL expressions. Direct\nfield references, aggregates, and Transform are examples that follow this\nAPI. A class is said to follow the query expression API when it implements the\nfollowing methods:
Generates the SQL fragment for the expression. Returns a tuple\n(sql, params), where sql is the SQL string, and params is the\nlist or tuple of query parameters. The compiler is an SQLCompiler\nobject, which has a compile() method that can be used to compile other\nexpressions. The connection is the connection used to execute the\nquery.
Calling expression.as_sql() is usually incorrect - instead\ncompiler.compile(expression) should be used. The compiler.compile()\nmethod 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\nas_vendorname() methods or subclasses will need to supply data to\noverride the generation of the SQL string. See Func.as_sql() for\nexample usage.
Works like as_sql() method. When an expression is compiled by\ncompiler.compile(), Django will first try to call as_vendorname(),\nwhere vendorname is the vendor name of the backend used for executing\nthe query. The vendorname is one of postgresql, oracle,\nsqlite, or mysql for Django’s built-in backends.
Must return the lookup named lookup_name. For instance, by returning\nself.output_field.get_lookup(lookup_name).
Must return the lookup named transform_name. For instance, by returning\nself.output_field.get_transform(transform_name).
Defines the type of class returned by the get_lookup() method. It must\nbe a Field instance.
Transform referenceLink to this heading#A Transform is a generic class to implement field transformations. A\nprominent example is __year that transforms a DateField into a\nIntegerField.
The notation to use a Transform in a lookup expression is\n<expression>__<transformation> (e.g. date__year).
This class follows the Query Expression API, which\nimplies that you can use <expression>__<transform1>__<transform2>. It’s\na specialized Func() expression that only accepts\none argument. It can also be used on the right hand side of a filter or\ndirectly as an annotation.
A boolean indicating whether this transformation should apply to both\nlhs and rhs. Bilateral transformations will be applied to rhs in\nthe same order as they appear in the lookup expression. By default it is set\nto False. For example usage, see Παραμετροποιήσιμα Lookups.
The left-hand side - what is being transformed. It must follow the\nQuery Expression API.
\nThe name of the lookup, used for identifying it on parsing query\nexpressions. It cannot contain the string "__".
Defines the class this transformation outputs. It must be a\nField instance. By default is the same as\nits lhs.output_field.
Lookup referenceLink to this heading#A Lookup is a generic class to implement lookups. A lookup is a query\nexpression with a left-hand side, lhs; a right-hand side,\nrhs; and a lookup_name that is used to produce a boolean\ncomparison between lhs and rhs such as lhs in rhs or\nlhs > rhs.
The notation to use a lookup in an expression is\n<lhs>__<lookup_name>=<rhs>.
This class acts as a query expression, but, since it has =<rhs> on its\nconstruction, lookups must always be the end of a lookup expression.
The left-hand side - what is being looked up. The object must follow\nthe Query Expression API.
\nThe right-hand side - what lhs is being compared against. It can be\na plain value, or something that compiles into SQL, typically an\nF() object or a QuerySet.
The name of this lookup, used to identify it on parsing query\nexpressions. It cannot contain the string "__".
Returns a tuple (lhs_string, lhs_params), as returned by\ncompiler.compile(lhs). This method can be overridden to tune how\nthe lhs is processed.
compiler is an SQLCompiler object, to be used like\ncompiler.compile(lhs) for compiling lhs. The connection\ncan be used for compiling vendor specific SQL. If lhs is not\nNone, use it as the processed lhs instead of self.lhs.
Behaves the same way as process_lhs(), for the right-hand side.