mirror of
https://github.com/django/django.git
synced 2024-11-30 07:06:18 +01:00
208 lines
7.6 KiB
Plaintext
208 lines
7.6 KiB
Plaintext
====================
|
|
Lookup API reference
|
|
====================
|
|
|
|
.. module:: django.db.models.lookups
|
|
:synopsis: Lookups API
|
|
|
|
.. currentmodule:: django.db.models
|
|
|
|
.. versionadded:: 1.7
|
|
|
|
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 `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. The two prominent examples are
|
|
:class:`~django.db.models.Field`, the base class of all model fields, and
|
|
``Aggregate``, the base class of all Django aggregates.
|
|
|
|
.. class:: lookups.RegisterLookupMixin
|
|
|
|
A mixin that implements the lookup API on a class.
|
|
|
|
.. classmethod:: register_lookup(lookup)
|
|
|
|
Registers a new lookup in the class. For example
|
|
``DateField.register_lookup(YearExact)`` will register ``YearExact``
|
|
lookup on ``DateField``. It overrides a lookup that already exists with
|
|
the same name.
|
|
|
|
.. method:: get_lookup(lookup_name)
|
|
|
|
Returns the :class:`Lookup` named ``lookup_name`` registered 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.
|
|
|
|
.. method:: get_transform(transform_name)
|
|
|
|
Returns a :class:`Transform` named ``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
|
|
<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(self, qn, connection)
|
|
|
|
Responsible for producing the query string and parameters for the expression.
|
|
The ``qn`` 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
|
|
``qn.compile(expression)`` should be used. The ``qn.compile()`` method will
|
|
take care of calling vendor-specific methods of the expression.
|
|
|
|
.. method:: as_vendorname(self, qn, connection)
|
|
|
|
Works like ``as_sql()`` method. When an expression is compiled by
|
|
``qn.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 an lookup expression is
|
|
``<expression>__<transformation>`` (e.g. ``date__year``).
|
|
|
|
This class follows the `Query Expression API <query-expression>`_, which
|
|
implies that you can use ``<expression>__<transform1>__<transform2>``.
|
|
|
|
.. attribute:: lhs
|
|
|
|
The left-hand side - what is being transformed. It must follow the
|
|
`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``.
|
|
|
|
.. method:: as_sql
|
|
|
|
To be overridden; raises :exc:`NotImplementedError`.
|
|
|
|
.. method:: get_lookup(lookup_name)
|
|
|
|
Same as :meth:`~lookups.RegisterLookupMixin.get_lookup()`.
|
|
|
|
.. method:: get_transform(transform_name)
|
|
|
|
Same as :meth:`~lookups.RegisterLookupMixin.get_transform()`.
|
|
|
|
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 notation to use a lookup in an expression is
|
|
``<lhs>__<lookup_name>=<rhs>``.
|
|
|
|
This class doesn't follow the `Query Expression API <query-expression>`_
|
|
since it has ``=<rhs>`` on its construction: lookups are always the end of
|
|
a lookup expression.
|
|
|
|
.. attribute:: lhs
|
|
|
|
The left-hand side - what is being looked up. The object must follow
|
|
the `Query Expression API <query-expression>`_.
|
|
|
|
.. 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 ``"__"``.
|
|
|
|
.. method:: process_lhs(qn, connection[, lhs=None])
|
|
|
|
Returns a tuple ``(lhs_string, lhs_params)``, as returned by
|
|
``qn.compile(lhs)``. This method can be overridden to tune how the
|
|
``lhs`` is processed.
|
|
|
|
``qn`` is an ``SQLCompiler`` object, to be used like ``qn.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(qn, connection)
|
|
|
|
Behaves the same way as :meth:`process_lhs`, for the right-hand side.
|