Debian Codegraph @

docs/ref/models/lookups.txt

raw
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.