| 1 |
==================== |
| 2 |
Lookup API reference |
| 3 |
==================== |
| 4 |
|
| 5 |
.. module:: django.db.models.lookups |
| 6 |
:synopsis: Lookups API |
| 7 |
|
| 8 |
.. currentmodule:: django.db.models |
| 9 |
|
| 10 |
This document has the API references of lookups, the Django API for building |
| 11 |
the ``WHERE`` clause of a database query. To learn how to *use* lookups, see |
| 12 |
:doc:`/topics/db/queries`; to learn how to *create* new lookups, see |
| 13 |
:doc:`/howto/custom-lookups`. |
| 14 |
|
| 15 |
The lookup API has two components: a :class:`~lookups.RegisterLookupMixin` class |
| 16 |
that registers lookups, and the :ref:`Query Expression API <query-expression>`, a |
| 17 |
set of methods that a class has to implement to be registrable as a lookup. |
| 18 |
|
| 19 |
Django has two base classes that follow the query expression API and from where |
| 20 |
all Django builtin lookups are derived: |
| 21 |
|
| 22 |
* :class:`Lookup`: to lookup a field (e.g. the ``exact`` of ``field_name__exact``) |
| 23 |
* :class:`Transform`: to transform a field |
| 24 |
|
| 25 |
A lookup expression consists of three parts: |
| 26 |
|
| 27 |
* Fields part (e.g. ``Book.objects.filter(author__best_friends__first_name...``); |
| 28 |
* Transforms part (may be omitted) (e.g. ``__lower__first3chars__reversed``); |
| 29 |
* A lookup (e.g. ``__icontains``) that, if omitted, defaults to ``__exact``. |
| 30 |
|
| 31 |
.. _lookup-registration-api: |
| 32 |
|
| 33 |
Registration API |
| 34 |
================ |
| 35 |
|
| 36 |
Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to |
| 37 |
register lookups on itself or its instances. The two prominent examples are |
| 38 |
:class:`~django.db.models.Field`, the base class of all model fields, and |
| 39 |
:class:`Transform`, the base class of all Django transforms. |
| 40 |
|
| 41 |
.. class:: lookups.RegisterLookupMixin |
| 42 |
|
| 43 |
A mixin that implements the lookup API on a class. |
| 44 |
|
| 45 |
.. classmethod:: register_lookup(lookup, lookup_name=None) |
| 46 |
|
| 47 |
Registers a new lookup in the class or class instance. For example:: |
| 48 |
|
| 49 |
DateField.register_lookup(YearExact) |
| 50 |
User._meta.get_field("date_joined").register_lookup(MonthExact) |
| 51 |
|
| 52 |
will register ``YearExact`` lookup on ``DateField`` and ``MonthExact`` |
| 53 |
lookup on the ``User.date_joined`` (you can use :ref:`Field Access API |
| 54 |
<model-meta-field-api>` to retrieve a single field instance). It |
| 55 |
overrides a lookup that already exists with the same name. Lookups |
| 56 |
registered on field instances take precedence over the lookups |
| 57 |
registered on classes. ``lookup_name`` will be used for this lookup if |
| 58 |
provided, otherwise ``lookup.lookup_name`` will be used. |
| 59 |
|
| 60 |
.. method:: get_lookup(lookup_name) |
| 61 |
|
| 62 |
Returns the :class:`Lookup` named ``lookup_name`` registered in the |
| 63 |
class or class instance depending on what calls it. The default |
| 64 |
implementation looks recursively on all parent classes and checks if |
| 65 |
any has a registered lookup named ``lookup_name``, returning the first |
| 66 |
match. Instance lookups would override any class lookups with the same |
| 67 |
``lookup_name``. |
| 68 |
|
| 69 |
.. method:: get_lookups() |
| 70 |
|
| 71 |
Returns a dictionary of each lookup name registered in the class or |
| 72 |
class instance mapped to the :class:`Lookup` class. |
| 73 |
|
| 74 |
.. method:: get_transform(transform_name) |
| 75 |
|
| 76 |
Returns a :class:`Transform` named ``transform_name`` registered in the |
| 77 |
class or class instance. The default implementation looks recursively |
| 78 |
on all parent classes to check if any has the registered transform |
| 79 |
named ``transform_name``, returning the first match. |
| 80 |
|
| 81 |
For a class to be a lookup, it must follow the :ref:`Query Expression API |
| 82 |
<query-expression>`. :class:`~Lookup` and :class:`~Transform` naturally |
| 83 |
follow this API. |
| 84 |
|
| 85 |
.. _query-expression: |
| 86 |
|
| 87 |
The Query Expression API |
| 88 |
======================== |
| 89 |
|
| 90 |
The query expression API is a common set of methods that classes define to be |
| 91 |
usable in query expressions to translate themselves into SQL expressions. Direct |
| 92 |
field references, aggregates, and ``Transform`` are examples that follow this |
| 93 |
API. A class is said to follow the query expression API when it implements the |
| 94 |
following methods: |
| 95 |
|
| 96 |
.. method:: as_sql(compiler, connection) |
| 97 |
|
| 98 |
Generates the SQL fragment for the expression. Returns a tuple |
| 99 |
``(sql, params)``, where ``sql`` is the SQL string, and ``params`` is the |
| 100 |
list or tuple of query parameters. The ``compiler`` is an ``SQLCompiler`` |
| 101 |
object, which has a ``compile()`` method that can be used to compile other |
| 102 |
expressions. The ``connection`` is the connection used to execute the |
| 103 |
query. |
| 104 |
|
| 105 |
Calling ``expression.as_sql()`` is usually incorrect - instead |
| 106 |
``compiler.compile(expression)`` should be used. The ``compiler.compile()`` |
| 107 |
method will take care of calling vendor-specific methods of the expression. |
| 108 |
|
| 109 |
Custom keyword arguments may be defined on this method if it's likely that |
| 110 |
``as_vendorname()`` methods or subclasses will need to supply data to |
| 111 |
override the generation of the SQL string. See :meth:`Func.as_sql` for |
| 112 |
example usage. |
| 113 |
|
| 114 |
.. method:: as_vendorname(compiler, connection) |
| 115 |
|
| 116 |
Works like ``as_sql()`` method. When an expression is compiled by |
| 117 |
``compiler.compile()``, Django will first try to call ``as_vendorname()``, |
| 118 |
where ``vendorname`` is the vendor name of the backend used for executing |
| 119 |
the query. The ``vendorname`` is one of ``postgresql``, ``oracle``, |
| 120 |
``sqlite``, or ``mysql`` for Django's built-in backends. |
| 121 |
|
| 122 |
.. method:: get_lookup(lookup_name) |
| 123 |
|
| 124 |
Must return the lookup named ``lookup_name``. For instance, by returning |
| 125 |
``self.output_field.get_lookup(lookup_name)``. |
| 126 |
|
| 127 |
.. method:: get_transform(transform_name) |
| 128 |
|
| 129 |
Must return the lookup named ``transform_name``. For instance, by returning |
| 130 |
``self.output_field.get_transform(transform_name)``. |
| 131 |
|
| 132 |
.. attribute:: output_field |
| 133 |
|
| 134 |
Defines the type of class returned by the ``get_lookup()`` method. It must |
| 135 |
be a :class:`~django.db.models.Field` instance. |
| 136 |
|
| 137 |
``Transform`` reference |
| 138 |
======================= |
| 139 |
|
| 140 |
.. class:: Transform |
| 141 |
|
| 142 |
A ``Transform`` is a generic class to implement field transformations. A |
| 143 |
prominent example is ``__year`` that transforms a ``DateField`` into a |
| 144 |
``IntegerField``. |
| 145 |
|
| 146 |
The notation to use a ``Transform`` in a lookup expression is |
| 147 |
``<expression>__<transformation>`` (e.g. ``date__year``). |
| 148 |
|
| 149 |
This class follows the :ref:`Query Expression API <query-expression>`, which |
| 150 |
implies that you can use ``<expression>__<transform1>__<transform2>``. It's |
| 151 |
a specialized :ref:`Func() expression <func-expressions>` that only accepts |
| 152 |
one argument. It can also be used on the right hand side of a filter or |
| 153 |
directly as an annotation. |
| 154 |
|
| 155 |
.. attribute:: bilateral |
| 156 |
|
| 157 |
A boolean indicating whether this transformation should apply to both |
| 158 |
``lhs`` and ``rhs``. Bilateral transformations will be applied to ``rhs`` in |
| 159 |
the same order as they appear in the lookup expression. By default it is set |
| 160 |
to ``False``. For example usage, see :doc:`/howto/custom-lookups`. |
| 161 |
|
| 162 |
.. attribute:: lhs |
| 163 |
|
| 164 |
The left-hand side - what is being transformed. It must follow the |
| 165 |
:ref:`Query Expression API <query-expression>`. |
| 166 |
|
| 167 |
.. attribute:: lookup_name |
| 168 |
|
| 169 |
The name of the lookup, used for identifying it on parsing query |
| 170 |
expressions. It cannot contain the string ``"__"``. |
| 171 |
|
| 172 |
.. attribute:: output_field |
| 173 |
|
| 174 |
Defines the class this transformation outputs. It must be a |
| 175 |
:class:`~django.db.models.Field` instance. By default is the same as |
| 176 |
its ``lhs.output_field``. |
| 177 |
|
| 178 |
``Lookup`` reference |
| 179 |
==================== |
| 180 |
|
| 181 |
.. class:: Lookup |
| 182 |
|
| 183 |
A ``Lookup`` is a generic class to implement lookups. A lookup is a query |
| 184 |
expression with a left-hand side, :attr:`lhs`; a right-hand side, |
| 185 |
:attr:`rhs`; and a ``lookup_name`` that is used to produce a boolean |
| 186 |
comparison between ``lhs`` and ``rhs`` such as ``lhs in rhs`` or |
| 187 |
``lhs > rhs``. |
| 188 |
|
| 189 |
The primary notation to use a lookup in an expression is |
| 190 |
``<lhs>__<lookup_name>=<rhs>``. Lookups can also be used directly in |
| 191 |
``QuerySet`` filters:: |
| 192 |
|
| 193 |
Book.objects.filter(LessThan(F("word_count"), 7500)) |
| 194 |
|
| 195 |
…or annotations:: |
| 196 |
|
| 197 |
Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500)) |
| 198 |
|
| 199 |
.. attribute:: lhs |
| 200 |
|
| 201 |
The left-hand side - what is being looked up. The object typically |
| 202 |
follows the :ref:`Query Expression API <query-expression>`. It may also |
| 203 |
be a plain value. |
| 204 |
|
| 205 |
.. attribute:: rhs |
| 206 |
|
| 207 |
The right-hand side - what ``lhs`` is being compared against. It can be |
| 208 |
a plain value, or something that compiles into SQL, typically an |
| 209 |
``F()`` object or a ``QuerySet``. |
| 210 |
|
| 211 |
.. attribute:: lookup_name |
| 212 |
|
| 213 |
The name of this lookup, used to identify it on parsing query |
| 214 |
expressions. It cannot contain the string ``"__"``. |
| 215 |
|
| 216 |
.. attribute:: prepare_rhs |
| 217 |
|
| 218 |
Defaults to ``True``. When :attr:`rhs` is a plain value, |
| 219 |
:attr:`prepare_rhs` determines whether it should be prepared for use as |
| 220 |
a parameter in a query. In order to do so, |
| 221 |
``lhs.output_field.get_prep_value()`` is called if defined, or ``rhs`` |
| 222 |
is wrapped in :class:`Value() <django.db.models.Value>` otherwise. |
| 223 |
|
| 224 |
.. method:: process_lhs(compiler, connection, lhs=None) |
| 225 |
|
| 226 |
Returns a tuple ``(lhs_string, lhs_params)``, as returned by |
| 227 |
``compiler.compile(lhs)``. This method can be overridden to tune how |
| 228 |
the ``lhs`` is processed. |
| 229 |
|
| 230 |
``compiler`` is an ``SQLCompiler`` object, to be used like |
| 231 |
``compiler.compile(lhs)`` for compiling ``lhs``. The ``connection`` |
| 232 |
can be used for compiling vendor specific SQL. If ``lhs`` is not |
| 233 |
``None``, use it as the processed ``lhs`` instead of ``self.lhs``. |
| 234 |
|
| 235 |
.. method:: process_rhs(compiler, connection) |
| 236 |
|
| 237 |
Behaves the same way as :meth:`process_lhs`, for the right-hand side. |