2008-08-23 22:25:40 +00:00
|
|
|
|
======================
|
|
|
|
|
QuerySet API reference
|
|
|
|
|
======================
|
|
|
|
|
|
2011-03-08 19:51:19 +00:00
|
|
|
|
.. currentmodule:: django.db.models.query
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
This document describes the details of the ``QuerySet`` API. It builds on the
|
2010-08-19 19:27:44 +00:00
|
|
|
|
material presented in the :doc:`model </topics/db/models>` and :doc:`database
|
|
|
|
|
query </topics/db/queries>` guides, so you'll probably want to read and
|
2008-09-11 00:24:02 +00:00
|
|
|
|
understand those documents before reading this one.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-10-09 08:12:50 +00:00
|
|
|
|
Throughout this reference we'll use the :ref:`example Weblog models
|
2010-08-19 19:27:44 +00:00
|
|
|
|
<queryset-model-example>` presented in the :doc:`database query guide
|
|
|
|
|
</topics/db/queries>`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
.. _when-querysets-are-evaluated:
|
|
|
|
|
|
|
|
|
|
When QuerySets are evaluated
|
|
|
|
|
============================
|
|
|
|
|
|
2009-09-12 22:59:41 +00:00
|
|
|
|
Internally, a ``QuerySet`` can be constructed, filtered, sliced, and generally
|
2008-08-23 22:25:40 +00:00
|
|
|
|
passed around without actually hitting the database. No database activity
|
|
|
|
|
actually occurs until you do something to evaluate the queryset.
|
|
|
|
|
|
|
|
|
|
You can evaluate a ``QuerySet`` in the following ways:
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **Iteration.** A ``QuerySet`` is iterable, and it executes its database
|
|
|
|
|
query the first time you iterate over it. For example, this will print
|
|
|
|
|
the headline of all entries in the database::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
for e in Entry.objects.all():
|
2012-04-28 16:02:01 +00:00
|
|
|
|
print(e.headline)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2012-09-08 15:19:49 +00:00
|
|
|
|
Note: Don't use this if all you want to do is determine if at least one
|
|
|
|
|
result exists. It's more efficient to use :meth:`~QuerySet.exists`.
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
|
2012-01-21 15:32:52 +00:00
|
|
|
|
be sliced, using Python's array-slicing syntax. Slicing an unevaluated
|
|
|
|
|
``QuerySet`` usually returns another unevaluated ``QuerySet``, but Django
|
|
|
|
|
will execute the database query if you use the "step" parameter of slice
|
|
|
|
|
syntax, and will return a list. Slicing a ``QuerySet`` that has been
|
2014-11-13 18:59:00 +00:00
|
|
|
|
evaluated also returns a list.
|
|
|
|
|
|
|
|
|
|
Also note that even though slicing an unevaluated ``QuerySet`` returns
|
|
|
|
|
another unevaluated ``QuerySet``, modifying it further (e.g., adding
|
|
|
|
|
more filters, or modifying ordering) is not allowed, since that does not
|
|
|
|
|
translate well into SQL and it would not have a clear meaning either.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **Pickling/Caching.** See the following section for details of what
|
|
|
|
|
is involved when `pickling QuerySets`_. The important thing for the
|
|
|
|
|
purposes of this section is that the results are read from the database.
|
2008-09-28 03:08:30 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
|
|
|
|
|
This is for convenience in the Python interactive interpreter, so you can
|
|
|
|
|
immediately see your results when using the API interactively.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
|
|
|
|
|
This, as you might expect, returns the length of the result list.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-01-20 15:20:02 +00:00
|
|
|
|
Note: If you only need to determine the number of records in the set (and
|
|
|
|
|
don't need the actual objects), it's much more efficient to handle a count
|
|
|
|
|
at the database level using SQL's ``SELECT COUNT(*)``. Django provides a
|
|
|
|
|
:meth:`~QuerySet.count` method for precisely this reason.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
|
|
|
|
|
it. For example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
entry_list = list(Entry.objects.all())
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* **bool().** Testing a ``QuerySet`` in a boolean context, such as using
|
|
|
|
|
``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query
|
|
|
|
|
to be executed. If there is at least one result, the ``QuerySet`` is
|
|
|
|
|
``True``, otherwise ``False``. For example::
|
2010-01-16 03:13:16 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
if Entry.objects.filter(headline="Test"):
|
2012-04-28 16:02:01 +00:00
|
|
|
|
print("There is at least one Entry with the headline Test")
|
2010-01-16 03:13:16 +00:00
|
|
|
|
|
2015-01-20 15:20:02 +00:00
|
|
|
|
Note: If you only want to determine if at least one result exists (and don't
|
|
|
|
|
need the actual objects), it's more efficient to use :meth:`~QuerySet.exists`.
|
2010-01-16 03:13:16 +00:00
|
|
|
|
|
2008-09-28 03:08:30 +00:00
|
|
|
|
.. _pickling QuerySets:
|
|
|
|
|
|
|
|
|
|
Pickling QuerySets
|
|
|
|
|
------------------
|
|
|
|
|
|
2011-09-04 21:17:30 +00:00
|
|
|
|
If you :mod:`pickle` a ``QuerySet``, this will force all the results to be loaded
|
2008-09-28 03:08:30 +00:00
|
|
|
|
into memory prior to pickling. Pickling is usually used as a precursor to
|
|
|
|
|
caching and when the cached queryset is reloaded, you want the results to
|
|
|
|
|
already be present and ready for use (reading from the database can take some
|
|
|
|
|
time, defeating the purpose of caching). This means that when you unpickle a
|
|
|
|
|
``QuerySet``, it contains the results at the moment it was pickled, rather
|
|
|
|
|
than the results that are currently in the database.
|
|
|
|
|
|
|
|
|
|
If you only want to pickle the necessary information to recreate the
|
2010-05-10 13:14:19 +00:00
|
|
|
|
``QuerySet`` from the database at a later time, pickle the ``query`` attribute
|
2008-09-28 03:08:30 +00:00
|
|
|
|
of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without
|
|
|
|
|
any results loaded) using some code like this::
|
|
|
|
|
|
|
|
|
|
>>> import pickle
|
|
|
|
|
>>> query = pickle.loads(s) # Assuming 's' is the pickled string.
|
|
|
|
|
>>> qs = MyModel.objects.all()
|
|
|
|
|
>>> qs.query = query # Restore the original 'query'.
|
|
|
|
|
|
|
|
|
|
The ``query`` attribute is an opaque object. It represents the internals of
|
|
|
|
|
the query construction and is not part of the public API. However, it is safe
|
|
|
|
|
(and fully supported) to pickle and unpickle the attribute's contents as
|
|
|
|
|
described here.
|
|
|
|
|
|
2010-02-24 13:56:19 +00:00
|
|
|
|
.. admonition:: You can't share pickles between versions
|
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
Pickles of ``QuerySets`` are only valid for the version of Django that
|
2011-09-30 10:28:39 +00:00
|
|
|
|
was used to generate them. If you generate a pickle using Django
|
|
|
|
|
version N, there is no guarantee that pickle will be readable with
|
|
|
|
|
Django version N+1. Pickles should not be used as part of a long-term
|
|
|
|
|
archival strategy.
|
2010-02-24 13:56:19 +00:00
|
|
|
|
|
2014-06-06 11:10:20 +00:00
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
|
|
|
|
|
|
Since pickle compatibility errors can be difficult to diagnose, such as
|
|
|
|
|
silently corrupted objects, a ``RuntimeWarning`` is raised when you try to
|
|
|
|
|
unpickle a queryset in a Django version that is different than the one in
|
|
|
|
|
which it was pickled.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
.. _queryset-api:
|
|
|
|
|
|
|
|
|
|
QuerySet API
|
|
|
|
|
============
|
|
|
|
|
|
2013-07-26 08:59:40 +00:00
|
|
|
|
Here's the formal declaration of a ``QuerySet``:
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-07-27 12:35:21 +00:00
|
|
|
|
.. class:: QuerySet(model=None, query=None, using=None)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-03-08 19:51:19 +00:00
|
|
|
|
Usually when you'll interact with a ``QuerySet`` you'll use it by
|
|
|
|
|
:ref:`chaining filters <chaining-filters>`. To make this work, most
|
|
|
|
|
``QuerySet`` methods return new querysets. These methods are covered in
|
|
|
|
|
detail later in this section.
|
|
|
|
|
|
|
|
|
|
The ``QuerySet`` class has two public attributes you can use for
|
|
|
|
|
introspection:
|
|
|
|
|
|
|
|
|
|
.. attribute:: ordered
|
|
|
|
|
|
2011-09-30 10:28:39 +00:00
|
|
|
|
``True`` if the ``QuerySet`` is ordered — i.e. has an
|
|
|
|
|
:meth:`order_by()` clause or a default ordering on the model.
|
|
|
|
|
``False`` otherwise.
|
2011-03-08 19:51:19 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: db
|
2011-08-26 06:19:30 +00:00
|
|
|
|
|
2011-03-08 19:51:19 +00:00
|
|
|
|
The database that will be used if this query is executed now.
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
The ``query`` parameter to :class:`QuerySet` exists so that specialized
|
|
|
|
|
query subclasses such as
|
|
|
|
|
:class:`~django.contrib.gis.db.models.GeoQuerySet` can reconstruct
|
|
|
|
|
internal query state. The value of the parameter is an opaque
|
|
|
|
|
representation of that query state and is not part of a public API.
|
|
|
|
|
To put it simply: if you need to ask, you don't need to use it.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django.db.models.query.QuerySet
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Methods that return new QuerySets
|
|
|
|
|
---------------------------------
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Django provides a range of ``QuerySet`` refinement methods that modify either
|
|
|
|
|
the types of results returned by the ``QuerySet`` or the way its SQL query is
|
|
|
|
|
executed.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
filter
|
|
|
|
|
~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: filter(**kwargs)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns a new ``QuerySet`` containing objects that match the given lookup
|
|
|
|
|
parameters.
|
|
|
|
|
|
|
|
|
|
The lookup parameters (``**kwargs``) should be in the format described in
|
|
|
|
|
`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
|
|
|
|
|
underlying SQL statement.
|
|
|
|
|
|
2015-01-11 20:02:33 +00:00
|
|
|
|
If you need to execute more complex queries (for example, queries with ``OR`` statements),
|
|
|
|
|
you can use :class:`Q objects <django.db.models.Q>`.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
exclude
|
|
|
|
|
~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: exclude(**kwargs)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns a new ``QuerySet`` containing objects that do *not* match the given
|
|
|
|
|
lookup parameters.
|
|
|
|
|
|
|
|
|
|
The lookup parameters (``**kwargs``) should be in the format described in
|
|
|
|
|
`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
|
|
|
|
|
underlying SQL statement, and the whole thing is enclosed in a ``NOT()``.
|
|
|
|
|
|
|
|
|
|
This example excludes all entries whose ``pub_date`` is later than 2005-1-3
|
|
|
|
|
AND whose ``headline`` is "Hello"::
|
|
|
|
|
|
|
|
|
|
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')
|
|
|
|
|
|
|
|
|
|
In SQL terms, that evaluates to::
|
|
|
|
|
|
|
|
|
|
SELECT ...
|
|
|
|
|
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')
|
|
|
|
|
|
|
|
|
|
This example excludes all entries whose ``pub_date`` is later than 2005-1-3
|
|
|
|
|
OR whose headline is "Hello"::
|
|
|
|
|
|
|
|
|
|
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello')
|
|
|
|
|
|
|
|
|
|
In SQL terms, that evaluates to::
|
|
|
|
|
|
|
|
|
|
SELECT ...
|
|
|
|
|
WHERE NOT pub_date > '2005-1-3'
|
2010-04-06 14:35:36 +00:00
|
|
|
|
AND NOT headline = 'Hello'
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Note the second example is more restrictive.
|
|
|
|
|
|
2015-01-11 20:02:33 +00:00
|
|
|
|
If you need to execute more complex queries (for example, queries with ``OR`` statements),
|
|
|
|
|
you can use :class:`Q objects <django.db.models.Q>`.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
annotate
|
|
|
|
|
~~~~~~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: annotate(*args, **kwargs)
|
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Annotates each object in the ``QuerySet`` with the provided list of :doc:`query
|
|
|
|
|
expressions </ref/models/expressions>`. An expression may be a simple value, a
|
|
|
|
|
reference to a field on the model (or any related models), or an aggregate
|
|
|
|
|
expression (averages, sums, etc) that has been computed over the objects that
|
|
|
|
|
are related to the objects in the ``QuerySet``.
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
|
|
|
|
|
|
Previous versions of Django only allowed aggregate functions to be used as
|
|
|
|
|
annotations. It is now possible to annotate a model with all kinds of
|
|
|
|
|
expressions.
|
|
|
|
|
|
2009-01-15 11:06:34 +00:00
|
|
|
|
Each argument to ``annotate()`` is an annotation that will be added
|
|
|
|
|
to each object in the ``QuerySet`` that is returned.
|
|
|
|
|
|
|
|
|
|
The aggregation functions that are provided by Django are described
|
|
|
|
|
in `Aggregation Functions`_ below.
|
|
|
|
|
|
|
|
|
|
Annotations specified using keyword arguments will use the keyword as
|
|
|
|
|
the alias for the annotation. Anonymous arguments will have an alias
|
|
|
|
|
generated for them based upon the name of the aggregate function and
|
2013-12-25 13:13:18 +00:00
|
|
|
|
the model field that is being aggregated. Only aggregate expressions
|
|
|
|
|
that reference a single field can be anonymous arguments. Everything
|
|
|
|
|
else must be a keyword argument.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
|
|
|
|
For example, if you were manipulating a list of blogs, you may want
|
|
|
|
|
to determine how many entries have been made in each blog::
|
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
>>> from django.db.models import Count
|
2009-01-15 11:06:34 +00:00
|
|
|
|
>>> q = Blog.objects.annotate(Count('entry'))
|
|
|
|
|
# The name of the first blog
|
|
|
|
|
>>> q[0].name
|
|
|
|
|
'Blogasaurus'
|
|
|
|
|
# The number of entries on the first blog
|
|
|
|
|
>>> q[0].entry__count
|
|
|
|
|
42
|
|
|
|
|
|
2009-04-16 12:45:35 +00:00
|
|
|
|
The ``Blog`` model doesn't define an ``entry__count`` attribute by itself,
|
2009-01-15 11:06:34 +00:00
|
|
|
|
but by using a keyword argument to specify the aggregate function, you can
|
|
|
|
|
control the name of the annotation::
|
|
|
|
|
|
|
|
|
|
>>> q = Blog.objects.annotate(number_of_entries=Count('entry'))
|
|
|
|
|
# The number of entries on the first blog, using the name provided
|
|
|
|
|
>>> q[0].number_of_entries
|
|
|
|
|
42
|
|
|
|
|
|
2010-08-19 19:27:44 +00:00
|
|
|
|
For an in-depth discussion of aggregation, see :doc:`the topic guide on
|
|
|
|
|
Aggregation </topics/db/aggregation>`.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
order_by
|
|
|
|
|
~~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: order_by(*fields)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
By default, results returned by a ``QuerySet`` are ordered by the ordering
|
|
|
|
|
tuple given by the ``ordering`` option in the model's ``Meta``. You can
|
|
|
|
|
override this on a per-``QuerySet`` basis by using the ``order_by`` method.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')
|
|
|
|
|
|
|
|
|
|
The result above will be ordered by ``pub_date`` descending, then by
|
|
|
|
|
``headline`` ascending. The negative sign in front of ``"-pub_date"`` indicates
|
|
|
|
|
*descending* order. Ascending order is implied. To order randomly, use ``"?"``,
|
|
|
|
|
like so::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('?')
|
|
|
|
|
|
|
|
|
|
Note: ``order_by('?')`` queries may be expensive and slow, depending on the
|
|
|
|
|
database backend you're using.
|
|
|
|
|
|
2008-08-29 05:04:26 +00:00
|
|
|
|
To order by a field in a different model, use the same syntax as when you are
|
|
|
|
|
querying across model relations. That is, the name of the field, followed by a
|
|
|
|
|
double underscore (``__``), followed by the name of the field in the new model,
|
|
|
|
|
and so on for as many models as you want to join. For example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('blog__name', 'headline')
|
|
|
|
|
|
|
|
|
|
If you try to order by a field that is a relation to another model, Django will
|
2014-11-12 21:00:48 +00:00
|
|
|
|
use the default ordering on the related model, or order by the related model's
|
2011-08-27 02:56:18 +00:00
|
|
|
|
primary key if there is no :attr:`Meta.ordering
|
2014-11-12 21:00:48 +00:00
|
|
|
|
<django.db.models.Options.ordering>` specified. For example, since the ``Blog``
|
|
|
|
|
model has no default ordering specified::
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('blog')
|
|
|
|
|
|
|
|
|
|
...is identical to::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('blog__id')
|
|
|
|
|
|
2014-11-12 21:00:48 +00:00
|
|
|
|
If ``Blog`` had ``ordering = ['name']``, then the first queryset would be
|
|
|
|
|
identical to::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('blog__name')
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-01-09 15:16:16 +00:00
|
|
|
|
It is also possible to order a queryset by a related field, without incurring
|
|
|
|
|
the cost of a JOIN, by referring to the ``_id`` of the related field::
|
|
|
|
|
|
|
|
|
|
# No Join
|
|
|
|
|
Entry.objects.order_by('blog_id')
|
|
|
|
|
|
|
|
|
|
# Join
|
|
|
|
|
Entry.objects.order_by('blog__id')
|
|
|
|
|
|
|
|
|
|
You can also order by :doc:`query expressions </ref/models/expressions>` by
|
|
|
|
|
calling ``asc()`` or ``desc()`` on the expression::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by(Coalesce('summary', 'headline').desc())
|
2014-04-26 07:34:20 +00:00
|
|
|
|
|
2015-01-09 15:16:16 +00:00
|
|
|
|
.. versionadded:: 1.8
|
2014-04-26 07:34:20 +00:00
|
|
|
|
|
2015-01-09 15:16:16 +00:00
|
|
|
|
Ordering by query expressions was added.
|
2014-04-26 07:34:20 +00:00
|
|
|
|
|
2008-08-29 05:04:26 +00:00
|
|
|
|
Be cautious when ordering by fields in related models if you are also using
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how
|
2010-11-28 18:15:40 +00:00
|
|
|
|
related model ordering can change the expected results.
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
.. note::
|
|
|
|
|
It is permissible to specify a multi-valued field to order the results by
|
|
|
|
|
(for example, a :class:`~django.db.models.ManyToManyField` field, or the
|
|
|
|
|
reverse relation of a :class:`~django.db.models.ForeignKey` field).
|
|
|
|
|
|
|
|
|
|
Consider this case::
|
|
|
|
|
|
|
|
|
|
class Event(Model):
|
2015-07-22 14:43:21 +00:00
|
|
|
|
parent = models.ForeignKey(
|
|
|
|
|
'self',
|
|
|
|
|
on_delete=models.CASCADE,
|
|
|
|
|
related_name='children',
|
|
|
|
|
)
|
2013-08-02 13:26:19 +00:00
|
|
|
|
date = models.DateField()
|
|
|
|
|
|
|
|
|
|
Event.objects.order_by('children__date')
|
|
|
|
|
|
|
|
|
|
Here, there could potentially be multiple ordering data for each ``Event``;
|
|
|
|
|
each ``Event`` with multiple ``children`` will be returned multiple times
|
|
|
|
|
into the new ``QuerySet`` that ``order_by()`` creates. In other words,
|
|
|
|
|
using ``order_by()`` on the ``QuerySet`` could return more items than you
|
|
|
|
|
were working on to begin with - which is probably neither expected nor
|
|
|
|
|
useful.
|
|
|
|
|
|
|
|
|
|
Thus, take care when using multi-valued field to order the results. **If**
|
|
|
|
|
you can be sure that there will only be one ordering piece of data for each
|
|
|
|
|
of the items you're ordering, this approach should not present problems. If
|
|
|
|
|
not, make sure the results are what you expect.
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
There's no way to specify whether ordering should be case sensitive. With
|
|
|
|
|
respect to case-sensitivity, Django will order results however your database
|
|
|
|
|
backend normally orders them.
|
|
|
|
|
|
2015-01-09 15:16:16 +00:00
|
|
|
|
You can order by a field converted to lowercase with
|
|
|
|
|
:class:`~django.db.models.functions.Lower` which will achieve case-consistent
|
|
|
|
|
ordering::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by(Lower('headline').desc())
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
|
|
|
|
|
|
The ability to order by expressions like ``Lower`` was added.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
If you don't want any ordering to be applied to a query, not even the default
|
2011-08-27 02:56:18 +00:00
|
|
|
|
ordering, call :meth:`order_by()` with no parameters.
|
2010-11-28 18:15:40 +00:00
|
|
|
|
|
2009-04-22 22:16:19 +00:00
|
|
|
|
You can tell if a query is ordered or not by checking the
|
2011-03-08 19:51:19 +00:00
|
|
|
|
:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the
|
2009-04-22 22:16:19 +00:00
|
|
|
|
``QuerySet`` has been ordered in any way.
|
|
|
|
|
|
2015-03-13 19:40:25 +00:00
|
|
|
|
Each ``order_by()`` call will clear any previous ordering. For example, this
|
|
|
|
|
query will be ordered by ``pub_date`` and not ``headline``::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('headline').order_by('pub_date')
|
|
|
|
|
|
2013-09-08 19:57:36 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Ordering is not a free operation. Each field you add to the ordering
|
|
|
|
|
incurs a cost to your database. Each foreign key you add will
|
2013-09-09 15:30:31 +00:00
|
|
|
|
implicitly include all of its default orderings as well.
|
2013-09-08 19:57:36 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
reverse
|
|
|
|
|
~~~~~~~
|
2008-09-11 00:24:02 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: reverse()
|
|
|
|
|
|
2008-09-11 00:24:02 +00:00
|
|
|
|
Use the ``reverse()`` method to reverse the order in which a queryset's
|
|
|
|
|
elements are returned. Calling ``reverse()`` a second time restores the
|
|
|
|
|
ordering back to the normal direction.
|
|
|
|
|
|
2013-05-12 19:24:48 +00:00
|
|
|
|
To retrieve the "last" five items in a queryset, you could do this::
|
2008-09-11 00:24:02 +00:00
|
|
|
|
|
|
|
|
|
my_queryset.reverse()[:5]
|
|
|
|
|
|
|
|
|
|
Note that this is not quite the same as slicing from the end of a sequence in
|
|
|
|
|
Python. The above example will return the last item first, then the
|
|
|
|
|
penultimate item and so on. If we had a Python sequence and looked at
|
|
|
|
|
``seq[-5:]``, we would see the fifth-last item first. Django doesn't support
|
|
|
|
|
that mode of access (slicing from the end), because it's not possible to do it
|
|
|
|
|
efficiently in SQL.
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Also, note that ``reverse()`` should generally only be called on a ``QuerySet``
|
|
|
|
|
which has a defined ordering (e.g., when querying against a model which defines
|
|
|
|
|
a default ordering, or when using :meth:`order_by()`). If no such ordering is
|
|
|
|
|
defined for a given ``QuerySet``, calling ``reverse()`` on it has no real
|
|
|
|
|
effect (the ordering was undefined prior to calling ``reverse()``, and will
|
|
|
|
|
remain undefined afterward).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
distinct
|
|
|
|
|
~~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-07-27 12:35:21 +00:00
|
|
|
|
.. method:: distinct(*fields)
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This
|
|
|
|
|
eliminates duplicate rows from the query results.
|
|
|
|
|
|
|
|
|
|
By default, a ``QuerySet`` will not eliminate duplicate rows. In practice, this
|
|
|
|
|
is rarely a problem, because simple queries such as ``Blog.objects.all()``
|
2008-08-29 05:04:26 +00:00
|
|
|
|
don't introduce the possibility of duplicate result rows. However, if your
|
|
|
|
|
query spans multiple tables, it's possible to get duplicate results when a
|
|
|
|
|
``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
|
|
|
|
|
|
|
|
|
|
.. note::
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Any fields used in an :meth:`order_by` call are included in the SQL
|
2011-08-27 02:56:18 +00:00
|
|
|
|
``SELECT`` columns. This can sometimes lead to unexpected results when used
|
|
|
|
|
in conjunction with ``distinct()``. If you order by fields from a related
|
|
|
|
|
model, those fields will be added to the selected columns and they may make
|
|
|
|
|
otherwise duplicate rows appear to be distinct. Since the extra columns
|
|
|
|
|
don't appear in the returned results (they are only there to support
|
|
|
|
|
ordering), it sometimes looks like non-distinct results are being returned.
|
|
|
|
|
|
|
|
|
|
Similarly, if you use a :meth:`values()` query to restrict the columns
|
|
|
|
|
selected, the columns used in any :meth:`order_by()` (or default model
|
2008-08-29 05:04:26 +00:00
|
|
|
|
ordering) will still be involved and may affect uniqueness of the results.
|
|
|
|
|
|
|
|
|
|
The moral here is that if you are using ``distinct()`` be careful about
|
|
|
|
|
ordering by related models. Similarly, when using ``distinct()`` and
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:meth:`values()` together, be careful when ordering by fields not in the
|
|
|
|
|
:meth:`values()` call.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-07-05 11:20:05 +00:00
|
|
|
|
On PostgreSQL only, you can pass positional arguments (``*fields``) in order to
|
|
|
|
|
specify the names of fields to which the ``DISTINCT`` should apply. This
|
|
|
|
|
translates to a ``SELECT DISTINCT ON`` SQL query. Here's the difference. For a
|
|
|
|
|
normal ``distinct()`` call, the database compares *each* field in each row when
|
2012-12-26 20:47:29 +00:00
|
|
|
|
determining which rows are distinct. For a ``distinct()`` call with specified
|
|
|
|
|
field names, the database will only compare the specified field names.
|
2011-12-22 20:42:40 +00:00
|
|
|
|
|
|
|
|
|
.. note::
|
2011-12-30 18:01:34 +00:00
|
|
|
|
When you specify field names, you *must* provide an ``order_by()`` in the
|
2013-08-02 13:26:19 +00:00
|
|
|
|
``QuerySet``, and the fields in ``order_by()`` must start with the fields in
|
2011-12-30 18:01:34 +00:00
|
|
|
|
``distinct()``, in the same order.
|
|
|
|
|
|
|
|
|
|
For example, ``SELECT DISTINCT ON (a)`` gives you the first row for each
|
|
|
|
|
value in column ``a``. If you don't specify an order, you'll get some
|
|
|
|
|
arbitrary row.
|
2011-12-22 20:42:40 +00:00
|
|
|
|
|
2013-07-05 11:20:05 +00:00
|
|
|
|
Examples (those after the first will only work on PostgreSQL)::
|
2011-12-22 20:42:40 +00:00
|
|
|
|
|
|
|
|
|
>>> Author.objects.distinct()
|
|
|
|
|
[...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.order_by('pub_date').distinct('pub_date')
|
|
|
|
|
[...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.order_by('blog').distinct('blog')
|
|
|
|
|
[...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.order_by('author', 'pub_date').distinct('author', 'pub_date')
|
|
|
|
|
[...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.order_by('blog__name', 'mod_date').distinct('blog__name', 'mod_date')
|
|
|
|
|
[...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.order_by('author', 'pub_date').distinct('author')
|
|
|
|
|
[...]
|
|
|
|
|
|
2014-04-26 07:34:20 +00:00
|
|
|
|
.. note::
|
|
|
|
|
Keep in mind that :meth:`order_by` uses any default related model ordering
|
|
|
|
|
that has been defined. You might have to explicitly order by the relation
|
|
|
|
|
``_id`` or referenced field to make sure the ``DISTINCT ON`` expressions
|
|
|
|
|
match those at the beginning of the ``ORDER BY`` clause. For example, if
|
|
|
|
|
the ``Blog`` model defined an :attr:`~django.db.models.Options.ordering` by
|
|
|
|
|
``name``::
|
|
|
|
|
|
|
|
|
|
Entry.objects.order_by('blog').distinct('blog')
|
|
|
|
|
|
|
|
|
|
...wouldn't work because the query would be ordered by ``blog__name`` thus
|
|
|
|
|
mismatching the ``DISTINCT ON`` expression. You'd have to explicitly order
|
|
|
|
|
by the relation `_id` field (``blog_id`` in this case) or the referenced
|
|
|
|
|
one (``blog__pk``) to make sure both expressions match.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
values
|
|
|
|
|
~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: values(*fields)
|
|
|
|
|
|
2015-01-30 07:26:13 +00:00
|
|
|
|
Returns a ``QuerySet`` that returns dictionaries, rather than model instances,
|
|
|
|
|
when used as an iterable.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Each of those dictionaries represents an object, with the keys corresponding to
|
|
|
|
|
the attribute names of model objects.
|
|
|
|
|
|
|
|
|
|
This example compares the dictionaries of ``values()`` with the normal model
|
|
|
|
|
objects::
|
|
|
|
|
|
|
|
|
|
# This list contains a Blog object.
|
|
|
|
|
>>> Blog.objects.filter(name__startswith='Beatles')
|
2008-08-28 13:40:20 +00:00
|
|
|
|
[<Blog: Beatles Blog>]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
# This list contains a dictionary.
|
|
|
|
|
>>> Blog.objects.filter(name__startswith='Beatles').values()
|
|
|
|
|
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
The ``values()`` method takes optional positional arguments, ``*fields``, which
|
|
|
|
|
specify field names to which the ``SELECT`` should be limited. If you specify
|
|
|
|
|
the fields, each dictionary will contain only the field keys/values for the
|
|
|
|
|
fields you specify. If you don't specify the fields, each dictionary will
|
|
|
|
|
contain a key and value for every field in the database table.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
>>> Blog.objects.values()
|
|
|
|
|
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
|
|
|
|
|
>>> Blog.objects.values('id', 'name')
|
|
|
|
|
[{'id': 1, 'name': 'Beatles Blog'}]
|
|
|
|
|
|
2010-11-21 02:28:25 +00:00
|
|
|
|
A few subtleties that are worth mentioning:
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* If you have a field called ``foo`` that is a
|
|
|
|
|
:class:`~django.db.models.ForeignKey`, the default ``values()`` call
|
|
|
|
|
will return a dictionary key called ``foo_id``, since this is the name
|
|
|
|
|
of the hidden model attribute that stores the actual value (the ``foo``
|
|
|
|
|
attribute refers to the related model). When you are calling
|
|
|
|
|
``values()`` and passing in field names, you can pass in either ``foo``
|
|
|
|
|
or ``foo_id`` and you will get back the same thing (the dictionary key
|
|
|
|
|
will match the field name you passed in).
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
For example::
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
>>> Entry.objects.values()
|
2014-03-22 20:30:49 +00:00
|
|
|
|
[{'blog_id': 1, 'headline': 'First Entry', ...}, ...]
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
>>> Entry.objects.values('blog')
|
|
|
|
|
[{'blog': 1}, ...]
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
>>> Entry.objects.values('blog_id')
|
|
|
|
|
[{'blog_id': 1}, ...]
|
2010-11-28 18:15:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* When using ``values()`` together with :meth:`distinct()`, be aware that
|
|
|
|
|
ordering can affect the results. See the note in :meth:`distinct` for
|
|
|
|
|
details.
|
2010-11-28 18:15:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* If you use a ``values()`` clause after an :meth:`extra()` call,
|
|
|
|
|
any fields defined by a ``select`` argument in the :meth:`extra()` must
|
|
|
|
|
be explicitly included in the ``values()`` call. Any :meth:`extra()` call
|
|
|
|
|
made after a ``values()`` call will have its extra selected fields
|
|
|
|
|
ignored.
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2014-02-15 21:44:14 +00:00
|
|
|
|
* Calling :meth:`only()` and :meth:`defer()` after ``values()`` doesn't make
|
|
|
|
|
sense, so doing so will raise a ``NotImplementedError``.
|
|
|
|
|
|
2015-01-30 07:26:13 +00:00
|
|
|
|
It is useful when you know you're only going to need values from a small number
|
|
|
|
|
of the available fields and you won't need the functionality of a model
|
|
|
|
|
instance object. It's more efficient to select only the fields you need to use.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-01-30 07:26:13 +00:00
|
|
|
|
Finally, note that you can call ``filter()``, ``order_by()``, etc. after the
|
|
|
|
|
``values()`` call, that means that these two calls are identical::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Blog.objects.values().order_by('id')
|
|
|
|
|
Blog.objects.order_by('id').values()
|
|
|
|
|
|
|
|
|
|
The people who made Django prefer to put all the SQL-affecting methods first,
|
|
|
|
|
followed (optionally) by any output-affecting methods (such as ``values()``),
|
|
|
|
|
but it doesn't really matter. This is your chance to really flaunt your
|
|
|
|
|
individualism.
|
|
|
|
|
|
2012-09-19 20:39:14 +00:00
|
|
|
|
You can also refer to fields on related models with reverse relations through
|
|
|
|
|
``OneToOneField``, ``ForeignKey`` and ``ManyToManyField`` attributes::
|
2010-11-21 02:28:25 +00:00
|
|
|
|
|
2011-09-30 10:28:39 +00:00
|
|
|
|
Blog.objects.values('name', 'entry__headline')
|
|
|
|
|
[{'name': 'My blog', 'entry__headline': 'An entry'},
|
2010-11-21 02:28:25 +00:00
|
|
|
|
{'name': 'My blog', 'entry__headline': 'Another entry'}, ...]
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Because :class:`~django.db.models.ManyToManyField` attributes and reverse
|
|
|
|
|
relations can have multiple related rows, including these can have a
|
|
|
|
|
multiplier effect on the size of your result set. This will be especially
|
|
|
|
|
pronounced if you include multiple such fields in your ``values()`` query,
|
|
|
|
|
in which case all possible combinations will be returned.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
values_list
|
|
|
|
|
~~~~~~~~~~~
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
2014-10-01 14:24:46 +00:00
|
|
|
|
.. method:: values_list(*fields, flat=False)
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
2010-03-10 03:41:41 +00:00
|
|
|
|
This is similar to ``values()`` except that instead of returning dictionaries,
|
|
|
|
|
it returns tuples when iterated over. Each tuple contains the value from the
|
2011-08-27 02:56:18 +00:00
|
|
|
|
respective field passed into the ``values_list()`` call — so the first item is
|
2010-03-10 03:41:41 +00:00
|
|
|
|
the first field, etc. For example::
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
|
|
|
|
>>> Entry.objects.values_list('id', 'headline')
|
2014-03-22 20:30:49 +00:00
|
|
|
|
[(1, 'First entry'), ...]
|
2008-08-29 05:04:26 +00:00
|
|
|
|
|
|
|
|
|
If you only pass in a single field, you can also pass in the ``flat``
|
|
|
|
|
parameter. If ``True``, this will mean the returned results are single values,
|
|
|
|
|
rather than one-tuples. An example should make the difference clearer::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.values_list('id').order_by('id')
|
|
|
|
|
[(1,), (2,), (3,), ...]
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.values_list('id', flat=True).order_by('id')
|
|
|
|
|
[1, 2, 3, ...]
|
|
|
|
|
|
|
|
|
|
It is an error to pass in ``flat`` when there is more than one field.
|
|
|
|
|
|
|
|
|
|
If you don't pass any values to ``values_list()``, it will return all the
|
|
|
|
|
fields in the model, in the order they were declared.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
dates
|
|
|
|
|
~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: dates(field, kind, order='ASC')
|
|
|
|
|
|
2015-09-11 15:14:35 +00:00
|
|
|
|
Returns a ``QuerySet`` that evaluates to a list of :class:`datetime.date`
|
|
|
|
|
objects representing all available dates of a particular kind within the
|
|
|
|
|
contents of the ``QuerySet``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
``field`` should be the name of a ``DateField`` of your model.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each
|
2013-02-10 15:15:49 +00:00
|
|
|
|
``datetime.date`` object in the result list is "truncated" to the given
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``type``.
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* ``"year"`` returns a list of all distinct year values for the field.
|
|
|
|
|
* ``"month"`` returns a list of all distinct year/month values for the
|
|
|
|
|
field.
|
|
|
|
|
* ``"day"`` returns a list of all distinct year/month/day values for the
|
|
|
|
|
field.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
|
|
|
|
|
``'DESC'``. This specifies how to order the results.
|
|
|
|
|
|
|
|
|
|
Examples::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.dates('pub_date', 'year')
|
2013-02-10 15:15:49 +00:00
|
|
|
|
[datetime.date(2005, 1, 1)]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Entry.objects.dates('pub_date', 'month')
|
2013-02-10 15:15:49 +00:00
|
|
|
|
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Entry.objects.dates('pub_date', 'day')
|
2013-02-10 15:15:49 +00:00
|
|
|
|
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Entry.objects.dates('pub_date', 'day', order='DESC')
|
2013-02-10 15:15:49 +00:00
|
|
|
|
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
|
2013-02-10 15:15:49 +00:00
|
|
|
|
[datetime.date(2005, 3, 20)]
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
datetimes
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
2014-10-27 22:18:37 +00:00
|
|
|
|
.. method:: datetimes(field_name, kind, order='ASC', tzinfo=None)
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-04-18 14:13:41 +00:00
|
|
|
|
Returns a ``QuerySet`` that evaluates to a list of :class:`datetime.datetime`
|
|
|
|
|
objects representing all available dates of a particular kind within the
|
|
|
|
|
contents of the ``QuerySet``.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2014-10-27 22:18:37 +00:00
|
|
|
|
``field_name`` should be the name of a ``DateTimeField`` of your model.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
``kind`` should be either ``"year"``, ``"month"``, ``"day"``, ``"hour"``,
|
|
|
|
|
``"minute"`` or ``"second"``. Each ``datetime.datetime`` object in the result
|
|
|
|
|
list is "truncated" to the given ``type``.
|
|
|
|
|
|
|
|
|
|
``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
|
|
|
|
|
``'DESC'``. This specifies how to order the results.
|
|
|
|
|
|
|
|
|
|
``tzinfo`` defines the time zone to which datetimes are converted prior to
|
|
|
|
|
truncation. Indeed, a given datetime has different representations depending
|
|
|
|
|
on the time zone in use. This parameter must be a :class:`datetime.tzinfo`
|
|
|
|
|
object. If it's ``None``, Django uses the :ref:`current time zone
|
|
|
|
|
<default-current-time-zone>`. It has no effect when :setting:`USE_TZ` is
|
|
|
|
|
``False``.
|
|
|
|
|
|
|
|
|
|
.. _database-time-zone-definitions:
|
|
|
|
|
|
|
|
|
|
.. note::
|
2011-11-18 13:01:06 +00:00
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
This function performs time zone conversions directly in the database.
|
|
|
|
|
As a consequence, your database must be able to interpret the value of
|
|
|
|
|
``tzinfo.tzname(None)``. This translates into the following requirements:
|
|
|
|
|
|
|
|
|
|
- SQLite: install pytz_ — conversions are actually performed in Python.
|
|
|
|
|
- PostgreSQL: no requirements (see `Time Zones`_).
|
|
|
|
|
- Oracle: no requirements (see `Choosing a Time Zone File`_).
|
2013-05-08 10:57:35 +00:00
|
|
|
|
- MySQL: install pytz_ and load the time zone tables with
|
|
|
|
|
`mysql_tzinfo_to_sql`_.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
.. _pytz: http://pytz.sourceforge.net/
|
2013-03-17 10:45:45 +00:00
|
|
|
|
.. _Time Zones: http://www.postgresql.org/docs/current/static/datatype-datetime.html#DATATYPE-TIMEZONES
|
2015-09-15 20:01:31 +00:00
|
|
|
|
.. _Choosing a Time Zone File: http://docs.oracle.com/cd/E11882_01/server.112/e10729/ch4datetime.htm#NLSPG258
|
2014-08-02 14:27:01 +00:00
|
|
|
|
.. _mysql_tzinfo_to_sql: http://dev.mysql.com/doc/refman/5.6/en/mysql-tzinfo-to-sql.html
|
2011-11-18 13:01:06 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
none
|
|
|
|
|
~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: none()
|
|
|
|
|
|
2012-10-23 21:04:37 +00:00
|
|
|
|
Calling none() will create a queryset that never returns any objects and no
|
|
|
|
|
query will be executed when accessing the results. A qs.none() queryset
|
|
|
|
|
is an instance of ``EmptyQuerySet``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Examples::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.none()
|
|
|
|
|
[]
|
2012-10-23 21:04:37 +00:00
|
|
|
|
>>> from django.db.models.query import EmptyQuerySet
|
|
|
|
|
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
|
|
|
|
|
True
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
all
|
|
|
|
|
~~~
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
|
|
|
|
.. method:: all()
|
2008-09-11 00:24:02 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass). This
|
|
|
|
|
can be useful in situations where you might want to pass in either a model
|
|
|
|
|
manager or a ``QuerySet`` and do further filtering on the result. After calling
|
|
|
|
|
``all()`` on either object, you'll definitely have a ``QuerySet`` to work with.
|
2008-09-11 00:24:02 +00:00
|
|
|
|
|
2014-07-26 14:00:48 +00:00
|
|
|
|
When a ``QuerySet`` is :ref:`evaluated <when-querysets-are-evaluated>`, it
|
|
|
|
|
typically caches its results. If the data in the database might have changed
|
|
|
|
|
since a ``QuerySet`` was evaluated, you can get updated results for the same
|
|
|
|
|
query by calling ``all()`` on a previously evaluated ``QuerySet``.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
select_related
|
|
|
|
|
~~~~~~~~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-10-15 12:15:02 +00:00
|
|
|
|
.. method:: select_related(*fields)
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
2013-10-15 12:15:02 +00:00
|
|
|
|
Returns a ``QuerySet`` that will "follow" foreign-key relationships, selecting
|
|
|
|
|
additional related-object data when it executes its query. This is a
|
|
|
|
|
performance booster which results in a single more complex query but means
|
|
|
|
|
later use of foreign-key relationships won't require database queries.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
The following examples illustrate the difference between plain lookups and
|
|
|
|
|
``select_related()`` lookups. Here's standard lookup::
|
|
|
|
|
|
|
|
|
|
# Hits the database.
|
|
|
|
|
e = Entry.objects.get(id=5)
|
|
|
|
|
|
|
|
|
|
# Hits the database again to get the related Blog object.
|
|
|
|
|
b = e.blog
|
|
|
|
|
|
|
|
|
|
And here's ``select_related`` lookup::
|
|
|
|
|
|
|
|
|
|
# Hits the database.
|
2013-10-15 12:15:02 +00:00
|
|
|
|
e = Entry.objects.select_related('blog').get(id=5)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
# Doesn't hit the database, because e.blog has been prepopulated
|
|
|
|
|
# in the previous query.
|
|
|
|
|
b = e.blog
|
|
|
|
|
|
2014-10-31 19:38:46 +00:00
|
|
|
|
You can use ``select_related()`` with any queryset of objects::
|
|
|
|
|
|
|
|
|
|
from django.utils import timezone
|
|
|
|
|
|
|
|
|
|
# Find all the blogs with entries scheduled to be published in the future.
|
|
|
|
|
blogs = set()
|
|
|
|
|
|
|
|
|
|
for e in Entry.objects.filter(pub_date__gt=timezone.now()).select_related('blog'):
|
|
|
|
|
# Without select_related(), this would make a database query for each
|
|
|
|
|
# loop iteration in order to fetch the related blog for each entry.
|
|
|
|
|
blogs.add(e.blog)
|
|
|
|
|
|
|
|
|
|
The order of ``filter()`` and ``select_related()`` chaining isn't important.
|
|
|
|
|
These querysets are equivalent::
|
|
|
|
|
|
2015-02-04 06:01:59 +00:00
|
|
|
|
Entry.objects.filter(pub_date__gt=timezone.now()).select_related('blog')
|
|
|
|
|
Entry.objects.select_related('blog').filter(pub_date__gt=timezone.now())
|
2014-10-31 19:38:46 +00:00
|
|
|
|
|
2013-10-15 12:15:02 +00:00
|
|
|
|
You can follow foreign keys in a similar way to querying them. If you have the
|
2008-08-23 22:25:40 +00:00
|
|
|
|
following models::
|
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
from django.db import models
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
class City(models.Model):
|
|
|
|
|
# ...
|
2011-10-08 18:07:30 +00:00
|
|
|
|
pass
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
class Person(models.Model):
|
|
|
|
|
# ...
|
2015-07-22 14:43:21 +00:00
|
|
|
|
hometown = models.ForeignKey(
|
|
|
|
|
City,
|
|
|
|
|
on_delete=models.SET_NULL,
|
|
|
|
|
blank=True,
|
|
|
|
|
null=True,
|
|
|
|
|
)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
class Book(models.Model):
|
|
|
|
|
# ...
|
2015-07-22 14:43:21 +00:00
|
|
|
|
author = models.ForeignKey(Person, on_delete=models.CASCADE)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-10-31 19:38:46 +00:00
|
|
|
|
... then a call to ``Book.objects.select_related('author__hometown').get(id=4)``
|
2014-07-24 17:57:00 +00:00
|
|
|
|
will cache the related ``Person`` *and* the related ``City``::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-10-31 19:38:46 +00:00
|
|
|
|
b = Book.objects.select_related('author__hometown').get(id=4)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
p = b.author # Doesn't hit the database.
|
|
|
|
|
c = p.hometown # Doesn't hit the database.
|
|
|
|
|
|
|
|
|
|
b = Book.objects.get(id=4) # No select_related() in this example.
|
|
|
|
|
p = b.author # Hits the database.
|
|
|
|
|
c = p.hometown # Hits the database.
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
You can refer to any :class:`~django.db.models.ForeignKey` or
|
|
|
|
|
:class:`~django.db.models.OneToOneField` relation in the list of fields
|
2013-10-15 12:15:02 +00:00
|
|
|
|
passed to ``select_related()``.
|
2008-10-24 07:15:07 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
You can also refer to the reverse direction of a
|
2011-10-08 18:07:30 +00:00
|
|
|
|
:class:`~django.db.models.OneToOneField` in the list of fields passed to
|
2011-08-27 02:56:18 +00:00
|
|
|
|
``select_related`` — that is, you can traverse a
|
|
|
|
|
:class:`~django.db.models.OneToOneField` back to the object on which the field
|
|
|
|
|
is defined. Instead of specifying the field name, use the :attr:`related_name
|
|
|
|
|
<django.db.models.ForeignKey.related_name>` for the field on the related object.
|
2010-01-27 13:30:29 +00:00
|
|
|
|
|
2013-10-15 12:15:02 +00:00
|
|
|
|
There may be some situations where you wish to call ``select_related()`` with a
|
|
|
|
|
lot of related objects, or where you don't know all of the relations. In these
|
|
|
|
|
cases it is possible to call ``select_related()`` with no arguments. This will
|
|
|
|
|
follow all non-null foreign keys it can find - nullable foreign keys must be
|
|
|
|
|
specified. This is not recommended in most cases as it is likely to make the
|
|
|
|
|
underlying query more complex, and return more data, than is actually needed.
|
|
|
|
|
|
2013-05-30 15:05:42 +00:00
|
|
|
|
If you need to clear the list of related fields added by past calls of
|
|
|
|
|
``select_related`` on a ``QuerySet``, you can pass ``None`` as a parameter::
|
|
|
|
|
|
|
|
|
|
>>> without_relations = queryset.select_related(None)
|
|
|
|
|
|
2014-11-03 10:30:48 +00:00
|
|
|
|
Chaining ``select_related`` calls works in a similar way to other methods -
|
|
|
|
|
that is that ``select_related('foo', 'bar')`` is equivalent to
|
|
|
|
|
``select_related('foo').select_related('bar')``.
|
|
|
|
|
|
2011-10-05 23:14:52 +00:00
|
|
|
|
prefetch_related
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
.. method:: prefetch_related(*lookups)
|
|
|
|
|
|
|
|
|
|
Returns a ``QuerySet`` that will automatically retrieve, in a single batch,
|
2011-10-07 16:05:53 +00:00
|
|
|
|
related objects for each of the specified lookups.
|
|
|
|
|
|
|
|
|
|
This has a similar purpose to ``select_related``, in that both are designed to
|
|
|
|
|
stop the deluge of database queries that is caused by accessing related objects,
|
|
|
|
|
but the strategy is quite different.
|
|
|
|
|
|
2013-09-05 22:23:48 +00:00
|
|
|
|
``select_related`` works by creating an SQL join and including the fields of the
|
2013-08-02 13:26:19 +00:00
|
|
|
|
related object in the ``SELECT`` statement. For this reason, ``select_related``
|
|
|
|
|
gets the related objects in the same database query. However, to avoid the much
|
2011-10-07 16:05:53 +00:00
|
|
|
|
larger result set that would result from joining across a 'many' relationship,
|
|
|
|
|
``select_related`` is limited to single-valued relationships - foreign key and
|
|
|
|
|
one-to-one.
|
|
|
|
|
|
|
|
|
|
``prefetch_related``, on the other hand, does a separate lookup for each
|
|
|
|
|
relationship, and does the 'joining' in Python. This allows it to prefetch
|
|
|
|
|
many-to-many and many-to-one objects, which cannot be done using
|
|
|
|
|
``select_related``, in addition to the foreign key and one-to-one relationships
|
|
|
|
|
that are supported by ``select_related``. It also supports prefetching of
|
2014-01-22 06:43:33 +00:00
|
|
|
|
:class:`~django.contrib.contenttypes.fields.GenericRelation` and
|
|
|
|
|
:class:`~django.contrib.contenttypes.fields.GenericForeignKey`.
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
For example, suppose you have these models::
|
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
from django.db import models
|
|
|
|
|
|
2011-10-05 23:14:52 +00:00
|
|
|
|
class Topping(models.Model):
|
|
|
|
|
name = models.CharField(max_length=30)
|
|
|
|
|
|
|
|
|
|
class Pizza(models.Model):
|
|
|
|
|
name = models.CharField(max_length=50)
|
|
|
|
|
toppings = models.ManyToManyField(Topping)
|
|
|
|
|
|
2014-02-09 11:38:13 +00:00
|
|
|
|
def __str__(self): # __unicode__ on Python 2
|
2014-12-06 21:00:09 +00:00
|
|
|
|
return "%s (%s)" % (self.name, ", ".join(topping.name
|
|
|
|
|
for topping in self.toppings.all()))
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
and run::
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
>>> Pizza.objects.all()
|
2014-02-09 11:38:13 +00:00
|
|
|
|
["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2014-02-09 11:38:13 +00:00
|
|
|
|
The problem with this is that every time ``Pizza.__str__()`` asks for
|
2013-08-02 13:26:19 +00:00
|
|
|
|
``self.toppings.all()`` it has to query the database, so
|
|
|
|
|
``Pizza.objects.all()`` will run a query on the Toppings table for **every**
|
|
|
|
|
item in the Pizza ``QuerySet``.
|
|
|
|
|
|
|
|
|
|
We can reduce to just two queries using ``prefetch_related``:
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
>>> Pizza.objects.all().prefetch_related('toppings')
|
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
This implies a ``self.toppings.all()`` for each ``Pizza``; now each time
|
|
|
|
|
``self.toppings.all()`` is called, instead of having to go to the database for
|
|
|
|
|
the items, it will find them in a prefetched ``QuerySet`` cache that was
|
|
|
|
|
populated in a single query.
|
|
|
|
|
|
|
|
|
|
That is, all the relevant toppings will have been fetched in a single query,
|
|
|
|
|
and used to make ``QuerySets`` that have a pre-filled cache of the relevant
|
|
|
|
|
results; these ``QuerySets`` are then used in the ``self.toppings.all()`` calls.
|
|
|
|
|
|
|
|
|
|
The additional queries in ``prefetch_related()`` are executed after the
|
|
|
|
|
``QuerySet`` has begun to be evaluated and the primary query has been executed.
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
Note that the result cache of the primary ``QuerySet`` and all specified related
|
|
|
|
|
objects will then be fully loaded into memory. This changes the typical
|
|
|
|
|
behavior of ``QuerySets``, which normally try to avoid loading all objects into
|
|
|
|
|
memory before they are needed, even after a query has been executed in the
|
|
|
|
|
database.
|
|
|
|
|
|
|
|
|
|
.. note::
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
Remember that, as always with ``QuerySets``, any subsequent chained methods
|
|
|
|
|
which imply a different database query will ignore previously cached
|
|
|
|
|
results, and retrieve data using a fresh database query. So, if you write
|
|
|
|
|
the following:
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
>>> pizzas = Pizza.objects.prefetch_related('toppings')
|
|
|
|
|
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-08-02 13:26:19 +00:00
|
|
|
|
...then the fact that ``pizza.toppings.all()`` has been prefetched will not
|
|
|
|
|
help you. The ``prefetch_related('toppings')`` implied
|
|
|
|
|
``pizza.toppings.all()``, but ``pizza.toppings.filter()`` is a new and
|
|
|
|
|
different query. The prefetched cache can't help here; in fact it hurts
|
|
|
|
|
performance, since you have done a database query that you haven't used. So
|
|
|
|
|
use this feature with caution!
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
You can also use the normal join syntax to do related fields of related
|
|
|
|
|
fields. Suppose we have an additional model to the example above::
|
|
|
|
|
|
|
|
|
|
class Restaurant(models.Model):
|
|
|
|
|
pizzas = models.ManyToMany(Pizza, related_name='restaurants')
|
|
|
|
|
best_pizza = models.ForeignKey(Pizza, related_name='championed_by')
|
|
|
|
|
|
|
|
|
|
The following are all legal:
|
|
|
|
|
|
|
|
|
|
>>> Restaurant.objects.prefetch_related('pizzas__toppings')
|
|
|
|
|
|
|
|
|
|
This will prefetch all pizzas belonging to restaurants, and all toppings
|
|
|
|
|
belonging to those pizzas. This will result in a total of 3 database queries -
|
|
|
|
|
one for the restaurants, one for the pizzas, and one for the toppings.
|
|
|
|
|
|
2011-10-07 16:05:53 +00:00
|
|
|
|
>>> Restaurant.objects.prefetch_related('best_pizza__toppings')
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
This will fetch the best pizza and all the toppings for the best pizza for each
|
2011-10-07 16:05:53 +00:00
|
|
|
|
restaurant. This will be done in 3 database queries - one for the restaurants,
|
|
|
|
|
one for the 'best pizzas', and one for one for the toppings.
|
|
|
|
|
|
|
|
|
|
Of course, the ``best_pizza`` relationship could also be fetched using
|
|
|
|
|
``select_related`` to reduce the query count to 2:
|
|
|
|
|
|
|
|
|
|
>>> Restaurant.objects.select_related('best_pizza').prefetch_related('best_pizza__toppings')
|
|
|
|
|
|
|
|
|
|
Since the prefetch is executed after the main query (which includes the joins
|
|
|
|
|
needed by ``select_related``), it is able to detect that the ``best_pizza``
|
|
|
|
|
objects have already been fetched, and it will skip fetching them again.
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2011-10-07 16:05:53 +00:00
|
|
|
|
Chaining ``prefetch_related`` calls will accumulate the lookups that are
|
2013-08-15 11:14:10 +00:00
|
|
|
|
prefetched. To clear any ``prefetch_related`` behavior, pass ``None`` as a
|
2013-11-06 17:25:05 +00:00
|
|
|
|
parameter:
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
|
|
|
|
>>> non_prefetched = qs.prefetch_related(None)
|
|
|
|
|
|
2011-10-07 16:05:53 +00:00
|
|
|
|
One difference to note when using ``prefetch_related`` is that objects created
|
|
|
|
|
by a query can be shared between the different objects that they are related to
|
|
|
|
|
i.e. a single Python model instance can appear at more than one point in the
|
|
|
|
|
tree of objects that are returned. This will normally happen with foreign key
|
|
|
|
|
relationships. Typically this behavior will not be a problem, and will in fact
|
|
|
|
|
save both memory and CPU time.
|
|
|
|
|
|
|
|
|
|
While ``prefetch_related`` supports prefetching ``GenericForeignKey``
|
|
|
|
|
relationships, the number of queries will depend on the data. Since a
|
|
|
|
|
``GenericForeignKey`` can reference data in multiple tables, one query per table
|
|
|
|
|
referenced is needed, rather than one query for all the items. There could be
|
|
|
|
|
additional queries on the ``ContentType`` table if the relevant rows have not
|
|
|
|
|
already been fetched.
|
2011-10-05 23:14:52 +00:00
|
|
|
|
|
2013-09-05 22:23:48 +00:00
|
|
|
|
``prefetch_related`` in most cases will be implemented using an SQL query that
|
2013-08-02 13:26:19 +00:00
|
|
|
|
uses the 'IN' operator. This means that for a large ``QuerySet`` a large 'IN' clause
|
2011-11-24 17:18:56 +00:00
|
|
|
|
could be generated, which, depending on the database, might have performance
|
|
|
|
|
problems of its own when it comes to parsing or executing the SQL query. Always
|
|
|
|
|
profile for your use case!
|
|
|
|
|
|
2012-02-28 19:34:04 +00:00
|
|
|
|
Note that if you use ``iterator()`` to run the query, ``prefetch_related()``
|
|
|
|
|
calls will be ignored since these two optimizations do not make sense together.
|
|
|
|
|
|
2013-11-06 17:25:05 +00:00
|
|
|
|
You can use the :class:`~django.db.models.Prefetch` object to further control
|
|
|
|
|
the prefetch operation.
|
|
|
|
|
|
|
|
|
|
In its simplest form ``Prefetch`` is equivalent to the traditional string based
|
|
|
|
|
lookups:
|
|
|
|
|
|
|
|
|
|
>>> Restaurant.objects.prefetch_related(Prefetch('pizzas__toppings'))
|
|
|
|
|
|
|
|
|
|
You can provide a custom queryset with the optional ``queryset`` argument.
|
|
|
|
|
This can be used to change the default ordering of the queryset:
|
|
|
|
|
|
|
|
|
|
>>> Restaurant.objects.prefetch_related(
|
|
|
|
|
... Prefetch('pizzas__toppings', queryset=Toppings.objects.order_by('name')))
|
|
|
|
|
|
|
|
|
|
Or to call :meth:`~django.db.models.query.QuerySet.select_related()` when
|
|
|
|
|
applicable to reduce the number of queries even further:
|
|
|
|
|
|
|
|
|
|
>>> Pizza.objects.prefetch_related(
|
|
|
|
|
... Prefetch('restaurants', queryset=Restaurant.objects.select_related('best_pizza')))
|
|
|
|
|
|
|
|
|
|
You can also assign the prefetched result to a custom attribute with the optional
|
|
|
|
|
``to_attr`` argument. The result will be stored directly in a list.
|
|
|
|
|
|
|
|
|
|
This allows prefetching the same relation multiple times with a different
|
|
|
|
|
``QuerySet``; for instance:
|
|
|
|
|
|
|
|
|
|
>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
|
|
|
|
|
>>> Restaurant.objects.prefetch_related(
|
2013-11-26 19:49:46 +00:00
|
|
|
|
... Prefetch('pizzas', to_attr='menu'),
|
2013-11-23 22:48:34 +00:00
|
|
|
|
... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'))
|
2013-11-06 17:25:05 +00:00
|
|
|
|
|
|
|
|
|
Lookups created with custom ``to_attr`` can still be traversed as usual by other
|
|
|
|
|
lookups:
|
|
|
|
|
|
|
|
|
|
>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
|
|
|
|
|
>>> Restaurant.objects.prefetch_related(
|
2013-11-23 22:48:34 +00:00
|
|
|
|
... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'),
|
2013-11-06 17:25:05 +00:00
|
|
|
|
... 'vegetarian_menu__toppings')
|
|
|
|
|
|
|
|
|
|
Using ``to_attr`` is recommended when filtering down the prefetch result as it is
|
|
|
|
|
less ambiguous than storing a filtered result in the related manager's cache:
|
|
|
|
|
|
|
|
|
|
>>> queryset = Pizza.objects.filter(vegetarian=True)
|
|
|
|
|
>>>
|
|
|
|
|
>>> # Recommended:
|
|
|
|
|
>>> restaurants = Restaurant.objects.prefetch_related(
|
2014-03-21 06:30:10 +00:00
|
|
|
|
... Prefetch('pizzas', queryset=queryset, to_attr='vegetarian_pizzas'))
|
2013-11-06 17:25:05 +00:00
|
|
|
|
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
|
|
|
|
|
>>>
|
|
|
|
|
>>> # Not recommended:
|
|
|
|
|
>>> restaurants = Restaurant.objects.prefetch_related(
|
|
|
|
|
... Prefetch('pizzas', queryset=queryset))
|
|
|
|
|
>>> vegetarian_pizzas = restaurants[0].pizzas.all()
|
|
|
|
|
|
2014-01-16 18:24:39 +00:00
|
|
|
|
Custom prefetching also works with single related relations like
|
|
|
|
|
forward ``ForeignKey`` or ``OneToOneField``. Generally you'll want to use
|
|
|
|
|
:meth:`select_related()` for these relations, but there are a number of cases
|
|
|
|
|
where prefetching with a custom ``QuerySet`` is useful:
|
|
|
|
|
|
|
|
|
|
* You want to use a ``QuerySet`` that performs further prefetching
|
|
|
|
|
on related models.
|
|
|
|
|
|
|
|
|
|
* You want to prefetch only a subset of the related objects.
|
|
|
|
|
|
|
|
|
|
* You want to use performance optimization techniques like
|
|
|
|
|
:meth:`deferred fields <defer()>`:
|
|
|
|
|
|
|
|
|
|
>>> queryset = Pizza.objects.only('name')
|
|
|
|
|
>>>
|
|
|
|
|
>>> restaurants = Restaurant.objects.prefetch_related(
|
|
|
|
|
... Prefetch('best_pizza', queryset=queryset))
|
|
|
|
|
|
2013-11-06 17:25:05 +00:00
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
The ordering of lookups matters.
|
|
|
|
|
|
|
|
|
|
Take the following examples:
|
|
|
|
|
|
|
|
|
|
>>> prefetch_related('pizzas__toppings', 'pizzas')
|
|
|
|
|
|
|
|
|
|
This works even though it's unordered because ``'pizzas__toppings'``
|
|
|
|
|
already contains all the needed information, therefore the second argument
|
|
|
|
|
``'pizzas'`` is actually redundant.
|
|
|
|
|
|
|
|
|
|
>>> prefetch_related('pizzas__toppings', Prefetch('pizzas', queryset=Pizza.objects.all()))
|
|
|
|
|
|
|
|
|
|
This will raise a ``ValueError`` because of the attempt to redefine the
|
|
|
|
|
queryset of a previously seen lookup. Note that an implicit queryset was
|
|
|
|
|
created to traverse ``'pizzas'`` as part of the ``'pizzas__toppings'``
|
|
|
|
|
lookup.
|
|
|
|
|
|
|
|
|
|
>>> prefetch_related('pizza_list__toppings', Prefetch('pizzas', to_attr='pizza_list'))
|
|
|
|
|
|
|
|
|
|
This will trigger an ``AttributeError`` because ``'pizza_list'`` doesn't exist yet
|
|
|
|
|
when ``'pizza_list__toppings'`` is being processed.
|
|
|
|
|
|
|
|
|
|
This consideration is not limited to the use of ``Prefetch`` objects. Some
|
|
|
|
|
advanced techniques may require that the lookups be performed in a
|
|
|
|
|
specific order to avoid creating extra queries; therefore it's recommended
|
|
|
|
|
to always carefully order ``prefetch_related`` arguments.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
extra
|
|
|
|
|
~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Sometimes, the Django query syntax by itself can't easily express a complex
|
|
|
|
|
``WHERE`` clause. For these edge cases, Django provides the ``extra()``
|
2011-08-27 02:56:18 +00:00
|
|
|
|
``QuerySet`` modifier — a hook for injecting specific clauses into the SQL
|
2008-08-23 22:25:40 +00:00
|
|
|
|
generated by a ``QuerySet``.
|
|
|
|
|
|
2015-08-03 21:05:18 +00:00
|
|
|
|
.. admonition:: Use this method as a last resort
|
|
|
|
|
|
|
|
|
|
This is an old API that we aim to deprecate at some point in the future.
|
|
|
|
|
Use it only if you cannot express your query using other queryset methods.
|
|
|
|
|
If you do need to use it, please `file a ticket
|
|
|
|
|
<https://code.djangoproject.com/newticket>`_ using the `QuerySet.extra
|
|
|
|
|
keyword <https://code.djangoproject.com/query?status=assigned&status=new&keywords=~QuerySet.extra>`_
|
|
|
|
|
with your use case (please check the list of existing tickets first) so
|
|
|
|
|
that we can enhance the QuerySet API to allow removing ``extra()``. We are
|
|
|
|
|
no longer improving or fixing bugs for this method.
|
|
|
|
|
|
|
|
|
|
For example, this use of ``extra()``::
|
|
|
|
|
|
|
|
|
|
>>> qs.extra(
|
|
|
|
|
... select={'val': "select col from sometable where othercol = %s"},
|
|
|
|
|
... select_params=(someparam,),
|
|
|
|
|
... )
|
|
|
|
|
|
|
|
|
|
is equivalent to::
|
|
|
|
|
|
|
|
|
|
>>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))
|
|
|
|
|
|
|
|
|
|
The main benefit of using :class:`~django.db.models.expressions.RawSQL` is
|
|
|
|
|
that you can set ``output_field`` if needed. The main downside is that if
|
|
|
|
|
you refer to some table alias of the queryset in the raw SQL, then it is
|
|
|
|
|
possible that Django might change that alias (for example, when the
|
|
|
|
|
queryset is used as a subquery in yet another query).
|
|
|
|
|
|
2014-04-24 18:10:03 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
You should be very careful whenever you use ``extra()``. Every time you use
|
|
|
|
|
it, you should escape any parameters that the user can control by using
|
|
|
|
|
``params`` in order to protect against SQL injection attacks . Please
|
|
|
|
|
read more about :ref:`SQL injection protection <sql-injection-protection>`.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
By definition, these extra lookups may not be portable to different database
|
|
|
|
|
engines (because you're explicitly writing SQL code) and violate the DRY
|
|
|
|
|
principle, so you should avoid them if possible.
|
|
|
|
|
|
|
|
|
|
Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None
|
|
|
|
|
of the arguments is required, but you should use at least one of them.
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* ``select``
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
The ``select`` argument lets you put extra fields in the ``SELECT``
|
|
|
|
|
clause. It should be a dictionary mapping attribute names to SQL
|
|
|
|
|
clauses to use to calculate that attribute.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Example::
|
2010-12-04 20:41:35 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
As a result, each ``Entry`` object will have an extra attribute,
|
|
|
|
|
``is_recent``, a boolean representing whether the entry's ``pub_date``
|
|
|
|
|
is greater than Jan. 1, 2006.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Django inserts the given SQL snippet directly into the ``SELECT``
|
|
|
|
|
statement, so the resulting SQL of the above example would be something
|
|
|
|
|
like::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
|
|
|
|
|
FROM blog_entry;
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
The next example is more advanced; it does a subquery to give each
|
|
|
|
|
resulting ``Blog`` object an ``entry_count`` attribute, an integer count
|
|
|
|
|
of associated ``Entry`` objects::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Blog.objects.extra(
|
|
|
|
|
select={
|
|
|
|
|
'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
|
|
|
|
|
},
|
|
|
|
|
)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
In this particular case, we're exploiting the fact that the query will
|
|
|
|
|
already contain the ``blog_blog`` table in its ``FROM`` clause.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
The resulting SQL of the above example would be::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
|
|
|
|
|
FROM blog_blog;
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Note that the parentheses required by most database engines around
|
|
|
|
|
subqueries are not required in Django's ``select`` clauses. Also note
|
|
|
|
|
that some database backends, such as some MySQL versions, don't support
|
|
|
|
|
subqueries.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
In some rare cases, you might wish to pass parameters to the SQL
|
|
|
|
|
fragments in ``extra(select=...)``. For this purpose, use the
|
|
|
|
|
``select_params`` parameter. Since ``select_params`` is a sequence and
|
|
|
|
|
the ``select`` attribute is a dictionary, some care is required so that
|
|
|
|
|
the parameters are matched up correctly with the extra select pieces.
|
2013-08-03 05:41:15 +00:00
|
|
|
|
In this situation, you should use a :class:`collections.OrderedDict` for
|
|
|
|
|
the ``select`` value, not just a normal Python dictionary.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
This will work, for example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Blog.objects.extra(
|
2013-08-03 05:41:15 +00:00
|
|
|
|
select=OrderedDict([('a', '%s'), ('b', '%s')]),
|
2011-10-10 17:32:33 +00:00
|
|
|
|
select_params=('one', 'two'))
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-09-10 07:23:58 +00:00
|
|
|
|
If you need to use a literal ``%s`` inside your select string, use
|
|
|
|
|
the sequence ``%%s``.
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.8
|
|
|
|
|
|
|
|
|
|
Prior to 1.8, you were unable to escape a literal ``%s``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* ``where`` / ``tables``
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
You can define explicit SQL ``WHERE`` clauses — perhaps to perform
|
|
|
|
|
non-explicit joins — by using ``where``. You can manually add tables to
|
|
|
|
|
the SQL ``FROM`` clause by using ``tables``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
``where`` and ``tables`` both take a list of strings. All ``where``
|
|
|
|
|
parameters are "AND"ed to any other search criteria.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2012-04-09 00:43:08 +00:00
|
|
|
|
Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
...translates (roughly) into the following SQL::
|
2011-09-30 10:28:39 +00:00
|
|
|
|
|
2012-04-09 00:43:08 +00:00
|
|
|
|
SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Be careful when using the ``tables`` parameter if you're specifying
|
|
|
|
|
tables that are already used in the query. When you add extra tables
|
|
|
|
|
via the ``tables`` parameter, Django assumes you want that table
|
|
|
|
|
included an extra time, if it is already included. That creates a
|
|
|
|
|
problem, since the table name will then be given an alias. If a table
|
|
|
|
|
appears multiple times in an SQL statement, the second and subsequent
|
|
|
|
|
occurrences must use aliases so the database can tell them apart. If
|
|
|
|
|
you're referring to the extra table you added in the extra ``where``
|
|
|
|
|
parameter this is going to cause errors.
|
2011-09-30 10:28:39 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Normally you'll only be adding extra tables that don't already appear
|
|
|
|
|
in the query. However, if the case outlined above does occur, there are
|
|
|
|
|
a few solutions. First, see if you can get by without including the
|
|
|
|
|
extra table and use the one already in the query. If that isn't
|
|
|
|
|
possible, put your ``extra()`` call at the front of the queryset
|
|
|
|
|
construction so that your table is the first use of that table.
|
|
|
|
|
Finally, if all else fails, look at the query produced and rewrite your
|
|
|
|
|
``where`` addition to use the alias given to your extra table. The
|
|
|
|
|
alias will be the same each time you construct the queryset in the same
|
|
|
|
|
way, so you can rely upon the alias name to not change.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* ``order_by``
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
If you need to order the resulting queryset using some of the new
|
|
|
|
|
fields or tables you have included via ``extra()`` use the ``order_by``
|
|
|
|
|
parameter to ``extra()`` and pass in a sequence of strings. These
|
|
|
|
|
strings should either be model fields (as in the normal
|
|
|
|
|
:meth:`order_by()` method on querysets), of the form
|
|
|
|
|
``table_name.column_name`` or an alias for a column that you specified
|
|
|
|
|
in the ``select`` parameter to ``extra()``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
For example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
|
|
|
|
|
q = q.extra(order_by = ['-is_recent'])
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
This would sort all the items for which ``is_recent`` is true to the
|
|
|
|
|
front of the result set (``True`` sorts before ``False`` in a
|
|
|
|
|
descending ordering).
|
2011-09-30 10:28:39 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
This shows, by the way, that you can make multiple calls to ``extra()``
|
|
|
|
|
and it will behave as you expect (adding new constraints each time).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* ``params``
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
The ``where`` parameter described above may use standard Python
|
|
|
|
|
database string placeholders — ``'%s'`` to indicate parameters the
|
|
|
|
|
database engine should automatically quote. The ``params`` argument is
|
|
|
|
|
a list of any extra parameters to be substituted.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Always use ``params`` instead of embedding values directly into
|
|
|
|
|
``where`` because ``params`` will ensure values are quoted correctly
|
|
|
|
|
according to your particular backend. For example, quotes will be
|
|
|
|
|
escaped correctly.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Bad::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
Entry.objects.extra(where=["headline='Lennon'"])
|
|
|
|
|
|
|
|
|
|
Good::
|
|
|
|
|
|
|
|
|
|
Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-04-20 20:13:41 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
If you are performing queries on MySQL, note that MySQL's silent type coercion
|
|
|
|
|
may cause unexpected results when mixing types. If you query on a string
|
|
|
|
|
type column, but with an integer value, MySQL will coerce the types of all values
|
|
|
|
|
in the table to an integer before performing the comparison. For example, if your
|
|
|
|
|
table contains the values ``'abc'``, ``'def'`` and you query for ``WHERE mycolumn=0``,
|
|
|
|
|
both rows will match. To prevent this, perform the correct typecasting
|
|
|
|
|
before using the value in a query.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
defer
|
|
|
|
|
~~~~~
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: defer(*fields)
|
|
|
|
|
|
2009-03-19 09:06:04 +00:00
|
|
|
|
In some complex data-modeling situations, your models might contain a lot of
|
|
|
|
|
fields, some of which could contain a lot of data (for example, text fields),
|
|
|
|
|
or require expensive processing to convert them to Python objects. If you are
|
2012-09-15 21:24:01 +00:00
|
|
|
|
using the results of a queryset in some situation where you don't know
|
2011-08-27 02:56:18 +00:00
|
|
|
|
if you need those particular fields when you initially fetch the data, you can
|
|
|
|
|
tell Django not to retrieve them from the database.
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
This is done by passing the names of the fields to not load to ``defer()``::
|
|
|
|
|
|
2010-02-21 23:39:08 +00:00
|
|
|
|
Entry.objects.defer("headline", "body")
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
A queryset that has deferred fields will still return model instances. Each
|
|
|
|
|
deferred field will be retrieved from the database if you access that field
|
|
|
|
|
(one at a time, not all the deferred fields at once).
|
|
|
|
|
|
|
|
|
|
You can make multiple calls to ``defer()``. Each call adds new fields to the
|
|
|
|
|
deferred set::
|
|
|
|
|
|
2010-08-28 11:23:54 +00:00
|
|
|
|
# Defers both the body and headline fields.
|
2010-02-21 23:39:08 +00:00
|
|
|
|
Entry.objects.defer("body").filter(rating=5).defer("headline")
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
The order in which fields are added to the deferred set does not matter.
|
|
|
|
|
Calling ``defer()`` with a field name that has already been deferred is
|
|
|
|
|
harmless (the field will still be deferred).
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
You can defer loading of fields in related models (if the related models are
|
2011-08-27 02:56:18 +00:00
|
|
|
|
loading via :meth:`select_related()`) by using the standard double-underscore
|
2009-03-19 09:06:04 +00:00
|
|
|
|
notation to separate related fields::
|
|
|
|
|
|
2010-02-21 23:39:08 +00:00
|
|
|
|
Blog.objects.select_related().defer("entry__headline", "entry__body")
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
If you want to clear the set of deferred fields, pass ``None`` as a parameter
|
|
|
|
|
to ``defer()``::
|
|
|
|
|
|
|
|
|
|
# Load all fields immediately.
|
|
|
|
|
my_queryset.defer(None)
|
|
|
|
|
|
2013-08-19 12:29:32 +00:00
|
|
|
|
Some fields in a model won't be deferred, even if you ask for them. You can
|
|
|
|
|
never defer the loading of the primary key. If you are using
|
|
|
|
|
:meth:`select_related()` to retrieve related models, you shouldn't defer the
|
|
|
|
|
loading of the field that connects from the primary model to the related
|
|
|
|
|
one, doing so will result in an error.
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
The ``defer()`` method (and its cousin, :meth:`only()`, below) are only for
|
|
|
|
|
advanced use-cases. They provide an optimization for when you have analyzed
|
|
|
|
|
your queries closely and understand *exactly* what information you need and
|
|
|
|
|
have measured that the difference between returning the fields you need and
|
|
|
|
|
the full set of fields for the model will be significant.
|
2011-08-26 06:19:30 +00:00
|
|
|
|
|
|
|
|
|
Even if you think you are in the advanced use-case situation, **only use
|
|
|
|
|
defer() when you cannot, at queryset load time, determine if you will need
|
|
|
|
|
the extra fields or not**. If you are frequently loading and using a
|
|
|
|
|
particular subset of your data, the best choice you can make is to
|
|
|
|
|
normalize your models and put the non-loaded data into a separate model
|
|
|
|
|
(and database table). If the columns *must* stay in the one table for some
|
|
|
|
|
reason, create a model with ``Meta.managed = False`` (see the
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:attr:`managed attribute <django.db.models.Options.managed>` documentation)
|
|
|
|
|
containing just the fields you normally need to load and use that where you
|
|
|
|
|
might otherwise call ``defer()``. This makes your code more explicit to the
|
|
|
|
|
reader, is slightly faster and consumes a little less memory in the Python
|
|
|
|
|
process.
|
2011-08-26 06:19:30 +00:00
|
|
|
|
|
2015-04-22 03:42:50 +00:00
|
|
|
|
For example, both of these models use the same underlying database table::
|
|
|
|
|
|
|
|
|
|
class CommonlyUsedModel(models.Model):
|
|
|
|
|
f1 = models.CharField(max_length=10)
|
|
|
|
|
|
|
|
|
|
class Meta:
|
|
|
|
|
managed = False
|
|
|
|
|
db_table = 'app_largetable'
|
|
|
|
|
|
|
|
|
|
class ManagedModel(models.Model):
|
|
|
|
|
f1 = models.CharField(max_length=10)
|
|
|
|
|
f2 = models.CharField(max_length=10)
|
|
|
|
|
|
|
|
|
|
class Meta:
|
|
|
|
|
db_table = 'app_largetable'
|
|
|
|
|
|
|
|
|
|
# Two equivalent QuerySets:
|
|
|
|
|
CommonlyUsedModel.objects.all()
|
|
|
|
|
ManagedModel.objects.all().defer('f2')
|
|
|
|
|
|
|
|
|
|
If many fields need to be duplicated in the unmanaged model, it may be best
|
|
|
|
|
to create an abstract model with the shared fields and then have the
|
|
|
|
|
unmanaged and managed models inherit from the abstract model.
|
|
|
|
|
|
2012-08-12 19:17:54 +00:00
|
|
|
|
.. note::
|
|
|
|
|
|
2012-12-25 14:56:22 +00:00
|
|
|
|
When calling :meth:`~django.db.models.Model.save()` for instances with
|
|
|
|
|
deferred fields, only the loaded fields will be saved. See
|
|
|
|
|
:meth:`~django.db.models.Model.save()` for more details.
|
2012-08-12 19:17:54 +00:00
|
|
|
|
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
only
|
|
|
|
|
~~~~
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
|
|
|
|
.. method:: only(*fields)
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
The ``only()`` method is more or less the opposite of :meth:`defer()`. You call
|
|
|
|
|
it with the fields that should *not* be deferred when retrieving a model. If
|
|
|
|
|
you have a model where almost all the fields need to be deferred, using
|
|
|
|
|
``only()`` to specify the complementary set of fields can result in simpler
|
2009-03-19 09:06:04 +00:00
|
|
|
|
code.
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Suppose you have a model with fields ``name``, ``age`` and ``biography``. The
|
2009-03-19 09:06:04 +00:00
|
|
|
|
following two querysets are the same, in terms of deferred fields::
|
|
|
|
|
|
|
|
|
|
Person.objects.defer("age", "biography")
|
|
|
|
|
Person.objects.only("name")
|
|
|
|
|
|
|
|
|
|
Whenever you call ``only()`` it *replaces* the set of fields to load
|
|
|
|
|
immediately. The method's name is mnemonic: **only** those fields are loaded
|
|
|
|
|
immediately; the remainder are deferred. Thus, successive calls to ``only()``
|
|
|
|
|
result in only the final fields being considered::
|
|
|
|
|
|
|
|
|
|
# This will defer all fields except the headline.
|
2010-08-28 11:23:54 +00:00
|
|
|
|
Entry.objects.only("body", "rating").only("headline")
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
|
|
|
|
Since ``defer()`` acts incrementally (adding fields to the deferred list), you
|
|
|
|
|
can combine calls to ``only()`` and ``defer()`` and things will behave
|
|
|
|
|
logically::
|
|
|
|
|
|
|
|
|
|
# Final result is that everything except "headline" is deferred.
|
|
|
|
|
Entry.objects.only("headline", "body").defer("body")
|
|
|
|
|
|
|
|
|
|
# Final result loads headline and body immediately (only() replaces any
|
|
|
|
|
# existing set of fields).
|
|
|
|
|
Entry.objects.defer("body").only("headline", "body")
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
All of the cautions in the note for the :meth:`defer` documentation apply to
|
2011-08-26 06:19:30 +00:00
|
|
|
|
``only()`` as well. Use it cautiously and only after exhausting your other
|
2013-03-25 05:53:48 +00:00
|
|
|
|
options.
|
2011-08-26 06:19:30 +00:00
|
|
|
|
|
2013-08-19 12:29:32 +00:00
|
|
|
|
Using :meth:`only` and omitting a field requested using :meth:`select_related`
|
|
|
|
|
is an error as well.
|
2012-08-12 19:17:54 +00:00
|
|
|
|
|
2013-08-19 12:29:32 +00:00
|
|
|
|
.. note::
|
2013-03-25 05:53:48 +00:00
|
|
|
|
|
2013-08-19 12:29:32 +00:00
|
|
|
|
When calling :meth:`~django.db.models.Model.save()` for instances with
|
|
|
|
|
deferred fields, only the loaded fields will be saved. See
|
|
|
|
|
:meth:`~django.db.models.Model.save()` for more details.
|
2012-08-12 19:17:54 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
using
|
|
|
|
|
~~~~~
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
|
|
|
|
.. method:: using(alias)
|
2009-12-22 15:18:51 +00:00
|
|
|
|
|
|
|
|
|
This method is for controlling which database the ``QuerySet`` will be
|
|
|
|
|
evaluated against if you are using more than one database. The only argument
|
|
|
|
|
this method takes is the alias of a database, as defined in
|
|
|
|
|
:setting:`DATABASES`.
|
|
|
|
|
|
|
|
|
|
For example::
|
|
|
|
|
|
|
|
|
|
# queries the database with the 'default' alias.
|
|
|
|
|
>>> Entry.objects.all()
|
|
|
|
|
|
|
|
|
|
# queries the database with the 'backup' alias
|
|
|
|
|
>>> Entry.objects.using('backup')
|
|
|
|
|
|
2011-04-20 20:42:07 +00:00
|
|
|
|
select_for_update
|
|
|
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
.. method:: select_for_update(nowait=False)
|
|
|
|
|
|
|
|
|
|
Returns a queryset that will lock rows until the end of the transaction,
|
|
|
|
|
generating a ``SELECT ... FOR UPDATE`` SQL statement on supported databases.
|
|
|
|
|
|
|
|
|
|
For example::
|
|
|
|
|
|
|
|
|
|
entries = Entry.objects.select_for_update().filter(author=request.user)
|
|
|
|
|
|
|
|
|
|
All matched entries will be locked until the end of the transaction block,
|
|
|
|
|
meaning that other transactions will be prevented from changing or acquiring
|
|
|
|
|
locks on them.
|
|
|
|
|
|
|
|
|
|
Usually, if another transaction has already acquired a lock on one of the
|
|
|
|
|
selected rows, the query will block until the lock is released. If this is
|
2011-05-13 04:33:42 +00:00
|
|
|
|
not the behavior you want, call ``select_for_update(nowait=True)``. This will
|
2011-04-20 20:42:07 +00:00
|
|
|
|
make the call non-blocking. If a conflicting lock is already acquired by
|
2011-08-27 02:56:18 +00:00
|
|
|
|
another transaction, :exc:`~django.db.DatabaseError` will be raised when the
|
|
|
|
|
queryset is evaluated.
|
2011-04-20 20:42:07 +00:00
|
|
|
|
|
2015-08-05 14:08:56 +00:00
|
|
|
|
Currently, the ``postgresql``, ``oracle``, and ``mysql`` database
|
2011-08-27 02:56:18 +00:00
|
|
|
|
backends support ``select_for_update()``. However, MySQL has no support for the
|
|
|
|
|
``nowait`` argument. Obviously, users of external third-party backends should
|
|
|
|
|
check with their backend's documentation for specifics in those cases.
|
2011-04-20 20:42:07 +00:00
|
|
|
|
|
2014-07-27 08:12:39 +00:00
|
|
|
|
Passing ``nowait=True`` to ``select_for_update()`` using database backends that
|
2011-08-27 02:56:18 +00:00
|
|
|
|
do not support ``nowait``, such as MySQL, will cause a
|
|
|
|
|
:exc:`~django.db.DatabaseError` to be raised. This is in order to prevent code
|
|
|
|
|
unexpectedly blocking.
|
2011-04-20 20:42:07 +00:00
|
|
|
|
|
2015-05-31 18:15:45 +00:00
|
|
|
|
Evaluating a queryset with ``select_for_update()`` in autocommit mode on
|
|
|
|
|
backends which support ``SELECT ... FOR UPDATE`` is a
|
|
|
|
|
:exc:`~django.db.transaction.TransactionManagementError` error because the
|
2014-07-27 08:12:39 +00:00
|
|
|
|
rows are not locked in that case. If allowed, this would facilitate data
|
|
|
|
|
corruption and could easily be caused by calling code that expects to be run in
|
|
|
|
|
a transaction outside of one.
|
2014-03-30 17:03:35 +00:00
|
|
|
|
|
2014-07-27 08:12:39 +00:00
|
|
|
|
Using ``select_for_update()`` on backends which do not support
|
2011-04-20 20:42:07 +00:00
|
|
|
|
``SELECT ... FOR UPDATE`` (such as SQLite) will have no effect.
|
2015-05-31 18:15:45 +00:00
|
|
|
|
``SELECT ... FOR UPDATE`` will not be added to the query, and an error isn't
|
|
|
|
|
raised if ``select_for_update()`` is used in autocommit mode.
|
2009-03-19 09:06:04 +00:00
|
|
|
|
|
2014-07-27 08:12:39 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Although ``select_for_update()`` normally fails in autocommit mode, since
|
|
|
|
|
:class:`~django.test.TestCase` automatically wraps each test in a
|
|
|
|
|
transaction, calling ``select_for_update()`` in a ``TestCase`` even outside
|
|
|
|
|
an :func:`~django.db.transaction.atomic()` block will (perhaps unexpectedly)
|
|
|
|
|
pass without raising a ``TransactionManagementError``. To properly test
|
|
|
|
|
``select_for_update()`` you should use
|
|
|
|
|
:class:`~django.test.TransactionTestCase`.
|
|
|
|
|
|
2013-07-29 09:47:49 +00:00
|
|
|
|
raw
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
.. method:: raw(raw_query, params=None, translations=None)
|
|
|
|
|
|
|
|
|
|
Takes a raw SQL query, executes it, and returns a
|
|
|
|
|
``django.db.models.query.RawQuerySet`` instance. This ``RawQuerySet`` instance
|
2013-08-02 13:26:19 +00:00
|
|
|
|
can be iterated over just like an normal ``QuerySet`` to provide object instances.
|
2013-07-29 09:47:49 +00:00
|
|
|
|
|
2014-04-24 18:10:03 +00:00
|
|
|
|
See the :doc:`/topics/db/sql` for more information.
|
2013-07-29 09:47:49 +00:00
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
``raw()`` always triggers a new query and doesn't account for previous
|
|
|
|
|
filtering. As such, it should generally be called from the ``Manager`` or
|
|
|
|
|
from a fresh ``QuerySet`` instance.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Methods that do not return QuerySets
|
|
|
|
|
------------------------------------
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
|
|
|
|
|
something *other than* a ``QuerySet``.
|
|
|
|
|
|
|
|
|
|
These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
|
|
|
|
|
they query the database each time they're called.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
get
|
|
|
|
|
~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: get(**kwargs)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns the object matching the given lookup parameters, which should be in
|
|
|
|
|
the format described in `Field lookups`_.
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
``get()`` raises :exc:`~django.core.exceptions.MultipleObjectsReturned` if more
|
|
|
|
|
than one object was found. The
|
2012-12-25 14:56:22 +00:00
|
|
|
|
:exc:`~django.core.exceptions.MultipleObjectsReturned` exception is an
|
2011-08-27 02:56:18 +00:00
|
|
|
|
attribute of the model class.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-05-08 01:30:04 +00:00
|
|
|
|
``get()`` raises a :exc:`~django.db.models.Model.DoesNotExist` exception if an
|
|
|
|
|
object wasn't found for the given parameters. This exception is an attribute
|
|
|
|
|
of the model class. Example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Entry.objects.get(id='foo') # raises Entry.DoesNotExist
|
|
|
|
|
|
2015-05-08 01:30:04 +00:00
|
|
|
|
The :exc:`~django.db.models.Model.DoesNotExist` exception inherits from
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:exc:`django.core.exceptions.ObjectDoesNotExist`, so you can target multiple
|
2015-05-08 01:30:04 +00:00
|
|
|
|
:exc:`~django.db.models.Model.DoesNotExist` exceptions. Example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
from django.core.exceptions import ObjectDoesNotExist
|
|
|
|
|
try:
|
|
|
|
|
e = Entry.objects.get(id=3)
|
|
|
|
|
b = Blog.objects.get(id=1)
|
|
|
|
|
except ObjectDoesNotExist:
|
2012-09-08 19:15:10 +00:00
|
|
|
|
print("Either the entry or blog doesn't exist.")
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
create
|
|
|
|
|
~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: create(**kwargs)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
A convenience method for creating an object and saving it all in one step. Thus::
|
|
|
|
|
|
|
|
|
|
p = Person.objects.create(first_name="Bruce", last_name="Springsteen")
|
|
|
|
|
|
|
|
|
|
and::
|
|
|
|
|
|
|
|
|
|
p = Person(first_name="Bruce", last_name="Springsteen")
|
2008-08-28 17:18:05 +00:00
|
|
|
|
p.save(force_insert=True)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
are equivalent.
|
|
|
|
|
|
2008-08-28 17:18:05 +00:00
|
|
|
|
The :ref:`force_insert <ref-models-force-insert>` parameter is documented
|
|
|
|
|
elsewhere, but all it means is that a new object will always be created.
|
|
|
|
|
Normally you won't need to worry about this. However, if your model contains a
|
|
|
|
|
manual primary key value that you set and if that value already exists in the
|
2011-03-08 19:51:19 +00:00
|
|
|
|
database, a call to ``create()`` will fail with an
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:exc:`~django.db.IntegrityError` since primary keys must be unique. Be
|
|
|
|
|
prepared to handle the exception if you are using manual primary keys.
|
2008-08-28 17:18:05 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
get_or_create
|
|
|
|
|
~~~~~~~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-05-18 11:49:06 +00:00
|
|
|
|
.. method:: get_or_create(defaults=None, **kwargs)
|
2010-05-09 05:48:45 +00:00
|
|
|
|
|
2013-07-03 11:59:35 +00:00
|
|
|
|
A convenience method for looking up an object with the given ``kwargs`` (may be
|
2013-05-24 20:36:09 +00:00
|
|
|
|
empty if your model has defaults for all fields), creating one if necessary.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or
|
|
|
|
|
created object and ``created`` is a boolean specifying whether a new object was
|
|
|
|
|
created.
|
|
|
|
|
|
2013-07-03 11:59:35 +00:00
|
|
|
|
This is meant as a shortcut to boilerplatish code. For example::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
try:
|
|
|
|
|
obj = Person.objects.get(first_name='John', last_name='Lennon')
|
|
|
|
|
except Person.DoesNotExist:
|
|
|
|
|
obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))
|
|
|
|
|
obj.save()
|
|
|
|
|
|
|
|
|
|
This pattern gets quite unwieldy as the number of fields in a model goes up.
|
|
|
|
|
The above example can be rewritten using ``get_or_create()`` like so::
|
|
|
|
|
|
|
|
|
|
obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon',
|
|
|
|
|
defaults={'birthday': date(1940, 10, 9)})
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Any keyword arguments passed to ``get_or_create()`` — *except* an optional one
|
|
|
|
|
called ``defaults`` — will be used in a :meth:`get()` call. If an object is
|
2012-11-22 15:36:18 +00:00
|
|
|
|
found, ``get_or_create()`` returns a tuple of that object and ``False``. If
|
|
|
|
|
multiple objects are found, ``get_or_create`` raises
|
|
|
|
|
:exc:`~django.core.exceptions.MultipleObjectsReturned`. If an object is *not*
|
|
|
|
|
found, ``get_or_create()`` will instantiate and save a new object, returning a
|
|
|
|
|
tuple of the new object and ``True``. The new object will be created roughly
|
|
|
|
|
according to this algorithm::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-12-06 21:00:09 +00:00
|
|
|
|
params = {k: v for k, v in kwargs.items() if '__' not in k}
|
2008-08-23 22:25:40 +00:00
|
|
|
|
params.update(defaults)
|
|
|
|
|
obj = self.model(**params)
|
|
|
|
|
obj.save()
|
|
|
|
|
|
|
|
|
|
In English, that means start with any non-``'defaults'`` keyword argument that
|
|
|
|
|
doesn't contain a double underscore (which would indicate a non-exact lookup).
|
|
|
|
|
Then add the contents of ``defaults``, overriding any keys if necessary, and
|
2008-08-28 17:18:05 +00:00
|
|
|
|
use the result as the keyword arguments to the model class. As hinted at
|
|
|
|
|
above, this is a simplification of the algorithm that is used, but it contains
|
|
|
|
|
all the pertinent details. The internal implementation has some more
|
|
|
|
|
error-checking than this and handles some extra edge-conditions; if you're
|
|
|
|
|
interested, read the code.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
If you have a field named ``defaults`` and want to use it as an exact lookup in
|
|
|
|
|
``get_or_create()``, just use ``'defaults__exact'``, like so::
|
|
|
|
|
|
|
|
|
|
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
The ``get_or_create()`` method has similar error behavior to :meth:`create()`
|
|
|
|
|
when you're using manually specified primary keys. If an object needs to be
|
|
|
|
|
created and the key already exists in the database, an
|
|
|
|
|
:exc:`~django.db.IntegrityError` will be raised.
|
2008-08-28 17:18:05 +00:00
|
|
|
|
|
2013-07-03 11:59:35 +00:00
|
|
|
|
This method is atomic assuming correct usage, correct database configuration,
|
|
|
|
|
and correct behavior of the underlying database. However, if uniqueness is not
|
|
|
|
|
enforced at the database level for the ``kwargs`` used in a ``get_or_create``
|
|
|
|
|
call (see :attr:`~django.db.models.Field.unique` or
|
|
|
|
|
:attr:`~django.db.models.Options.unique_together`), this method is prone to a
|
|
|
|
|
race-condition which can result in multiple rows with the same parameters being
|
|
|
|
|
inserted simultaneously.
|
|
|
|
|
|
|
|
|
|
If you are using MySQL, be sure to use the ``READ COMMITTED`` isolation level
|
|
|
|
|
rather than ``REPEATABLE READ`` (the default), otherwise you may see cases
|
|
|
|
|
where ``get_or_create`` will raise an :exc:`~django.db.IntegrityError` but the
|
|
|
|
|
object won't appear in a subsequent :meth:`~django.db.models.query.QuerySet.get`
|
|
|
|
|
call.
|
|
|
|
|
|
2014-01-23 14:01:26 +00:00
|
|
|
|
Finally, a word on using ``get_or_create()`` in Django views. Please make sure
|
|
|
|
|
to use it only in ``POST`` requests unless you have a good reason not to.
|
|
|
|
|
``GET`` requests shouldn't have any effect on data. Instead, use ``POST``
|
|
|
|
|
whenever a request to a page has a side effect on your data. For more, see
|
|
|
|
|
`Safe methods`_ in the HTTP spec.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
|
|
|
|
|
|
2013-05-19 12:15:36 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
You can use ``get_or_create()`` through :class:`~django.db.models.ManyToManyField`
|
|
|
|
|
attributes and reverse relations. In that case you will restrict the queries
|
|
|
|
|
inside the context of that relation. That could lead you to some integrity
|
|
|
|
|
problems if you don't use it consistently.
|
|
|
|
|
|
|
|
|
|
Being the following models::
|
|
|
|
|
|
|
|
|
|
class Chapter(models.Model):
|
|
|
|
|
title = models.CharField(max_length=255, unique=True)
|
|
|
|
|
|
|
|
|
|
class Book(models.Model):
|
|
|
|
|
title = models.CharField(max_length=256)
|
|
|
|
|
chapters = models.ManyToManyField(Chapter)
|
|
|
|
|
|
|
|
|
|
You can use ``get_or_create()`` through Book's chapters field, but it only
|
|
|
|
|
fetches inside the context of that book::
|
|
|
|
|
|
|
|
|
|
>>> book = Book.objects.create(title="Ulysses")
|
|
|
|
|
>>> book.chapters.get_or_create(title="Telemachus")
|
|
|
|
|
(<Chapter: Telemachus>, True)
|
|
|
|
|
>>> book.chapters.get_or_create(title="Telemachus")
|
|
|
|
|
(<Chapter: Telemachus>, False)
|
|
|
|
|
>>> Chapter.objects.create(title="Chapter 1")
|
|
|
|
|
<Chapter: Chapter 1>
|
|
|
|
|
>>> book.chapters.get_or_create(title="Chapter 1")
|
|
|
|
|
# Raises IntegrityError
|
|
|
|
|
|
|
|
|
|
This is happening because it's trying to get or create "Chapter 1" through the
|
|
|
|
|
book "Ulysses", but it can't do any of them: the relation can't fetch that
|
|
|
|
|
chapter because it isn't related to that book, but it can't create it either
|
|
|
|
|
because ``title`` field should be unique.
|
|
|
|
|
|
2013-05-18 11:49:06 +00:00
|
|
|
|
update_or_create
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
.. method:: update_or_create(defaults=None, **kwargs)
|
|
|
|
|
|
|
|
|
|
A convenience method for updating an object with the given ``kwargs``, creating
|
|
|
|
|
a new one if necessary. The ``defaults`` is a dictionary of (field, value)
|
|
|
|
|
pairs used to update the object.
|
|
|
|
|
|
|
|
|
|
Returns a tuple of ``(object, created)``, where ``object`` is the created or
|
|
|
|
|
updated object and ``created`` is a boolean specifying whether a new object was
|
|
|
|
|
created.
|
|
|
|
|
|
|
|
|
|
The ``update_or_create`` method tries to fetch an object from database based on
|
|
|
|
|
the given ``kwargs``. If a match is found, it updates the fields passed in the
|
|
|
|
|
``defaults`` dictionary.
|
|
|
|
|
|
|
|
|
|
This is meant as a shortcut to boilerplatish code. For example::
|
|
|
|
|
|
|
|
|
|
try:
|
|
|
|
|
obj = Person.objects.get(first_name='John', last_name='Lennon')
|
|
|
|
|
for key, value in updated_values.iteritems():
|
|
|
|
|
setattr(obj, key, value)
|
|
|
|
|
obj.save()
|
|
|
|
|
except Person.DoesNotExist:
|
|
|
|
|
updated_values.update({'first_name': 'John', 'last_name': 'Lennon'})
|
|
|
|
|
obj = Person(**updated_values)
|
|
|
|
|
obj.save()
|
|
|
|
|
|
|
|
|
|
This pattern gets quite unwieldy as the number of fields in a model goes up.
|
|
|
|
|
The above example can be rewritten using ``update_or_create()`` like so::
|
|
|
|
|
|
|
|
|
|
obj, created = Person.objects.update_or_create(
|
|
|
|
|
first_name='John', last_name='Lennon', defaults=updated_values)
|
|
|
|
|
|
|
|
|
|
For detailed description how names passed in ``kwargs`` are resolved see
|
|
|
|
|
:meth:`get_or_create`.
|
|
|
|
|
|
|
|
|
|
As described above in :meth:`get_or_create`, this method is prone to a
|
|
|
|
|
race-condition which can result in multiple rows being inserted simultaneously
|
|
|
|
|
if uniqueness is not enforced at the database level.
|
2013-05-19 12:15:36 +00:00
|
|
|
|
|
2011-09-09 19:22:28 +00:00
|
|
|
|
bulk_create
|
|
|
|
|
~~~~~~~~~~~
|
|
|
|
|
|
2012-04-29 01:22:05 +00:00
|
|
|
|
.. method:: bulk_create(objs, batch_size=None)
|
2011-09-09 19:22:28 +00:00
|
|
|
|
|
|
|
|
|
This method inserts the provided list of objects into the database in an
|
|
|
|
|
efficient manner (generally only 1 query, no matter how many objects there
|
|
|
|
|
are)::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.bulk_create([
|
|
|
|
|
... Entry(headline="Django 1.0 Released"),
|
|
|
|
|
... Entry(headline="Django 1.1 Announced"),
|
|
|
|
|
... Entry(headline="Breaking: Django is awesome")
|
|
|
|
|
... ])
|
|
|
|
|
|
|
|
|
|
This has a number of caveats though:
|
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* The model's ``save()`` method will not be called, and the ``pre_save`` and
|
2011-10-11 18:23:08 +00:00
|
|
|
|
``post_save`` signals will not be sent.
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* It does not work with child models in a multi-table inheritance scenario.
|
|
|
|
|
* If the model's primary key is an :class:`~django.db.models.AutoField` it
|
2011-10-11 18:23:08 +00:00
|
|
|
|
does not retrieve and set the primary key attribute, as ``save()`` does.
|
2014-01-17 01:47:02 +00:00
|
|
|
|
* It does not work with many-to-many relationships.
|
2011-09-09 19:22:28 +00:00
|
|
|
|
|
2015-06-18 14:12:07 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Support for using ``bulk_create()`` with proxy models was added.
|
|
|
|
|
|
2012-04-29 01:22:05 +00:00
|
|
|
|
The ``batch_size`` parameter controls how many objects are created in single
|
|
|
|
|
query. The default is to create all objects in one batch, except for SQLite
|
2014-07-30 17:03:54 +00:00
|
|
|
|
where the default is such that at most 999 variables per query are used.
|
2012-03-04 17:34:22 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
count
|
|
|
|
|
~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: count()
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns an integer representing the number of objects in the database matching
|
2011-08-27 02:56:18 +00:00
|
|
|
|
the ``QuerySet``. The ``count()`` method never raises exceptions.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
# Returns the total number of entries in the database.
|
|
|
|
|
Entry.objects.count()
|
|
|
|
|
|
|
|
|
|
# Returns the number of entries whose headline contains 'Lennon'
|
|
|
|
|
Entry.objects.filter(headline__contains='Lennon').count()
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
A ``count()`` call performs a ``SELECT COUNT(*)`` behind the scenes, so you
|
|
|
|
|
should always use ``count()`` rather than loading all of the record into Python
|
2009-12-22 17:32:30 +00:00
|
|
|
|
objects and calling ``len()`` on the result (unless you need to load the
|
|
|
|
|
objects into memory anyway, in which case ``len()`` will be faster).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Depending on which database you're using (e.g. PostgreSQL vs. MySQL),
|
|
|
|
|
``count()`` may return a long integer instead of a normal Python integer. This
|
|
|
|
|
is an underlying implementation quirk that shouldn't pose any real-world
|
|
|
|
|
problems.
|
|
|
|
|
|
2015-01-20 15:20:02 +00:00
|
|
|
|
Note that if you want the number of items in a ``QuerySet`` and are also
|
|
|
|
|
retrieving model instances from it (for example, by iterating over it), it's
|
|
|
|
|
probably more efficient to use ``len(queryset)`` which won't cause an extra
|
|
|
|
|
database query like ``count()`` would.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
in_bulk
|
|
|
|
|
~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: in_bulk(id_list)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Takes a list of primary-key values and returns a dictionary mapping each
|
|
|
|
|
primary-key value to an instance of the object with the given ID.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
>>> Blog.objects.in_bulk([1])
|
2008-08-28 13:40:20 +00:00
|
|
|
|
{1: <Blog: Beatles Blog>}
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Blog.objects.in_bulk([1, 2])
|
2008-08-28 13:40:20 +00:00
|
|
|
|
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
|
2008-08-23 22:25:40 +00:00
|
|
|
|
>>> Blog.objects.in_bulk([])
|
|
|
|
|
{}
|
|
|
|
|
|
|
|
|
|
If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
iterator
|
|
|
|
|
~~~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: iterator()
|
|
|
|
|
|
2011-09-04 21:17:30 +00:00
|
|
|
|
Evaluates the ``QuerySet`` (by performing the query) and returns an iterator
|
|
|
|
|
(see :pep:`234`) over the results. A ``QuerySet`` typically caches its results
|
|
|
|
|
internally so that repeated evaluations do not result in additional queries. In
|
|
|
|
|
contrast, ``iterator()`` will read results directly, without doing any caching
|
|
|
|
|
at the ``QuerySet`` level (internally, the default iterator calls ``iterator()``
|
|
|
|
|
and caches the return value). For a ``QuerySet`` which returns a large number of
|
2013-05-14 10:40:33 +00:00
|
|
|
|
objects that you only need to access once, this can result in better
|
2011-08-27 02:56:18 +00:00
|
|
|
|
performance and a significant reduction in memory.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Note that using ``iterator()`` on a ``QuerySet`` which has already been
|
|
|
|
|
evaluated will force it to evaluate again, repeating the query.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2012-02-28 19:34:04 +00:00
|
|
|
|
Also, use of ``iterator()`` causes previous ``prefetch_related()`` calls to be
|
|
|
|
|
ignored since these two optimizations do not make sense together.
|
|
|
|
|
|
2012-10-20 19:21:19 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Some Python database drivers like ``psycopg2`` perform caching if using
|
|
|
|
|
client side cursors (instantiated with ``connection.cursor()`` and what
|
|
|
|
|
Django's ORM uses). Using ``iterator()`` does not affect caching at the
|
|
|
|
|
database driver level. To disable this caching, look at `server side
|
|
|
|
|
cursors`_.
|
|
|
|
|
|
|
|
|
|
.. _server side cursors: http://initd.org/psycopg/docs/usage.html#server-side-cursors
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
latest
|
|
|
|
|
~~~~~~
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: latest(field_name=None)
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Returns the latest object in the table, by date, using the ``field_name``
|
|
|
|
|
provided as the date field.
|
|
|
|
|
|
|
|
|
|
This example returns the latest ``Entry`` in the table, according to the
|
|
|
|
|
``pub_date`` field::
|
|
|
|
|
|
|
|
|
|
Entry.objects.latest('pub_date')
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
If your model's :ref:`Meta <meta-options>` specifies
|
|
|
|
|
:attr:`~django.db.models.Options.get_latest_by`, you can leave off the
|
2013-01-12 08:37:19 +00:00
|
|
|
|
``field_name`` argument to ``earliest()`` or ``latest()``. Django will use the
|
|
|
|
|
field specified in :attr:`~django.db.models.Options.get_latest_by` by default.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-01-12 08:37:19 +00:00
|
|
|
|
Like :meth:`get()`, ``earliest()`` and ``latest()`` raise
|
2015-05-08 01:30:04 +00:00
|
|
|
|
:exc:`~django.db.models.Model.DoesNotExist` if there is no object with the
|
2013-01-12 08:37:19 +00:00
|
|
|
|
given parameters.
|
|
|
|
|
|
|
|
|
|
Note that ``earliest()`` and ``latest()`` exist purely for convenience and
|
|
|
|
|
readability.
|
|
|
|
|
|
|
|
|
|
earliest
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
.. method:: earliest(field_name=None)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-01-12 08:37:19 +00:00
|
|
|
|
Works otherwise like :meth:`~django.db.models.query.QuerySet.latest` except
|
|
|
|
|
the direction is changed.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2013-05-21 15:35:12 +00:00
|
|
|
|
first
|
|
|
|
|
~~~~~
|
|
|
|
|
|
2014-03-24 15:42:56 +00:00
|
|
|
|
.. method:: first()
|
2013-05-21 15:35:12 +00:00
|
|
|
|
|
|
|
|
|
Returns the first object matched by the queryset, or ``None`` if there
|
|
|
|
|
is no matching object. If the ``QuerySet`` has no ordering defined, then the
|
|
|
|
|
queryset is automatically ordered by the primary key.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
p = Article.objects.order_by('title', 'pub_date').first()
|
|
|
|
|
|
|
|
|
|
Note that ``first()`` is a convenience method, the following code sample is
|
|
|
|
|
equivalent to the above example::
|
|
|
|
|
|
|
|
|
|
try:
|
|
|
|
|
p = Article.objects.order_by('title', 'pub_date')[0]
|
|
|
|
|
except IndexError:
|
|
|
|
|
p = None
|
|
|
|
|
|
|
|
|
|
last
|
|
|
|
|
~~~~
|
|
|
|
|
.. method:: last()
|
|
|
|
|
|
2013-05-21 16:18:35 +00:00
|
|
|
|
Works like :meth:`first()`, but returns the last object in the queryset.
|
2013-05-21 15:35:12 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
aggregate
|
|
|
|
|
~~~~~~~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: aggregate(*args, **kwargs)
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Returns a dictionary of aggregate values (averages, sums, etc) calculated over
|
|
|
|
|
the ``QuerySet``. Each argument to ``aggregate()`` specifies a value that will
|
|
|
|
|
be included in the dictionary that is returned.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
The aggregation functions that are provided by Django are described in
|
2013-12-25 13:13:18 +00:00
|
|
|
|
`Aggregation Functions`_ below. Since aggregates are also :doc:`query
|
|
|
|
|
expressions </ref/models/expressions>`, you may combine aggregates with other
|
|
|
|
|
aggregates or values to create complex aggregates.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Aggregates specified using keyword arguments will use the keyword as the name
|
|
|
|
|
for the annotation. Anonymous arguments will have a name generated for them
|
|
|
|
|
based upon the name of the aggregate function and the model field that is being
|
2013-12-25 13:13:18 +00:00
|
|
|
|
aggregated. Complex aggregates cannot use anonymous arguments and must specify
|
|
|
|
|
a keyword argument as an alias.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
For example, when you are working with blog entries, you may want to know the
|
|
|
|
|
number of authors that have contributed blog entries::
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
>>> from django.db.models import Count
|
2009-01-15 11:06:34 +00:00
|
|
|
|
>>> q = Blog.objects.aggregate(Count('entry'))
|
|
|
|
|
{'entry__count': 16}
|
|
|
|
|
|
|
|
|
|
By using a keyword argument to specify the aggregate function, you can
|
|
|
|
|
control the name of the aggregation value that is returned::
|
|
|
|
|
|
|
|
|
|
>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))
|
2009-02-17 10:17:29 +00:00
|
|
|
|
{'number_of_entries': 16}
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-08-19 19:27:44 +00:00
|
|
|
|
For an in-depth discussion of aggregation, see :doc:`the topic guide on
|
|
|
|
|
Aggregation </topics/db/aggregation>`.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
exists
|
|
|
|
|
~~~~~~
|
2009-10-24 00:28:39 +00:00
|
|
|
|
|
2010-05-09 05:48:45 +00:00
|
|
|
|
.. method:: exists()
|
|
|
|
|
|
2011-03-08 19:51:19 +00:00
|
|
|
|
Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
|
2009-10-24 00:28:39 +00:00
|
|
|
|
if not. This tries to perform the query in the simplest and fastest way
|
2012-09-08 15:19:49 +00:00
|
|
|
|
possible, but it *does* execute nearly the same query as a normal
|
|
|
|
|
:class:`.QuerySet` query.
|
|
|
|
|
|
|
|
|
|
:meth:`~.QuerySet.exists` is useful for searches relating to both
|
|
|
|
|
object membership in a :class:`.QuerySet` and to the existence of any objects in
|
|
|
|
|
a :class:`.QuerySet`, particularly in the context of a large :class:`.QuerySet`.
|
|
|
|
|
|
|
|
|
|
The most efficient method of finding whether a model with a unique field
|
|
|
|
|
(e.g. ``primary_key``) is a member of a :class:`.QuerySet` is::
|
|
|
|
|
|
|
|
|
|
entry = Entry.objects.get(pk=123)
|
2013-03-08 14:15:23 +00:00
|
|
|
|
if some_queryset.filter(pk=entry.pk).exists():
|
2012-09-08 19:15:10 +00:00
|
|
|
|
print("Entry contained in queryset")
|
2012-09-08 15:19:49 +00:00
|
|
|
|
|
|
|
|
|
Which will be faster than the following which requires evaluating and iterating
|
|
|
|
|
through the entire queryset::
|
|
|
|
|
|
2013-03-08 14:15:23 +00:00
|
|
|
|
if entry in some_queryset:
|
2012-09-08 19:15:10 +00:00
|
|
|
|
print("Entry contained in QuerySet")
|
2012-09-08 15:19:49 +00:00
|
|
|
|
|
|
|
|
|
And to find whether a queryset contains any items::
|
|
|
|
|
|
2013-03-08 14:15:23 +00:00
|
|
|
|
if some_queryset.exists():
|
|
|
|
|
print("There is at least one object in some_queryset")
|
2012-09-08 15:19:49 +00:00
|
|
|
|
|
|
|
|
|
Which will be faster than::
|
|
|
|
|
|
2013-03-08 14:15:23 +00:00
|
|
|
|
if some_queryset:
|
|
|
|
|
print("There is at least one object in some_queryset")
|
2012-09-08 15:19:49 +00:00
|
|
|
|
|
|
|
|
|
... but not by a large degree (hence needing a large queryset for efficiency
|
|
|
|
|
gains).
|
|
|
|
|
|
2013-03-08 14:15:23 +00:00
|
|
|
|
Additionally, if a ``some_queryset`` has not yet been evaluated, but you know
|
|
|
|
|
that it will be at some point, then using ``some_queryset.exists()`` will do
|
2011-08-27 02:56:18 +00:00
|
|
|
|
more overall work (one query for the existence check plus an extra one to later
|
2013-03-08 14:15:23 +00:00
|
|
|
|
retrieve the results) than simply using ``bool(some_queryset)``, which
|
2011-08-27 02:56:18 +00:00
|
|
|
|
retrieves the results and then checks if any were returned.
|
2009-10-24 00:28:39 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
update
|
|
|
|
|
~~~~~~
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
|
|
|
|
.. method:: update(**kwargs)
|
|
|
|
|
|
|
|
|
|
Performs an SQL update query for the specified fields, and returns
|
2012-10-06 11:02:11 +00:00
|
|
|
|
the number of rows matched (which may not be equal to the number of rows
|
|
|
|
|
updated if some rows already have the new value).
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
2011-07-05 20:09:00 +00:00
|
|
|
|
For example, to turn comments off for all blog entries published in 2010,
|
|
|
|
|
you could do this::
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
2011-07-05 20:09:00 +00:00
|
|
|
|
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
|
|
|
|
|
|
|
|
|
|
(This assumes your ``Entry`` model has fields ``pub_date`` and ``comments_on``.)
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
You can update multiple fields — there's no limit on how many. For example,
|
2011-07-05 20:09:00 +00:00
|
|
|
|
here we update the ``comments_on`` and ``headline`` fields::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')
|
|
|
|
|
|
|
|
|
|
The ``update()`` method is applied instantly, and the only restriction on the
|
|
|
|
|
:class:`.QuerySet` that is updated is that it can only update columns in the
|
|
|
|
|
model's main table, not on related models. You can't do this, for example::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.update(blog__name='foo') # Won't work!
|
|
|
|
|
|
|
|
|
|
Filtering based on related fields is still possible, though::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.filter(blog__id=1).update(comments_on=True)
|
|
|
|
|
|
|
|
|
|
You cannot call ``update()`` on a :class:`.QuerySet` that has had a slice taken
|
|
|
|
|
or can otherwise no longer be filtered.
|
|
|
|
|
|
|
|
|
|
The ``update()`` method returns the number of affected rows::
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.filter(id=64).update(comments_on=True)
|
|
|
|
|
1
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)
|
|
|
|
|
0
|
|
|
|
|
|
|
|
|
|
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
|
|
|
|
|
132
|
|
|
|
|
|
|
|
|
|
If you're just updating a record and don't need to do anything with the model
|
2011-08-27 02:56:18 +00:00
|
|
|
|
object, the most efficient approach is to call ``update()``, rather than
|
|
|
|
|
loading the model object into memory. For example, instead of doing this::
|
2011-07-05 20:09:00 +00:00
|
|
|
|
|
|
|
|
|
e = Entry.objects.get(id=10)
|
|
|
|
|
e.comments_on = False
|
|
|
|
|
e.save()
|
|
|
|
|
|
|
|
|
|
...do this::
|
|
|
|
|
|
2011-07-06 00:21:32 +00:00
|
|
|
|
Entry.objects.filter(id=10).update(comments_on=False)
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Using ``update()`` also prevents a race condition wherein something might
|
|
|
|
|
change in your database in the short period of time between loading the object
|
|
|
|
|
and calling ``save()``.
|
2011-07-05 20:16:08 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Finally, realize that ``update()`` does an update at the SQL level and, thus,
|
|
|
|
|
does not call any ``save()`` methods on your models, nor does it emit the
|
|
|
|
|
:attr:`~django.db.models.signals.pre_save` or
|
|
|
|
|
:attr:`~django.db.models.signals.post_save` signals (which are a consequence of
|
2012-12-25 08:40:08 +00:00
|
|
|
|
calling :meth:`Model.save() <django.db.models.Model.save>`). If you want to
|
2011-08-27 02:56:18 +00:00
|
|
|
|
update a bunch of records for a model that has a custom
|
2012-10-05 15:32:28 +00:00
|
|
|
|
:meth:`~django.db.models.Model.save()` method, loop over them and call
|
2011-08-27 02:56:18 +00:00
|
|
|
|
:meth:`~django.db.models.Model.save()`, like this::
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
2011-07-05 20:09:00 +00:00
|
|
|
|
for e in Entry.objects.filter(pub_date__year=2010):
|
|
|
|
|
e.comments_on = False
|
|
|
|
|
e.save()
|
2010-10-09 10:00:13 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
delete
|
|
|
|
|
~~~~~~
|
2010-11-09 16:33:48 +00:00
|
|
|
|
|
|
|
|
|
.. method:: delete()
|
|
|
|
|
|
2015-03-07 08:56:25 +00:00
|
|
|
|
Performs an SQL delete query on all rows in the :class:`.QuerySet` and
|
|
|
|
|
returns the number of objects deleted and a dictionary with the number of
|
|
|
|
|
deletions per object type.
|
|
|
|
|
|
|
|
|
|
The ``delete()`` is applied instantly. You cannot call ``delete()`` on a
|
2011-03-08 19:51:19 +00:00
|
|
|
|
:class:`.QuerySet` that has had a slice taken or can otherwise no longer be
|
2010-11-09 16:33:48 +00:00
|
|
|
|
filtered.
|
|
|
|
|
|
|
|
|
|
For example, to delete all the entries in a particular blog::
|
|
|
|
|
|
|
|
|
|
>>> b = Blog.objects.get(pk=1)
|
|
|
|
|
|
|
|
|
|
# Delete all the entries belonging to this Blog.
|
|
|
|
|
>>> Entry.objects.filter(blog=b).delete()
|
2015-03-07 08:56:25 +00:00
|
|
|
|
(4, {'weblog.Entry': 2, 'weblog.Entry_authors': 2})
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
The return value describing the number of objects deleted was added.
|
2010-11-09 16:33:48 +00:00
|
|
|
|
|
2010-11-09 16:46:42 +00:00
|
|
|
|
By default, Django's :class:`~django.db.models.ForeignKey` emulates the SQL
|
2011-08-27 02:56:18 +00:00
|
|
|
|
constraint ``ON DELETE CASCADE`` — in other words, any objects with foreign
|
2010-11-09 16:46:42 +00:00
|
|
|
|
keys pointing at the objects to be deleted will be deleted along with them.
|
|
|
|
|
For example::
|
2010-11-09 16:33:48 +00:00
|
|
|
|
|
2015-03-07 08:56:25 +00:00
|
|
|
|
>>> blogs = Blog.objects.all()
|
|
|
|
|
|
2010-11-09 16:33:48 +00:00
|
|
|
|
# This will delete all Blogs and all of their Entry objects.
|
2015-03-07 08:56:25 +00:00
|
|
|
|
>>> blogs.delete()
|
|
|
|
|
(5, {'weblog.Blog': 1, 'weblog.Entry': 2, 'weblog.Entry_authors': 2})
|
2010-11-09 16:33:48 +00:00
|
|
|
|
|
2012-09-19 20:39:14 +00:00
|
|
|
|
This cascade behavior is customizable via the
|
|
|
|
|
:attr:`~django.db.models.ForeignKey.on_delete` argument to the
|
|
|
|
|
:class:`~django.db.models.ForeignKey`.
|
2010-11-09 16:46:42 +00:00
|
|
|
|
|
2010-11-09 16:33:48 +00:00
|
|
|
|
The ``delete()`` method does a bulk delete and does not call any ``delete()``
|
|
|
|
|
methods on your models. It does, however, emit the
|
|
|
|
|
:data:`~django.db.models.signals.pre_delete` and
|
|
|
|
|
:data:`~django.db.models.signals.post_delete` signals for all deleted objects
|
|
|
|
|
(including cascaded deletions).
|
|
|
|
|
|
2012-09-20 15:51:30 +00:00
|
|
|
|
Django needs to fetch objects into memory to send signals and handle cascades.
|
|
|
|
|
However, if there are no cascades and no signals, then Django may take a
|
|
|
|
|
fast-path and delete objects without fetching into memory. For large
|
|
|
|
|
deletes this can result in significantly reduced memory usage. The amount of
|
|
|
|
|
executed queries can be reduced, too.
|
|
|
|
|
|
|
|
|
|
ForeignKeys which are set to :attr:`~django.db.models.ForeignKey.on_delete`
|
2013-08-19 12:29:32 +00:00
|
|
|
|
``DO_NOTHING`` do not prevent taking the fast-path in deletion.
|
2012-09-20 15:51:30 +00:00
|
|
|
|
|
|
|
|
|
Note that the queries generated in object deletion is an implementation
|
|
|
|
|
detail subject to change.
|
|
|
|
|
|
2013-07-26 08:59:40 +00:00
|
|
|
|
as_manager
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
.. classmethod:: as_manager()
|
|
|
|
|
|
|
|
|
|
Class method that returns an instance of :class:`~django.db.models.Manager`
|
2013-08-05 16:23:26 +00:00
|
|
|
|
with a copy of the ``QuerySet``’s methods. See
|
2013-07-26 08:59:40 +00:00
|
|
|
|
:ref:`create-manager-with-queryset-methods` for more details.
|
|
|
|
|
|
2009-12-26 00:55:06 +00:00
|
|
|
|
.. _field-lookups:
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Field lookups
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're
|
2011-08-27 02:56:18 +00:00
|
|
|
|
specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`,
|
|
|
|
|
:meth:`exclude()` and :meth:`get()`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
For an introduction, see :ref:`models and database queries documentation
|
|
|
|
|
<field-lookups-intro>`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-01-18 09:09:43 +00:00
|
|
|
|
Django's inbuilt lookups are listed below. It is also possible to write
|
2014-06-11 15:09:10 +00:00
|
|
|
|
:doc:`custom lookups </howto/custom-lookups>` for model fields.
|
2014-01-18 09:09:43 +00:00
|
|
|
|
|
2014-02-15 15:26:22 +00:00
|
|
|
|
As a convenience when no lookup type is provided (like in
|
|
|
|
|
``Entry.objects.get(id=14)``) the lookup type is assumed to be :lookup:`exact`.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: exact
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
exact
|
|
|
|
|
~~~~~
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Exact match. If the value provided for comparison is ``None``, it will be
|
|
|
|
|
interpreted as an SQL ``NULL`` (see :lookup:`isnull` for more details).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Examples::
|
|
|
|
|
|
|
|
|
|
Entry.objects.get(id__exact=14)
|
|
|
|
|
Entry.objects.get(id__exact=None)
|
|
|
|
|
|
|
|
|
|
SQL equivalents::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE id = 14;
|
|
|
|
|
SELECT ... WHERE id IS NULL;
|
|
|
|
|
|
|
|
|
|
.. admonition:: MySQL comparisons
|
|
|
|
|
|
2008-09-10 03:57:52 +00:00
|
|
|
|
In MySQL, a database table's "collation" setting determines whether
|
|
|
|
|
``exact`` comparisons are case-sensitive. This is a database setting, *not*
|
|
|
|
|
a Django setting. It's possible to configure your MySQL tables to use
|
|
|
|
|
case-sensitive comparisons, but some trade-offs are involved. For more
|
|
|
|
|
information about this, see the :ref:`collation section <mysql-collation>`
|
2010-08-19 19:27:44 +00:00
|
|
|
|
in the :doc:`databases </ref/databases>` documentation.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: iexact
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
iexact
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
2015-01-26 20:39:52 +00:00
|
|
|
|
Case-insensitive exact match. If the value provided for comparison is ``None``,
|
|
|
|
|
it will be interpreted as an SQL ``NULL`` (see :lookup:`isnull` for more
|
|
|
|
|
details).
|
2013-12-03 09:24:45 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Blog.objects.get(name__iexact='beatles blog')
|
2013-12-03 09:24:45 +00:00
|
|
|
|
Blog.objects.get(name__iexact=None)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-07-30 17:03:54 +00:00
|
|
|
|
SQL equivalents::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
SELECT ... WHERE name ILIKE 'beatles blog';
|
2014-07-30 17:03:54 +00:00
|
|
|
|
SELECT ... WHERE name IS NULL;
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-07-30 17:03:54 +00:00
|
|
|
|
Note the first query will match ``'Beatles Blog'``, ``'beatles blog'``,
|
|
|
|
|
``'BeAtLes BLoG'``, etc.
|
2009-01-06 03:34:47 +00:00
|
|
|
|
|
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
When using the SQLite backend and Unicode (non-ASCII) strings, bear in
|
|
|
|
|
mind the :ref:`database note <sqlite-string-matching>` about string
|
|
|
|
|
comparisons. SQLite does not do case-insensitive matching for Unicode
|
|
|
|
|
strings.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: contains
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
contains
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-sensitive containment test.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.get(headline__contains='Lennon')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline LIKE '%Lennon%';
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Note this will match the headline ``'Lennon honored today'`` but not ``'lennon
|
|
|
|
|
honored today'``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2011-08-26 08:42:38 +00:00
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains``
|
|
|
|
|
acts like ``icontains`` for SQLite. See the :ref:`database note
|
|
|
|
|
<sqlite-string-matching>` for more information.
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: icontains
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
icontains
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-insensitive containment test.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.get(headline__icontains='Lennon')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline ILIKE '%Lennon%';
|
|
|
|
|
|
2009-01-06 03:34:47 +00:00
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
When using the SQLite backend and Unicode (non-ASCII) strings, bear in
|
|
|
|
|
mind the :ref:`database note <sqlite-string-matching>` about string
|
|
|
|
|
comparisons.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: in
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
in
|
|
|
|
|
~~
|
|
|
|
|
|
|
|
|
|
In a given list.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(id__in=[1, 3, 4])
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE id IN (1, 3, 4);
|
|
|
|
|
|
|
|
|
|
You can also use a queryset to dynamically evaluate the list of values
|
2009-01-05 11:47:48 +00:00
|
|
|
|
instead of providing a list of literal values::
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2009-01-05 11:47:48 +00:00
|
|
|
|
inner_qs = Blog.objects.filter(name__contains='Cheddar')
|
|
|
|
|
entries = Entry.objects.filter(blog__in=inner_qs)
|
|
|
|
|
|
|
|
|
|
This queryset will be evaluated as subselect statement::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')
|
|
|
|
|
|
2015-01-30 07:26:13 +00:00
|
|
|
|
If you pass in a ``QuerySet`` resulting from ``values()`` or ``values_list()``
|
|
|
|
|
as the value to an ``__in`` lookup, you need to ensure you are only extracting
|
|
|
|
|
one field in the result. For example, this will work (filtering on the blog
|
|
|
|
|
names)::
|
2009-01-16 10:59:43 +00:00
|
|
|
|
|
|
|
|
|
inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
|
|
|
|
|
entries = Entry.objects.filter(blog__name__in=inner_qs)
|
|
|
|
|
|
|
|
|
|
This example will raise an exception, since the inner query is trying to
|
|
|
|
|
extract two field values, where only one is expected::
|
|
|
|
|
|
|
|
|
|
# Bad code! Will raise a TypeError.
|
|
|
|
|
inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')
|
|
|
|
|
entries = Entry.objects.filter(blog__name__in=inner_qs)
|
|
|
|
|
|
2013-09-26 23:35:53 +00:00
|
|
|
|
.. _nested-queries-performance:
|
|
|
|
|
|
2009-01-05 11:47:48 +00:00
|
|
|
|
.. admonition:: Performance considerations
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2009-01-05 11:47:48 +00:00
|
|
|
|
Be cautious about using nested queries and understand your database
|
|
|
|
|
server's performance characteristics (if in doubt, benchmark!). Some
|
|
|
|
|
database backends, most notably MySQL, don't optimize nested queries very
|
|
|
|
|
well. It is more efficient, in those cases, to extract a list of values
|
|
|
|
|
and then pass that into the second query. That is, execute two queries
|
|
|
|
|
instead of one::
|
|
|
|
|
|
|
|
|
|
values = Blog.objects.filter(
|
|
|
|
|
name__contains='Cheddar').values_list('pk', flat=True)
|
2010-01-10 17:25:44 +00:00
|
|
|
|
entries = Entry.objects.filter(blog__in=list(values))
|
|
|
|
|
|
|
|
|
|
Note the ``list()`` call around the Blog ``QuerySet`` to force execution of
|
2010-01-27 13:30:29 +00:00
|
|
|
|
the first query. Without it, a nested query would be executed, because
|
2010-01-10 17:25:44 +00:00
|
|
|
|
:ref:`querysets-are-lazy`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: gt
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
gt
|
|
|
|
|
~~
|
|
|
|
|
|
|
|
|
|
Greater than.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(id__gt=4)
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE id > 4;
|
|
|
|
|
|
2010-05-09 04:24:21 +00:00
|
|
|
|
.. fieldlookup:: gte
|
2010-03-20 05:04:31 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
gte
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Greater than or equal to.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: lt
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
lt
|
|
|
|
|
~~
|
|
|
|
|
|
|
|
|
|
Less than.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: lte
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
lte
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Less than or equal to.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: startswith
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
startswith
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-sensitive starts-with.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(headline__startswith='Will')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline LIKE 'Will%';
|
|
|
|
|
|
|
|
|
|
SQLite doesn't support case-sensitive ``LIKE`` statements; ``startswith`` acts
|
|
|
|
|
like ``istartswith`` for SQLite.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: istartswith
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
istartswith
|
|
|
|
|
~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-insensitive starts-with.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(headline__istartswith='will')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline ILIKE 'Will%';
|
|
|
|
|
|
2009-01-06 03:34:47 +00:00
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
When using the SQLite backend and Unicode (non-ASCII) strings, bear in
|
|
|
|
|
mind the :ref:`database note <sqlite-string-matching>` about string
|
|
|
|
|
comparisons.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: endswith
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
endswith
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-sensitive ends-with.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(headline__endswith='cats')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline LIKE '%cats';
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith``
|
|
|
|
|
acts like ``iendswith`` for SQLite. Refer to the :ref:`database note
|
|
|
|
|
<sqlite-string-matching>` documentation for more.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: iendswith
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
iendswith
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-insensitive ends-with.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(headline__iendswith='will')
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE headline ILIKE '%will'
|
|
|
|
|
|
2009-01-06 03:34:47 +00:00
|
|
|
|
.. admonition:: SQLite users
|
|
|
|
|
|
|
|
|
|
When using the SQLite backend and Unicode (non-ASCII) strings, bear in
|
|
|
|
|
mind the :ref:`database note <sqlite-string-matching>` about string
|
|
|
|
|
comparisons.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: range
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
range
|
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
|
|
Range test (inclusive).
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
2013-05-18 10:12:26 +00:00
|
|
|
|
import datetime
|
2008-08-23 22:25:40 +00:00
|
|
|
|
start_date = datetime.date(2005, 1, 1)
|
|
|
|
|
end_date = datetime.date(2005, 3, 31)
|
|
|
|
|
Entry.objects.filter(pub_date__range=(start_date, end_date))
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';
|
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
You can use ``range`` anywhere you can use ``BETWEEN`` in SQL — for dates,
|
2008-08-23 22:25:40 +00:00
|
|
|
|
numbers and even characters.
|
|
|
|
|
|
2012-09-08 15:00:04 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Filtering a ``DateTimeField`` with dates won't include items on the last
|
|
|
|
|
day, because the bounds are interpreted as "0am on the given date". If
|
|
|
|
|
``pub_date`` was a ``DateTimeField``, the above expression would be turned
|
|
|
|
|
into this SQL::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE pub_date BETWEEN '2005-01-01 00:00:00' and '2005-03-31 00:00:00';
|
|
|
|
|
|
|
|
|
|
Generally speaking, you can't mix dates and datetimes.
|
|
|
|
|
|
2015-03-07 21:20:29 +00:00
|
|
|
|
.. fieldlookup:: date
|
|
|
|
|
|
|
|
|
|
date
|
|
|
|
|
~~~~
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.9
|
|
|
|
|
|
|
|
|
|
For datetime fields, casts the value as date. Allows chaining additional field
|
|
|
|
|
lookups. Takes a date value.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))
|
|
|
|
|
Entry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))
|
|
|
|
|
|
|
|
|
|
(No equivalent SQL code fragment is included for this lookup because
|
|
|
|
|
implementation of the relevant query varies among different database engines.)
|
|
|
|
|
|
|
|
|
|
When :setting:`USE_TZ` is ``True``, fields are converted to the current time
|
|
|
|
|
zone before filtering.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: year
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
year
|
|
|
|
|
~~~~
|
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
For date and datetime fields, an exact year match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer year.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__year=2005)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Entry.objects.filter(pub_date__year__gte=2005)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
2012-09-08 15:00:04 +00:00
|
|
|
|
SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE pub_date >= '2005-01-01';
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
|
|
|
|
|
current time zone before filtering.
|
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: month
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
month
|
|
|
|
|
~~~~~
|
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
For date and datetime fields, an exact month match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer 1 (January) through 12 (December).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__month=12)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Entry.objects.filter(pub_date__month__gte=6)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
|
2013-09-12 13:27:35 +00:00
|
|
|
|
current time zone before filtering. This requires :ref:`time zone definitions
|
|
|
|
|
in the database <database-time-zone-definitions>`.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: day
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
day
|
|
|
|
|
~~~
|
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
For date and datetime fields, an exact day match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer day.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__day=3)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Entry.objects.filter(pub_date__day__gte=3)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
|
|
|
|
|
|
|
|
|
Note this will match any record with a pub_date on the third day of the month,
|
|
|
|
|
such as January 3, July 3, etc.
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
|
2013-09-12 13:27:35 +00:00
|
|
|
|
current time zone before filtering. This requires :ref:`time zone definitions
|
|
|
|
|
in the database <database-time-zone-definitions>`.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: week_day
|
|
|
|
|
|
2009-02-08 05:08:06 +00:00
|
|
|
|
week_day
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
For date and datetime fields, a 'day of the week' match. Allows chaining
|
|
|
|
|
additional field lookups.
|
2009-02-08 05:08:06 +00:00
|
|
|
|
|
2010-05-09 04:50:00 +00:00
|
|
|
|
Takes an integer value representing the day of week from 1 (Sunday) to 7
|
|
|
|
|
(Saturday).
|
|
|
|
|
|
2009-02-08 05:08:06 +00:00
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__week_day=2)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Entry.objects.filter(pub_date__week_day__gte=2)
|
2009-02-08 05:08:06 +00:00
|
|
|
|
|
2010-05-09 04:50:00 +00:00
|
|
|
|
(No equivalent SQL code fragment is included for this lookup because
|
|
|
|
|
implementation of the relevant query varies among different database engines.)
|
2009-02-08 05:08:06 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
Note this will match any record with a ``pub_date`` that falls on a Monday (day
|
|
|
|
|
2 of the week), regardless of the month or year in which it occurs. Week days
|
2009-02-08 05:08:06 +00:00
|
|
|
|
are indexed with day 1 being Sunday and day 7 being Saturday.
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
|
2013-09-12 13:27:35 +00:00
|
|
|
|
current time zone before filtering. This requires :ref:`time zone definitions
|
|
|
|
|
in the database <database-time-zone-definitions>`.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
.. fieldlookup:: hour
|
|
|
|
|
|
|
|
|
|
hour
|
|
|
|
|
~~~~
|
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime and time fields, an exact hour match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer between 0 and 23.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Event.objects.filter(timestamp__hour=23)
|
2015-05-22 19:16:26 +00:00
|
|
|
|
Event.objects.filter(time__hour=5)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Event.objects.filter(timestamp__hour__gte=12)
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';
|
2015-05-22 19:16:26 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('hour' FROM time) = '5';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime fields, when :setting:`USE_TZ` is ``True``, values are converted
|
|
|
|
|
to the current time zone before filtering.
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Added support for :class:`~django.db.models.TimeField` on SQLite (other
|
|
|
|
|
databases supported it as of 1.7).
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
.. fieldlookup:: minute
|
|
|
|
|
|
|
|
|
|
minute
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime and time fields, an exact minute match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer between 0 and 59.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Event.objects.filter(timestamp__minute=29)
|
2015-05-22 19:16:26 +00:00
|
|
|
|
Event.objects.filter(time__minute=46)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Event.objects.filter(timestamp__minute__gte=29)
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';
|
2015-05-22 19:16:26 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('minute' FROM time) = '46';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime fields, When :setting:`USE_TZ` is ``True``, values are converted
|
|
|
|
|
to the current time zone before filtering.
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Added support for :class:`~django.db.models.TimeField` on SQLite (other
|
|
|
|
|
databases supported it as of 1.7).
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2013-02-10 15:15:49 +00:00
|
|
|
|
.. fieldlookup:: second
|
|
|
|
|
|
|
|
|
|
second
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime and time fields, an exact second match. Allows chaining additional
|
|
|
|
|
field lookups. Takes an integer between 0 and 59.
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Event.objects.filter(timestamp__second=31)
|
2015-05-22 19:16:26 +00:00
|
|
|
|
Event.objects.filter(time__second=2)
|
2015-03-22 20:30:57 +00:00
|
|
|
|
Event.objects.filter(timestamp__second__gte=31)
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';
|
2015-05-22 19:16:26 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('second' FROM time) = '2';
|
2015-03-22 20:30:57 +00:00
|
|
|
|
SELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';
|
2013-02-10 15:15:49 +00:00
|
|
|
|
|
|
|
|
|
(The exact SQL syntax varies for each database engine.)
|
2011-11-18 13:01:06 +00:00
|
|
|
|
|
2015-05-22 19:16:26 +00:00
|
|
|
|
For datetime fields, when :setting:`USE_TZ` is ``True``, values are converted
|
|
|
|
|
to the current time zone before filtering.
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Added support for :class:`~django.db.models.TimeField` on SQLite (other
|
|
|
|
|
databases supported it as of 1.7).
|
2011-11-18 13:01:06 +00:00
|
|
|
|
|
2015-03-22 20:30:57 +00:00
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
Allowed chaining additional field lookups.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: isnull
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
isnull
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
|
|
Takes either ``True`` or ``False``, which correspond to SQL queries of
|
|
|
|
|
``IS NULL`` and ``IS NOT NULL``, respectively.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.filter(pub_date__isnull=True)
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE pub_date IS NULL;
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: search
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
search
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
|
|
A boolean full-text search, taking advantage of full-text indexing. This is
|
2011-08-27 02:56:18 +00:00
|
|
|
|
like :lookup:`contains` but is significantly faster due to full-text indexing.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2009-03-31 23:34:03 +00:00
|
|
|
|
Example::
|
2009-04-16 12:45:35 +00:00
|
|
|
|
|
2009-03-31 23:34:03 +00:00
|
|
|
|
Entry.objects.filter(headline__search="+Django -jazz Python")
|
|
|
|
|
|
|
|
|
|
SQL equivalent::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE);
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Note this is only available in MySQL and requires direct manipulation of the
|
2009-03-31 23:34:03 +00:00
|
|
|
|
database to add the full-text index. By default Django uses BOOLEAN MODE for
|
2011-08-27 02:56:18 +00:00
|
|
|
|
full text searches. See the `MySQL documentation`_ for additional details.
|
|
|
|
|
|
2014-08-02 14:27:01 +00:00
|
|
|
|
.. _MySQL documentation: http://dev.mysql.com/doc/refman/5.6/en/fulltext-boolean.html
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: regex
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
regex
|
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
|
|
Case-sensitive regular expression match.
|
|
|
|
|
|
2009-09-12 23:36:00 +00:00
|
|
|
|
The regular expression syntax is that of the database backend in use.
|
|
|
|
|
In the case of SQLite, which has no built in regular expression support,
|
|
|
|
|
this feature is provided by a (Python) user-defined REGEXP function, and
|
|
|
|
|
the regular expression syntax is therefore that of Python's ``re`` module.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.get(title__regex=r'^(An?|The) +')
|
|
|
|
|
|
|
|
|
|
SQL equivalents::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL
|
|
|
|
|
|
2015-09-15 20:01:31 +00:00
|
|
|
|
SELECT ... WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); -- Oracle
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite
|
|
|
|
|
|
|
|
|
|
Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the
|
|
|
|
|
regular expression syntax is recommended.
|
|
|
|
|
|
2010-03-20 05:04:31 +00:00
|
|
|
|
.. fieldlookup:: iregex
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
iregex
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
|
|
Case-insensitive regular expression match.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
Entry.objects.get(title__iregex=r'^(an?|the) +')
|
|
|
|
|
|
|
|
|
|
SQL equivalents::
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL
|
|
|
|
|
|
|
|
|
|
SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite
|
|
|
|
|
|
2009-01-15 11:06:34 +00:00
|
|
|
|
.. _aggregation-functions:
|
|
|
|
|
|
2011-01-03 13:29:17 +00:00
|
|
|
|
Aggregation functions
|
2009-01-15 11:06:34 +00:00
|
|
|
|
---------------------
|
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. currentmodule:: django.db.models
|
|
|
|
|
|
2009-01-15 11:06:34 +00:00
|
|
|
|
Django provides the following aggregation functions in the
|
2009-01-15 12:13:17 +00:00
|
|
|
|
``django.db.models`` module. For details on how to use these
|
2013-12-25 13:13:18 +00:00
|
|
|
|
aggregate functions, see :doc:`the topic guide on aggregation
|
|
|
|
|
</topics/db/aggregation>`. See the :class:`~django.db.models.Aggregate`
|
|
|
|
|
documentation to learn how to create your aggregates.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-01-11 05:57:54 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
SQLite can't handle aggregation on date/time fields out of the box.
|
|
|
|
|
This is because there are no native date/time fields in SQLite and Django
|
|
|
|
|
currently emulates these features using a text field. Attempts to use
|
|
|
|
|
aggregation on date/time fields in SQLite will raise
|
|
|
|
|
``NotImplementedError``.
|
|
|
|
|
|
2014-05-29 06:53:25 +00:00
|
|
|
|
.. admonition:: Note
|
|
|
|
|
|
2014-06-04 13:58:28 +00:00
|
|
|
|
Aggregation functions return ``None`` when used with an empty
|
|
|
|
|
``QuerySet``. For example, the ``Sum`` aggregation function returns ``None``
|
|
|
|
|
instead of ``0`` if the ``QuerySet`` contains no entries. An exception is
|
|
|
|
|
``Count``, which does return ``0`` if the ``QuerySet`` is empty.
|
2014-05-29 06:53:25 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
All aggregates have the following parameters in common:
|
|
|
|
|
|
|
|
|
|
``expression``
|
|
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
A string that references a field on the model, or a :doc:`query expression
|
|
|
|
|
</ref/models/expressions>`.
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
|
|
|
|
|
|
Aggregate functions are now able to reference multiple fields in complex
|
|
|
|
|
computations.
|
|
|
|
|
|
|
|
|
|
``output_field``
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
An optional argument that represents the :doc:`model field </ref/models/fields>`
|
|
|
|
|
of the return value
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
|
|
|
|
|
|
The ``output_field`` argument was added.
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
When combining multiple field types, Django can only determine the
|
|
|
|
|
``output_field`` if all fields are of the same type. Otherwise, you
|
|
|
|
|
must provide the ``output_field`` yourself.
|
|
|
|
|
|
|
|
|
|
``**extra``
|
|
|
|
|
~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Keyword arguments that can provide extra context for the SQL generated
|
|
|
|
|
by the aggregate.
|
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Avg
|
|
|
|
|
~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2015-04-24 00:13:24 +00:00
|
|
|
|
.. class:: Avg(expression, output_field=FloatField(), **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2015-04-24 00:13:24 +00:00
|
|
|
|
Returns the mean value of the given expression, which must be numeric
|
|
|
|
|
unless you specify a different ``output_field``.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__avg``
|
2015-04-24 00:13:24 +00:00
|
|
|
|
* Return type: ``float`` (or the type of whatever ``output_field`` is
|
|
|
|
|
specified)
|
|
|
|
|
|
|
|
|
|
.. versionchanged:: 1.9
|
|
|
|
|
|
|
|
|
|
The ``output_field`` parameter was added to allow aggregating over
|
|
|
|
|
non-numeric columns, such as ``DurationField``.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Count
|
|
|
|
|
~~~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: Count(expression, distinct=False, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Returns the number of objects that are related through the provided
|
|
|
|
|
expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__count``
|
2012-02-21 18:28:35 +00:00
|
|
|
|
* Return type: ``int``
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
Has one optional argument:
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. attribute:: distinct
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2012-02-21 18:28:35 +00:00
|
|
|
|
If ``distinct=True``, the count will only include unique instances.
|
|
|
|
|
This is the SQL equivalent of ``COUNT(DISTINCT <field>)``. The default
|
|
|
|
|
value is ``False``.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Max
|
|
|
|
|
~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: Max(expression, output_field=None, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Returns the maximum value of the given expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__max``
|
2013-12-25 13:13:18 +00:00
|
|
|
|
* Return type: same as input field, or ``output_field`` if supplied
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Min
|
|
|
|
|
~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: Min(expression, output_field=None, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Returns the minimum value of the given expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__min``
|
2013-12-25 13:13:18 +00:00
|
|
|
|
* Return type: same as input field, or ``output_field`` if supplied
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
StdDev
|
|
|
|
|
~~~~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: StdDev(expression, sample=False, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Returns the standard deviation of the data in the provided expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__stddev``
|
2012-02-21 18:28:35 +00:00
|
|
|
|
* Return type: ``float``
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
Has one optional argument:
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. attribute:: sample
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
By default, ``StdDev`` returns the population standard deviation. However,
|
|
|
|
|
if ``sample=True``, the return value will be the sample standard deviation.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. admonition:: SQLite
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2012-02-21 18:28:35 +00:00
|
|
|
|
SQLite doesn't provide ``StdDev`` out of the box. An implementation
|
|
|
|
|
is available as an extension module for SQLite. Consult the `SQlite
|
|
|
|
|
documentation`_ for instructions on obtaining and installing this
|
|
|
|
|
extension.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Sum
|
|
|
|
|
~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: Sum(expression, output_field=None, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Computes the sum of all values of the given expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__sum``
|
2013-12-25 13:13:18 +00:00
|
|
|
|
* Return type: same as input field, or ``output_field`` if supplied
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2010-11-28 18:15:40 +00:00
|
|
|
|
Variance
|
|
|
|
|
~~~~~~~~
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
.. class:: Variance(expression, sample=False, **extra)
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2013-12-25 13:13:18 +00:00
|
|
|
|
Returns the variance of the data in the provided expression.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-10-10 17:32:33 +00:00
|
|
|
|
* Default alias: ``<field>__variance``
|
2012-02-21 18:28:35 +00:00
|
|
|
|
* Return type: ``float``
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
Has one optional argument:
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. attribute:: sample
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
By default, ``Variance`` returns the population variance. However,
|
|
|
|
|
if ``sample=True``, the return value will be the sample variance.
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-02-16 01:56:53 +00:00
|
|
|
|
.. admonition:: SQLite
|
2009-01-15 11:06:34 +00:00
|
|
|
|
|
2011-08-27 02:56:18 +00:00
|
|
|
|
SQLite doesn't provide ``Variance`` out of the box. An implementation
|
|
|
|
|
is available as an extension module for SQLite. Consult the `SQlite
|
|
|
|
|
documentation`_ for instructions on obtaining and installing this
|
|
|
|
|
extension.
|
|
|
|
|
|
|
|
|
|
.. _SQLite documentation: http://www.sqlite.org/contrib
|
2015-01-11 20:02:33 +00:00
|
|
|
|
|
|
|
|
|
Query-related classes
|
|
|
|
|
=====================
|
|
|
|
|
|
|
|
|
|
This section provides reference material for query-related tools not documented
|
|
|
|
|
elsewhere.
|
|
|
|
|
|
|
|
|
|
``Q()`` objects
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. class:: Q
|
|
|
|
|
|
|
|
|
|
A ``Q()`` object, like an :class:`~django.db.models.F` object, encapsulates a
|
|
|
|
|
SQL expression in a Python object that can be used in database-related
|
|
|
|
|
operations.
|
|
|
|
|
|
|
|
|
|
In general, ``Q() objects`` make it possible to define and reuse conditions.
|
|
|
|
|
This permits the :ref:`construction of complex database queries
|
|
|
|
|
<complex-lookups-with-q>` using ``|`` (``OR``) and ``&`` (``AND``) operators;
|
|
|
|
|
in particular, it is not otherwise possible to use ``OR`` in ``QuerySets``.
|
|
|
|
|
|
|
|
|
|
``Prefetch()`` objects
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
.. class:: Prefetch(lookup, queryset=None, to_attr=None)
|
|
|
|
|
|
|
|
|
|
The ``Prefetch()`` object can be used to control the operation of
|
|
|
|
|
:meth:`~django.db.models.query.QuerySet.prefetch_related()`.
|
|
|
|
|
|
|
|
|
|
The ``lookup`` argument describes the relations to follow and works the same
|
|
|
|
|
as the string based lookups passed to
|
2015-03-10 05:17:33 +00:00
|
|
|
|
:meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example:
|
|
|
|
|
|
|
|
|
|
>>> Question.objects.prefetch_related(Prefetch('choice_set')).get().choice_set.all()
|
|
|
|
|
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
|
|
|
|
|
# This will only execute two queries regardless of the number of Question
|
|
|
|
|
# and Choice objects.
|
|
|
|
|
>>> Question.objects.prefetch_related(Prefetch('choice_set')).all()
|
|
|
|
|
[<Question: Question object>]
|
2015-01-11 20:02:33 +00:00
|
|
|
|
|
|
|
|
|
The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup.
|
|
|
|
|
This is useful to further filter down the prefetch operation, or to call
|
|
|
|
|
:meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched
|
2015-03-10 05:17:33 +00:00
|
|
|
|
relation, hence reducing the number of queries even further:
|
|
|
|
|
|
|
|
|
|
>>> voted_choices = Choice.objects.filter(votes__gt=0)
|
|
|
|
|
>>> voted_choices
|
|
|
|
|
[<Choice: The sky>]
|
|
|
|
|
>>> prefetch = Prefetch('choice_set', queryset=voted_choices)
|
|
|
|
|
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all()
|
|
|
|
|
[<Choice: The sky>]
|
2015-01-11 20:02:33 +00:00
|
|
|
|
|
|
|
|
|
The ``to_attr`` argument sets the result of the prefetch operation to a custom
|
2015-03-10 05:17:33 +00:00
|
|
|
|
attribute:
|
|
|
|
|
|
|
|
|
|
>>> prefetch = Prefetch('choice_set', queryset=voted_choices, to_attr='voted_choices')
|
|
|
|
|
>>> Question.objects.prefetch_related(prefetch).get().voted_choices
|
|
|
|
|
[<Choice: The sky>]
|
|
|
|
|
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all()
|
|
|
|
|
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
|
2015-01-11 20:02:33 +00:00
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
When using ``to_attr`` the prefetched result is stored in a list. This can
|
|
|
|
|
provide a significant speed improvement over traditional
|
|
|
|
|
``prefetch_related`` calls which store the cached result within a
|
|
|
|
|
``QuerySet`` instance.
|