mirror of
https://github.com/django/django.git
synced 2025-09-17 22:49:35 +00:00
f81e6e3a53
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
243 lines
9.5 KiB
Plaintext
243 lines
9.5 KiB
Plaintext
====================
|
|
Lookup API reference
|
|
====================
|
|
|
|
.. module:: django.db.models.lookups
|
|
:synopsis: Lookups API
|
|
|
|
.. currentmodule:: django.db.models
|
|
|
|
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
|
|
:doc:`/topics/db/queries`; to learn how to *create* new lookups, see
|
|
:doc:`/howto/custom-lookups`.
|
|
|
|
The lookup API has two components: a :class:`~lookups.RegisterLookupMixin`
|
|
class that registers lookups, and the :ref:`Query Expression API
|
|
<query-expression>`, 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:
|
|
|
|
* :class:`Lookup`: to lookup a field (e.g. the ``exact`` of
|
|
``field_name__exact``)
|
|
* :class:`Transform`: to transform a field
|
|
|
|
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``.
|
|
|
|
.. _lookup-registration-api:
|
|
|
|
Registration API
|
|
================
|
|
|
|
Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface
|
|
to register lookups on itself or its instances. The two prominent examples are
|
|
:class:`~django.db.models.Field`, the base class of all model fields, and
|
|
:class:`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 or class instance. For example::
|
|
|
|
DateField.register_lookup(YearExact)
|
|
User._meta.get_field("date_joined").register_lookup(MonthExact)
|
|
|
|
will register ``YearExact`` lookup on ``DateField`` and ``MonthExact``
|
|
lookup on the ``User.date_joined`` (you can use :ref:`Field Access API
|
|
<model-meta-field-api>` to retrieve a single field instance). It
|
|
overrides a lookup that already exists with the same name. Lookups
|
|
registered on field instances take precedence over the lookups
|
|
registered on classes. ``lookup_name`` will be used for this lookup if
|
|
provided, otherwise ``lookup.lookup_name`` will be used.
|
|
|
|
.. method:: get_lookup(lookup_name)
|
|
|
|
Returns the :class:`Lookup` named ``lookup_name`` registered in the
|
|
class or class instance depending on what calls it. The default
|
|
implementation looks recursively on all parent classes and checks if
|
|
any has a registered lookup named ``lookup_name``, returning the first
|
|
match. Instance lookups would override any class lookups with the same
|
|
``lookup_name``.
|
|
|
|
.. method:: get_lookups()
|
|
|
|
Returns a dictionary of each lookup name registered in the class or
|
|
class instance mapped to the :class:`Lookup` class.
|
|
|
|
.. method:: get_transform(transform_name)
|
|
|
|
Returns a :class:`Transform` named ``transform_name`` registered in the
|
|
class or class instance. 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 :ref:`Query Expression API
|
|
<query-expression>`. :class:`~Lookup` and :class:`~Transform` naturally
|
|
follow this API.
|
|
|
|
.. _query-expression:
|
|
|
|
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:
|
|
|
|
.. method:: as_sql(compiler, connection)
|
|
|
|
Generates the SQL fragment for the expression. Returns a tuple
|
|
``(sql, params)``, where ``sql`` is the SQL string, and ``params`` is the
|
|
list or tuple of query parameters. The ``compiler`` is an ``SQLCompiler``
|
|
object, which has a ``compile()`` method that can be used to compile other
|
|
expressions. The ``connection`` is the connection used to execute the
|
|
query.
|
|
|
|
Calling ``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.
|
|
|
|
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. See :meth:`Func.as_sql` for
|
|
example usage.
|
|
|
|
.. method:: as_vendorname(compiler, connection)
|
|
|
|
Works like ``as_sql()`` method. When an expression is compiled by
|
|
``compiler.compile()``, Django will first try to call ``as_vendorname()``,
|
|
where ``vendorname`` is the vendor name of the backend used for executing
|
|
the query. The ``vendorname`` is one of ``postgresql``, ``oracle``,
|
|
``sqlite``, or ``mysql`` for Django's built-in backends.
|
|
|
|
.. method:: get_lookup(lookup_name)
|
|
|
|
Must return the lookup named ``lookup_name``. For instance, by returning
|
|
``self.output_field.get_lookup(lookup_name)``.
|
|
|
|
.. method:: get_transform(transform_name)
|
|
|
|
Must return the lookup named ``transform_name``. For instance, by returning
|
|
``self.output_field.get_transform(transform_name)``.
|
|
|
|
.. attribute:: output_field
|
|
|
|
Defines the type of class returned by the ``get_lookup()`` method. It must
|
|
be a :class:`~django.db.models.Field` instance.
|
|
|
|
``Transform`` reference
|
|
=======================
|
|
|
|
.. class:: Transform
|
|
|
|
A ``Transform`` is a generic class to implement field transformations. A
|
|
prominent example is ``__year`` that transforms a ``DateField`` into a
|
|
``IntegerField``.
|
|
|
|
The notation to use a ``Transform`` in a lookup expression is
|
|
``<expression>__<transformation>`` (e.g. ``date__year``).
|
|
|
|
This class follows the :ref:`Query Expression API <query-expression>`,
|
|
which implies that you can use
|
|
``<expression>__<transform1>__<transform2>``. It's a specialized
|
|
:ref:`Func() expression <func-expressions>` that only accepts one argument.
|
|
It can also be used on the right hand side of a filter or directly as an
|
|
annotation.
|
|
|
|
.. attribute:: bilateral
|
|
|
|
A boolean indicating whether this transformation should apply to both
|
|
``lhs`` and ``rhs``. Bilateral transformations will be applied to
|
|
``rhs`` in the same order as they appear in the lookup expression. By
|
|
default it is set to ``False``. For example usage, see
|
|
:doc:`/howto/custom-lookups`.
|
|
|
|
.. attribute:: lhs
|
|
|
|
The left-hand side - what is being transformed. It must follow the
|
|
:ref:`Query Expression API <query-expression>`.
|
|
|
|
.. attribute:: lookup_name
|
|
|
|
The name of the lookup, used for identifying it on parsing query
|
|
expressions. It cannot contain the string ``"__"``.
|
|
|
|
.. attribute:: output_field
|
|
|
|
Defines the class this transformation outputs. It must be a
|
|
:class:`~django.db.models.Field` instance. By default is the same as
|
|
its ``lhs.output_field``.
|
|
|
|
``Lookup`` reference
|
|
====================
|
|
|
|
.. class:: Lookup
|
|
|
|
A ``Lookup`` is a generic class to implement lookups. A lookup is a query
|
|
expression with a left-hand side, :attr:`lhs`; a right-hand side,
|
|
:attr:`rhs`; and a ``lookup_name`` that is used to produce a boolean
|
|
comparison between ``lhs`` and ``rhs`` such as ``lhs in rhs`` or
|
|
``lhs > rhs``.
|
|
|
|
The primary notation to use a lookup in an expression is
|
|
``<lhs>__<lookup_name>=<rhs>``. Lookups can also be used directly in
|
|
``QuerySet`` filters::
|
|
|
|
Book.objects.filter(LessThan(F("word_count"), 7500))
|
|
|
|
…or annotations::
|
|
|
|
Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500))
|
|
|
|
.. attribute:: lhs
|
|
|
|
The left-hand side - what is being looked up. The object typically
|
|
follows the :ref:`Query Expression API <query-expression>`. It may also
|
|
be a plain value.
|
|
|
|
.. attribute:: rhs
|
|
|
|
The right-hand side - what ``lhs`` is being compared against. It can be
|
|
a plain value, or something that compiles into SQL, typically an
|
|
``F()`` object or a ``QuerySet``.
|
|
|
|
.. attribute:: lookup_name
|
|
|
|
The name of this lookup, used to identify it on parsing query
|
|
expressions. It cannot contain the string ``"__"``.
|
|
|
|
.. attribute:: prepare_rhs
|
|
|
|
Defaults to ``True``. When :attr:`rhs` is a plain value,
|
|
:attr:`prepare_rhs` determines whether it should be prepared for use as
|
|
a parameter in a query. In order to do so,
|
|
``lhs.output_field.get_prep_value()`` is called if defined, or ``rhs``
|
|
is wrapped in :class:`Value() <django.db.models.Value>` otherwise.
|
|
|
|
.. method:: process_lhs(compiler, connection, lhs=None)
|
|
|
|
Returns a tuple ``(lhs_string, lhs_params)``, as returned by
|
|
``compiler.compile(lhs)``. This method can be overridden to tune how
|
|
the ``lhs`` is processed.
|
|
|
|
``compiler`` is an ``SQLCompiler`` object, to be used like
|
|
``compiler.compile(lhs)`` for compiling ``lhs``. The ``connection``
|
|
can be used for compiling vendor specific SQL. If ``lhs`` is not
|
|
``None``, use it as the processed ``lhs`` instead of ``self.lhs``.
|
|
|
|
.. method:: process_rhs(compiler, connection)
|
|
|
|
Behaves the same way as :meth:`process_lhs`, for the right-hand side.
|