You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
996 lines
38 KiB
996 lines
38 KiB
.. _topics-db-queries: |
|
|
|
============== |
|
Making queries |
|
============== |
|
|
|
.. currentmodule:: django.db.models |
|
|
|
Once you've created your :ref:`data models <topics-db-models>`, Django |
|
automatically gives you a database-abstraction API that lets you create, |
|
retrieve, update and delete objects. This document explains how to use this |
|
API. Refer to the `data model reference <ref-models-index>` for full |
|
details of all the various model lookup options. |
|
|
|
Throughout this guide (and in the reference), we'll refer to the following |
|
models, which comprise a weblog application: |
|
|
|
.. _queryset-model-example: |
|
|
|
.. code-block:: python |
|
|
|
class Blog(models.Model): |
|
name = models.CharField(max_length=100) |
|
tagline = models.TextField() |
|
|
|
def __unicode__(self): |
|
return self.name |
|
|
|
class Author(models.Model): |
|
name = models.CharField(max_length=50) |
|
email = models.EmailField() |
|
|
|
def __unicode__(self): |
|
return self.name |
|
|
|
class Entry(models.Model): |
|
blog = models.ForeignKey(Blog) |
|
headline = models.CharField(max_length=255) |
|
body_text = models.TextField() |
|
pub_date = models.DateTimeField() |
|
authors = models.ManyToManyField(Author) |
|
|
|
def __unicode__(self): |
|
return self.headline |
|
|
|
Creating objects |
|
================ |
|
|
|
To represent database-table data in Python objects, Django uses an intuitive |
|
system: A model class represents a database table, and an instance of that |
|
class represents a particular record in the database table. |
|
|
|
To create an object, instantiate it using keyword arguments to the model class, |
|
then call ``save()`` to save it to the database. |
|
|
|
You import the model class from wherever it lives on the Python path, as you |
|
may expect. (We point this out here because previous Django versions required |
|
funky model importing.) |
|
|
|
Assuming models live in a file ``mysite/blog/models.py``, here's an example:: |
|
|
|
>>> from mysite.blog.models import Blog |
|
>>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.') |
|
>>> b.save() |
|
|
|
This performs an ``INSERT`` SQL statement behind the scenes. Django doesn't hit |
|
the database until you explicitly call ``save()``. |
|
|
|
The ``save()`` method has no return value. |
|
|
|
.. seealso:: |
|
|
|
``save()`` takes a number of advanced options not described here. |
|
See the documentation for ``save()`` for complete details. |
|
|
|
To create an object and save it all in one step see the ```create()``` |
|
method. |
|
|
|
Saving changes to objects |
|
========================= |
|
|
|
To save changes to an object that's already in the database, use ``save()``. |
|
|
|
Given a ``Blog`` instance ``b5`` that has already been saved to the database, |
|
this example changes its name and updates its record in the database:: |
|
|
|
>> b5.name = 'New name' |
|
>> b5.save() |
|
|
|
This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit |
|
the database until you explicitly call ``save()``. |
|
|
|
Saving ``ForeignKey`` and ``ManyToManyField`` fields |
|
---------------------------------------------------- |
|
|
|
Updating ``ForeignKey`` fields works exactly the same way as saving a normal |
|
field; simply assign an object of the right type to the field in question:: |
|
|
|
>>> cheese_blog = Blog.objects.get(name="Cheddar Talk") |
|
>>> entry.blog = cheese_blog |
|
>>> entry.save() |
|
|
|
Updating a ``ManyToManyField`` works a little differently; use the ``add()`` |
|
method on the field to add a record to the relation:: |
|
|
|
>> joe = Author.objects.create(name="Joe") |
|
>> entry.authors.add(joe) |
|
|
|
Django will complain if you try to assign or add an object of the wrong type. |
|
|
|
Retrieving objects |
|
================== |
|
|
|
To retrieve objects from your database, you construct a ``QuerySet`` via a |
|
``Manager`` on your model class. |
|
|
|
A ``QuerySet`` represents a collection of objects from your database. It can |
|
have zero, one or many *filters* -- criteria that narrow down the collection |
|
based on given parameters. In SQL terms, a ``QuerySet`` equates to a ``SELECT`` |
|
statement, and a filter is a limiting clause such as ``WHERE`` or ``LIMIT``. |
|
|
|
You get a ``QuerySet`` by using your model's ``Manager``. Each model has at |
|
least one ``Manager``, and it's called ``objects`` by default. Access it |
|
directly via the model class, like so:: |
|
|
|
>>> Blog.objects |
|
<django.db.models.manager.Manager object at ...> |
|
>>> b = Blog(name='Foo', tagline='Bar') |
|
>>> b.objects |
|
Traceback: |
|
... |
|
AttributeError: "Manager isn't accessible via Blog instances." |
|
|
|
.. note:: |
|
|
|
``Managers`` are accessible only via model classes, rather than from model |
|
instances, to enforce a separation between "table-level" operations and |
|
"record-level" operations. |
|
|
|
The ``Manager`` is the main source of ``QuerySets`` for a model. It acts as a |
|
"root" ``QuerySet`` that describes all objects in the model's database table. |
|
For example, ``Blog.objects`` is the initial ``QuerySet`` that contains all |
|
``Blog`` objects in the database. |
|
|
|
Retrieving all objects |
|
---------------------- |
|
|
|
The simplest way to retrieve objects from a table is to get all of them. |
|
To do this, use the ``all()`` method on a ``Manager``:: |
|
|
|
>>> all_entries = Entry.objects.all() |
|
|
|
The ``all()`` method returns a ``QuerySet`` of all the objects in the database. |
|
|
|
(If ``Entry.objects`` is a ``QuerySet``, why can't we just do ``Entry.objects``? |
|
That's because ``Entry.objects``, the root ``QuerySet``, is a special case |
|
that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that |
|
*can* be evaluated.) |
|
|
|
Retrieving specific objects with filters |
|
---------------------------------------- |
|
|
|
The root ``QuerySet`` provided by the ``Manager`` describes all objects in the |
|
database table. Usually, though, you'll need to select only a subset of the |
|
complete set of objects. |
|
|
|
To create such a subset, you refine the initial ``QuerySet``, adding filter |
|
conditions. The two most common ways to refine a ``QuerySet`` are: |
|
|
|
``filter(**kwargs)`` |
|
Returns a new ``QuerySet`` containing objects that match the given |
|
lookup parameters. |
|
|
|
``exclude(**kwargs)`` |
|
Returns a new ``QuerySet`` containing objects that do *not* match the |
|
given lookup parameters. |
|
|
|
The lookup parameters (``**kwargs`` in the above function definitions) should |
|
be in the format described in `Field lookups`_ below. |
|
|
|
For example, to get a ``QuerySet`` of blog entries from the year 2006, use |
|
``filter()`` like so:: |
|
|
|
Entry.objects.filter(pub_date__year=2006) |
|
|
|
We don't have to add an ``all()`` -- ``Entry.objects.all().filter(...)``. That |
|
would still work, but you only need ``all()`` when you want all objects from the |
|
root ``QuerySet``. |
|
|
|
.. _chaining-filters: |
|
|
|
Chaining filters |
|
~~~~~~~~~~~~~~~~ |
|
|
|
The result of refining a ``QuerySet`` is itself a ``QuerySet``, so it's |
|
possible to chain refinements together. For example:: |
|
|
|
>>> Entry.objects.filter( |
|
... headline__startswith='What' |
|
... ).exclude( |
|
... pub_date__gte=datetime.now() |
|
... ).filter( |
|
... pub_date__gte=datetime(2005, 1, 1) |
|
... ) |
|
|
|
This takes the initial ``QuerySet`` of all entries in the database, adds a |
|
filter, then an exclusion, then another filter. The final result is a |
|
``QuerySet`` containing all entries with a headline that starts with "What", |
|
that were published between January 1, 2005, and the current day. |
|
|
|
.. _filtered-querysets-are-unique: |
|
|
|
Filtered QuerySets are unique |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
Each time you refine a ``QuerySet``, you get a brand-new ``QuerySet`` that is |
|
in no way bound to the previous ``QuerySet``. Each refinement creates a |
|
separate and distinct ``QuerySet`` that can be stored, used and reused. |
|
|
|
Example:: |
|
|
|
>> q1 = Entry.objects.filter(headline__startswith="What") |
|
>> q2 = q1.exclude(pub_date__gte=datetime.now()) |
|
>> q3 = q1.filter(pub_date__gte=datetime.now()) |
|
|
|
These three ``QuerySets`` are separate. The first is a base ``QuerySet`` |
|
containing all entries that contain a headline starting with "What". The second |
|
is a subset of the first, with an additional criteria that excludes records |
|
whose ``pub_date`` is greater than now. The third is a subset of the first, |
|
with an additional criteria that selects only the records whose ``pub_date`` is |
|
greater than now. The initial ``QuerySet`` (``q1``) is unaffected by the |
|
refinement process. |
|
|
|
.. _querysets-are-lazy: |
|
|
|
QuerySets are lazy |
|
~~~~~~~~~~~~~~~~~~ |
|
|
|
``QuerySets`` are lazy -- the act of creating a ``QuerySet`` doesn't involve any |
|
database activity. You can stack filters together all day long, and Django won't |
|
actually run the query until the ``QuerySet`` is *evaluated*. Take a look at |
|
this example:: |
|
|
|
>>> q = Entry.objects.filter(headline__startswith="What") |
|
>>> q = q.filter(pub_date__lte=datetime.now()) |
|
>>> q = q.exclude(body_text__icontains="food") |
|
>>> print q |
|
|
|
Though this looks like three database hits, in fact it hits the database only |
|
once, at the last line (``print q``). In general, the results of a ``QuerySet`` |
|
aren't fetched from the database until you "ask" for them. When you do, the |
|
``QuerySet`` is *evaluated* by accessing the database. For more details on |
|
exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`. |
|
|
|
Other QuerySet methods |
|
~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
Most of the time you'll use ``all()``, ``filter()`` and ``exclude()`` when you |
|
need to look up objects from the database. However, that's far from all there is; see the :ref:`QuerySet API Reference <queryset-api>` for a complete list |
|
of all the various ``QuerySet`` methods. |
|
|
|
.. _limiting-querysets: |
|
|
|
Limiting QuerySets |
|
------------------ |
|
|
|
Use Python's array-slicing syntax to limit your ``QuerySet`` to a certain |
|
number of results. This is the equivalent of SQL's ``LIMIT`` and ``OFFSET`` |
|
clauses. |
|
|
|
For example, this returns the first 5 objects (``LIMIT 5``):: |
|
|
|
>>> Entry.objects.all()[:5] |
|
|
|
This returns the sixth through tenth objects (``OFFSET 5 LIMIT 5``):: |
|
|
|
>>> Entry.objects.all()[5:10] |
|
|
|
Generally, slicing a ``QuerySet`` returns a new ``QuerySet`` -- it doesn't |
|
evaluate the query. An exception is if you use the "step" parameter of Python |
|
slice syntax. For example, this would actually execute the query in order to |
|
return a list of every *second* object of the first 10:: |
|
|
|
>>> Entry.objects.all()[:10:2] |
|
|
|
To retrieve a *single* object rather than a list |
|
(e.g. ``SELECT foo FROM bar LIMIT 1``), use a simple index instead of a |
|
slice. For example, this returns the first ``Entry`` in the database, after |
|
ordering entries alphabetically by headline:: |
|
|
|
>>> Entry.objects.order_by('headline')[0] |
|
|
|
This is roughly equivalent to:: |
|
|
|
>>> Entry.objects.order_by('headline')[0:1].get() |
|
|
|
Note, however, that the first of these will raise ``IndexError`` while the |
|
second will raise ``DoesNotExist`` if no objects match the given criteria. See |
|
``get()`` for more details. |
|
|
|
.. _field-lookups-intro: |
|
|
|
Field lookups |
|
------------- |
|
|
|
Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're |
|
specified as keyword arguments to the ``QuerySet`` methods ``filter()``, |
|
``exclude()`` and ``get()``. |
|
|
|
Basic lookups keyword arguments take the form ``field__lookuptype=value``. |
|
(That's a double-underscore). For example:: |
|
|
|
>>> Entry.objects.filter(pub_date__lte='2006-01-01') |
|
|
|
translates (roughly) into the following SQL:: |
|
|
|
SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01'; |
|
|
|
.. admonition:: How this is possible |
|
|
|
Python has the ability to define functions that accept arbitrary name-value |
|
arguments whose names and values are evaluated at runtime. For more |
|
information, see `Keyword Arguments`_ in the official Python tutorial. |
|
|
|
.. _`Keyword Arguments`: http://docs.python.org/tut/node6.html#SECTION006720000000000000000 |
|
|
|
If you pass an invalid keyword argument, a lookup function will raise |
|
``TypeError``. |
|
|
|
The database API supports about two dozen lookup types; a complete reference |
|
can be found in the :ref:`field lookup reference <field-lookups>`. To give you a taste of what's available, here's some of the more common lookups |
|
you'll probably use: |
|
|
|
:lookup:`exact` |
|
An "exact" match. For example:: |
|
|
|
>>> Entry.objects.get(headline__exact="Man bites dog") |
|
|
|
World generate SQL along these lines: |
|
|
|
.. code-block:: sql |
|
|
|
SELECT ... WHERE headline = 'Man bits dog'; |
|
|
|
If you don't provide a lookup type -- that is, if your keyword argument |
|
doesn't contain a double underscore -- the lookup type is assumed to be |
|
``exact``. |
|
|
|
For example, the following two statements are equivalent:: |
|
|
|
>>> Blog.objects.get(id__exact=14) # Explicit form |
|
>>> Blog.objects.get(id=14) # __exact is implied |
|
|
|
This is for convenience, because ``exact`` lookups are the common case. |
|
|
|
:lookup:`iexact` |
|
A case-insensitive match. So, the query:: |
|
|
|
>>> Blog.objects.get(name__iexact="beatles blog") |
|
|
|
Would match a ``Blog`` titled "Beatles Blog", "beatles blog", or even |
|
"BeAtlES blOG". |
|
|
|
:lookup:`contains` |
|
Case-sensitive containment test. For example:: |
|
|
|
Entry.objects.get(headline__contains='Lennon') |
|
|
|
Roughly translates to this SQL: |
|
|
|
.. code-block:: sql |
|
|
|
SELECT ... WHERE headline LIKE '%Lennon%'; |
|
|
|
Note this will match the headline ``'Today Lennon honored'`` but not |
|
``'today lennon honored'``. |
|
|
|
There's also a case-insensitive version, :lookup:`icontains`. |
|
|
|
:lookup:`startswith`, :lookup:`endswith` |
|
Starts-with and ends-with search, respectively. There are also |
|
case-insensitive versions called :lookup:`istartswith` and |
|
:lookup:`iendswith`. |
|
|
|
Again, this only scratches the surface. A complete reference can be found in the |
|
:ref:`field lookup reference <field-lookups>`. |
|
|
|
Lookups that span relationships |
|
------------------------------- |
|
|
|
Django offers a powerful and intuitive way to "follow" relationships in |
|
lookups, taking care of the SQL ``JOIN``\s for you automatically, behind the |
|
scenes. To span a relationship, just use the field name of related fields |
|
across models, separated by double underscores, until you get to the field you |
|
want. |
|
|
|
This example retrieves all ``Entry`` objects with a ``Blog`` whose ``name`` |
|
is ``'Beatles Blog'``:: |
|
|
|
>>> Entry.objects.filter(blog__name__exact='Beatles Blog') |
|
|
|
This spanning can be as deep as you'd like. |
|
|
|
It works backwards, too. To refer to a "reverse" relationship, just use the |
|
lowercase name of the model. |
|
|
|
This example retrieves all ``Blog`` objects which have at least one ``Entry`` |
|
whose ``headline`` contains ``'Lennon'``:: |
|
|
|
>>> Blog.objects.filter(entry__headline__contains='Lennon') |
|
|
|
If you are filtering across multiple relationships and one of the intermediate |
|
models doesn't have a value that meets the filter condition, Django will treat |
|
it as if there is an empty (all values are ``NULL``), but valid, object there. |
|
All this means is that no error will be raised. For example, in this filter:: |
|
|
|
Blog.objects.filter(entry__author__name='Lennon') |
|
|
|
(if there was a related ``Author`` model), if there was no ``author`` |
|
associated with an entry, it would be treated as if there was also no ``name`` |
|
attached, rather than raising an error because of the missing ``author``. |
|
Usually this is exactly what you want to have happen. The only case where it |
|
might be confusing is if you are using ``isnull``. Thus:: |
|
|
|
Blog.objects.filter(entry__author__name__isnull=True) |
|
|
|
will return ``Blog`` objects that have an empty ``name`` on the ``author`` and |
|
also those which have an empty ``author`` on the ``entry``. If you don't want |
|
those latter objects, you could write:: |
|
|
|
Blog.objetcs.filter(entry__author__isnull=False, |
|
entry__author__name__isnull=True) |
|
|
|
Spanning multi-valued relationships |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
.. versionadded:: 1.0 |
|
|
|
When you are filtering an object based on a ``ManyToManyField`` or a reverse |
|
``ForeignKeyField``, there are two different sorts of filter you may be |
|
interested in. Consider the ``Blog``/``Entry`` relationship (``Blog`` to |
|
``Entry`` is a one-to-many relation). We might be interested in finding blogs |
|
that have an entry which has both *"Lennon"* in the headline and was published |
|
in 2008. Or we might want to find blogs that have an entry with *"Lennon"* in |
|
the headline as well as an entry that was published in 2008. Since there are |
|
multiple entries associated with a single ``Blog``, both of these queries are |
|
possible and make sense in some situations. |
|
|
|
The same type of situation arises with a ``ManyToManyField``. For example, if |
|
an ``Entry`` has a ``ManyToManyField`` called ``tags``, we might want to find |
|
entries linked to tags called *"music"* and *"bands"* or we might want an |
|
entry that contains a tag with a name of *"music"* and a status of *"public"*. |
|
|
|
To handle both of these situations, Django has a consistent way of processing |
|
``filter()`` and ``exclude()`` calls. Everything inside a single ``filter()`` |
|
call is applied simultaneously to filter out items matching all those |
|
requirements. Successive ``filter()`` calls further restrict the set of |
|
objects, but for multi-valued relations, they apply to any object linked to |
|
the primary model, not necessarily those objects that were selected by an |
|
earlier ``filter()`` call. |
|
|
|
That may sound a bit confusing, so hopefully an example will clarify. To |
|
select all blogs that contains entries with *"Lennon"* in the headline and |
|
were published in 2008, we would write:: |
|
|
|
Blog.objects.filter(entry__headline__contains='Lennon', |
|
entry__pub_date__year=2008) |
|
|
|
To select all blogs that contain an entry with *"Lennon"* in the headline |
|
**as well as** an entry that was published in 2008, we would write:: |
|
|
|
Blog.objects.filter(entry__headline__contains='Lennon').filter( |
|
entry__pub_date__year=2008) |
|
|
|
In this second example, the first filter restricted the queryset to all those |
|
blogs linked to that particular type of entry. The second filter restricted |
|
the set of blogs *further* to those that are also linked to the second type of |
|
entry. The entries select by the second filter may or may not be the same as |
|
the entries in the first filter. We are filtering the ``Blog`` items with each |
|
filter statement, not the ``Entry`` items. |
|
|
|
All of this behavior also applies to ``exclude()``: all the conditions in a |
|
single ``exclude()`` statement apply to a single instance (if those conditions |
|
are talking about the same multi-valued relation). Conditions in subsequent |
|
``filter()`` or ``exclude()`` calls that refer to the same relation may end up |
|
filtering on different linked objects. |
|
|
|
The pk lookup shortcut |
|
---------------------- |
|
|
|
For convenience, Django provides a ``pk`` lookup shortcut, which stands for |
|
"primary key". |
|
|
|
In the example ``Blog`` model, the primary key is the ``id`` field, so these |
|
three statements are equivalent:: |
|
|
|
>>> Blog.objects.get(id__exact=14) # Explicit form |
|
>>> Blog.objects.get(id=14) # __exact is implied |
|
>>> Blog.objects.get(pk=14) # pk implies id__exact |
|
|
|
The use of ``pk`` isn't limited to ``__exact`` queries -- any query term |
|
can be combined with ``pk`` to perform a query on the primary key of a model:: |
|
|
|
# Get blogs entries with id 1, 4 and 7 |
|
>>> Blog.objects.filter(pk__in=[1,4,7]) |
|
|
|
# Get all blog entries with id > 14 |
|
>>> Blog.objects.filter(pk__gt=14) |
|
|
|
``pk`` lookups also work across joins. For example, these three statements are |
|
equivalent:: |
|
|
|
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form |
|
>>> Entry.objects.filter(blog__id=3) # __exact is implied |
|
>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact |
|
|
|
Escaping percent signs and underscores in LIKE statements |
|
--------------------------------------------------------- |
|
|
|
The field lookups that equate to ``LIKE`` SQL statements (``iexact``, |
|
``contains``, ``icontains``, ``startswith``, ``istartswith``, ``endswith`` |
|
and ``iendswith``) will automatically escape the two special characters used in |
|
``LIKE`` statements -- the percent sign and the underscore. (In a ``LIKE`` |
|
statement, the percent sign signifies a multiple-character wildcard and the |
|
underscore signifies a single-character wildcard.) |
|
|
|
This means things should work intuitively, so the abstraction doesn't leak. |
|
For example, to retrieve all the entries that contain a percent sign, just use |
|
the percent sign as any other character:: |
|
|
|
>>> Entry.objects.filter(headline__contains='%') |
|
|
|
Django takes care of the quoting for you; the resulting SQL will look something |
|
like this: |
|
|
|
.. code-block:: sql |
|
|
|
SELECT ... WHERE headline LIKE '%\%%'; |
|
|
|
Same goes for underscores. Both percentage signs and underscores are handled |
|
for you transparently. |
|
|
|
.. _caching-and-querysets: |
|
|
|
Caching and QuerySets |
|
--------------------- |
|
|
|
Each ``QuerySet`` contains a cache, to minimize database access. It's important |
|
to understand how it works, in order to write the most efficient code. |
|
|
|
In a newly created ``QuerySet``, the cache is empty. The first time a |
|
``QuerySet`` is evaluated -- and, hence, a database query happens -- Django |
|
saves the query results in the ``QuerySet``'s cache and returns the results |
|
that have been explicitly requested (e.g., the next element, if the |
|
``QuerySet`` is being iterated over). Subsequent evaluations of the |
|
``QuerySet`` reuse the cached results. |
|
|
|
Keep this caching behavior in mind, because it may bite you if you don't use |
|
your ``QuerySet``\s correctly. For example, the following will create two |
|
``QuerySet``\s, evaluate them, and throw them away:: |
|
|
|
>>> print [e.headline for e in Entry.objects.all()] |
|
>>> print [e.pub_date for e in Entry.objects.all()] |
|
|
|
That means the same database query will be executed twice, effectively doubling |
|
your database load. Also, there's a possibility the two lists may not include |
|
the same database records, because an ``Entry`` may have been added or deleted |
|
in the split second between the two requests. |
|
|
|
To avoid this problem, simply save the ``QuerySet`` and reuse it:: |
|
|
|
>>> queryset = Poll.objects.all() |
|
>>> print [p.headline for p in queryset] # Evaluate the query set. |
|
>>> print [p.pub_date for p in queryset] # Re-use the cache from the evaluation. |
|
|
|
Complex lookups with Q objects |
|
============================== |
|
|
|
Keyword argument queries -- in ``filter()``, etc. -- are "AND"ed together. If |
|
you need to execute more complex queries (for example, queries with ``OR`` |
|
statements), you can use ``Q`` objects. |
|
|
|
A ``Q`` object (``django.db.models.Q``) is an object used to encapsulate a |
|
collection of keyword arguments. These keyword arguments are specified as in |
|
"Field lookups" above. |
|
|
|
For example, this ``Q`` object encapsulates a single ``LIKE`` query:: |
|
|
|
Q(question__startswith='What') |
|
|
|
``Q`` objects can be combined using the ``&`` and ``|`` operators. When an |
|
operator is used on two ``Q`` objects, it yields a new ``Q`` object. |
|
|
|
For example, this statement yields a single ``Q`` object that represents the |
|
"OR" of two ``"question__startswith"`` queries:: |
|
|
|
Q(question__startswith='Who') | Q(question__startswith='What') |
|
|
|
This is equivalent to the following SQL ``WHERE`` clause:: |
|
|
|
WHERE question LIKE 'Who%' OR question LIKE 'What%' |
|
|
|
You can compose statements of arbitrary complexity by combining ``Q`` objects |
|
with the ``&`` and ``|`` operators. You can also use parenthetical grouping. |
|
|
|
Each lookup function that takes keyword-arguments (e.g. ``filter()``, |
|
``exclude()``, ``get()``) can also be passed one or more ``Q`` objects as |
|
positional (not-named) arguments. If you provide multiple ``Q`` object |
|
arguments to a lookup function, the arguments will be "AND"ed together. For |
|
example:: |
|
|
|
Poll.objects.get( |
|
Q(question__startswith='Who'), |
|
Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) |
|
) |
|
|
|
... roughly translates into the SQL:: |
|
|
|
SELECT * from polls WHERE question LIKE 'Who%' |
|
AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06') |
|
|
|
Lookup functions can mix the use of ``Q`` objects and keyword arguments. All |
|
arguments provided to a lookup function (be they keyword arguments or ``Q`` |
|
objects) are "AND"ed together. However, if a ``Q`` object is provided, it must |
|
precede the definition of any keyword arguments. For example:: |
|
|
|
Poll.objects.get( |
|
Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)), |
|
question__startswith='Who') |
|
|
|
... would be a valid query, equivalent to the previous example; but:: |
|
|
|
# INVALID QUERY |
|
Poll.objects.get( |
|
question__startswith='Who', |
|
Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))) |
|
|
|
... would not be valid. |
|
|
|
.. seealso:: |
|
|
|
The `OR lookups examples`_ in the Django unit tests show some possible uses |
|
of ``Q``. |
|
|
|
.. _OR lookups examples: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/or_lookups/models.py |
|
|
|
Comparing objects |
|
================= |
|
|
|
To compare two model instances, just use the standard Python comparison operator, |
|
the double equals sign: ``==``. Behind the scenes, that compares the primary |
|
key values of two models. |
|
|
|
Using the ``Entry`` example above, the following two statements are equivalent:: |
|
|
|
>>> some_entry == other_entry |
|
>>> some_entry.id == other_entry.id |
|
|
|
If a model's primary key isn't called ``id``, no problem. Comparisons will |
|
always use the primary key, whatever it's called. For example, if a model's |
|
primary key field is called ``name``, these two statements are equivalent:: |
|
|
|
>>> some_obj == other_obj |
|
>>> some_obj.name == other_obj.name |
|
|
|
Deleting objects |
|
================ |
|
|
|
The delete method, conveniently, is named ``delete()``. This method immediately |
|
deletes the object and has no return value. Example:: |
|
|
|
e.delete() |
|
|
|
You can also delete objects in bulk. Every ``QuerySet`` has a ``delete()`` |
|
method, which deletes all members of that ``QuerySet``. |
|
|
|
For example, this deletes all ``Entry`` objects with a ``pub_date`` year of |
|
2005:: |
|
|
|
Entry.objects.filter(pub_date__year=2005).delete() |
|
|
|
Keep in mind that this will, whenever possible, be executed purely in |
|
SQL, and so the ``delete()`` methods of individual object instances |
|
will not necessarily be called during the process. If you've provided |
|
a custom ``delete()`` method on a model class and want to ensure that |
|
it is called, you will need to "manually" delete instances of that |
|
model (e.g., by iterating over a ``QuerySet`` and calling ``delete()`` |
|
on each object individually) rather than using the bulk ``delete()`` |
|
method of a ``QuerySet``. |
|
|
|
When Django deletes an object, it emulates the behavior of the SQL |
|
constraint ``ON DELETE CASCADE`` -- in other words, any objects which |
|
had foreign keys pointing at the object to be deleted will be deleted |
|
along with it. For example:: |
|
|
|
b = Blog.objects.get(pk=1) |
|
# This will delete the Blog and all of its Entry objects. |
|
b.delete() |
|
|
|
Note that ``delete()`` is the only ``QuerySet`` method that is not exposed on a |
|
``Manager`` itself. This is a safety mechanism to prevent you from accidentally |
|
requesting ``Entry.objects.delete()``, and deleting *all* the entries. If you |
|
*do* want to delete all the objects, then you have to explicitly request a |
|
complete query set:: |
|
|
|
Entry.objects.all().delete() |
|
|
|
Updating multiple objects at once |
|
================================= |
|
|
|
.. versionadded:: 1.0 |
|
|
|
Sometimes you want to set a field to a particular value for all the objects in |
|
a ``QuerySet``. You can do this with the ``update()`` method. For example:: |
|
|
|
# Update all the headlines with pub_date in 2007. |
|
Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same') |
|
|
|
You can only set non-relation fields and ``ForeignKey`` fields using this |
|
method, and the value you set the field to must be a hard-coded Python value |
|
(i.e., you can't set a field to be equal to some other field at the moment). |
|
|
|
To update ``ForeignKey`` fields, set the new value to be the new model |
|
instance you want to point to. Example:: |
|
|
|
>>> b = Blog.objects.get(pk=1) |
|
|
|
# Change every Entry so that it belongs to this Blog. |
|
>>> Entry.objects.all().update(blog=b) |
|
|
|
The ``update()`` method is applied instantly and doesn't return anything |
|
(similar to ``delete()``). The only restriction on the ``QuerySet`` that is |
|
updated is that it can only access one database table, the model's main |
|
table. So don't try to filter based on related fields or anything like that; |
|
it won't work. |
|
|
|
Be aware that the ``update()`` method is converted directly to an SQL |
|
statement. It is a bulk operation for direct updates. It doesn't run any |
|
``save()`` methods on your models, or emit the ``pre_save`` or ``post_save`` |
|
signals (which are a consequence of calling ``save()``). If you want to save |
|
every item in a ``QuerySet`` and make sure that the ``save()`` method is |
|
called on each instance, you don't need any special function to handle that. |
|
Just loop over them and call ``save()``:: |
|
|
|
for item in my_queryset: |
|
item.save() |
|
|
|
Related objects |
|
=============== |
|
|
|
When you define a relationship in a model (i.e., a ``ForeignKey``, |
|
``OneToOneField``, or ``ManyToManyField``), instances of that model will have |
|
a convenient API to access the related object(s). |
|
|
|
Using the models at the top of this page, for example, an ``Entry`` object ``e`` |
|
can get its associated ``Blog`` object by accessing the ``blog`` attribute: |
|
``e.blog``. |
|
|
|
(Behind the scenes, this functionality is implemented by Python descriptors_. |
|
This shouldn't really matter to you, but we point it out here for the curious.) |
|
|
|
Django also creates API accessors for the "other" side of the relationship -- |
|
the link from the related model to the model that defines the relationship. |
|
For example, a ``Blog`` object ``b`` has access to a list of all related |
|
``Entry`` objects via the ``entry_set`` attribute: ``b.entry_set.all()``. |
|
|
|
All examples in this section use the sample ``Blog``, ``Author`` and ``Entry`` |
|
models defined at the top of this page. |
|
|
|
.. _descriptors: http://users.rcn.com/python/download/Descriptor.htm |
|
|
|
One-to-many relationships |
|
------------------------- |
|
|
|
Forward |
|
~~~~~~~ |
|
|
|
If a model has a ``ForeignKey``, instances of that model will have access to |
|
the related (foreign) object via a simple attribute of the model. |
|
|
|
Example:: |
|
|
|
>>> e = Entry.objects.get(id=2) |
|
>>> e.blog # Returns the related Blog object. |
|
|
|
You can get and set via a foreign-key attribute. As you may expect, changes to |
|
the foreign key aren't saved to the database until you call ``save()``. |
|
Example:: |
|
|
|
>>> e = Entry.objects.get(id=2) |
|
>>> e.blog = some_blog |
|
>>> e.save() |
|
|
|
If a ``ForeignKey`` field has ``null=True`` set (i.e., it allows ``NULL`` |
|
values), you can assign ``None`` to it. Example:: |
|
|
|
>>> e = Entry.objects.get(id=2) |
|
>>> e.blog = None |
|
>>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;" |
|
|
|
Forward access to one-to-many relationships is cached the first time the |
|
related object is accessed. Subsequent accesses to the foreign key on the same |
|
object instance are cached. Example:: |
|
|
|
>>> e = Entry.objects.get(id=2) |
|
>>> print e.blog # Hits the database to retrieve the associated Blog. |
|
>>> print e.blog # Doesn't hit the database; uses cached version. |
|
|
|
Note that the ``select_related()`` ``QuerySet`` method recursively prepopulates |
|
the cache of all one-to-many relationships ahead of time. Example:: |
|
|
|
>>> e = Entry.objects.select_related().get(id=2) |
|
>>> print e.blog # Doesn't hit the database; uses cached version. |
|
>>> print e.blog # Doesn't hit the database; uses cached version. |
|
|
|
.. _backwards-related-objects: |
|
|
|
Following relationships "backward" |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
If a model has a ``ForeignKey``, instances of the foreign-key model will have |
|
access to a ``Manager`` that returns all instances of the first model. By |
|
default, this ``Manager`` is named ``FOO_set``, where ``FOO`` is the source |
|
model name, lowercased. This ``Manager`` returns ``QuerySets``, which can be |
|
filtered and manipulated as described in the "Retrieving objects" section |
|
above. |
|
|
|
Example:: |
|
|
|
>>> b = Blog.objects.get(id=1) |
|
>>> b.entry_set.all() # Returns all Entry objects related to Blog. |
|
|
|
# b.entry_set is a Manager that returns QuerySets. |
|
>>> b.entry_set.filter(headline__contains='Lennon') |
|
>>> b.entry_set.count() |
|
|
|
You can override the ``FOO_set`` name by setting the ``related_name`` |
|
parameter in the ``ForeignKey()`` definition. For example, if the ``Entry`` |
|
model was altered to ``blog = ForeignKey(Blog, related_name='entries')``, the |
|
above example code would look like this:: |
|
|
|
>>> b = Blog.objects.get(id=1) |
|
>>> b.entries.all() # Returns all Entry objects related to Blog. |
|
|
|
# b.entries is a Manager that returns QuerySets. |
|
>>> b.entries.filter(headline__contains='Lennon') |
|
>>> b.entries.count() |
|
|
|
You cannot access a reverse ``ForeignKey`` ``Manager`` from the class; it must |
|
be accessed from an instance:: |
|
|
|
>>> Blog.entry_set |
|
Traceback: |
|
... |
|
AttributeError: "Manager must be accessed via instance". |
|
|
|
In addition to the ``QuerySet`` methods defined in "Retrieving objects" above, |
|
the ``ForeignKey`` ``Manager`` has additional methods used to handle the set of |
|
related objects. A synopsis of each is below, and complete details can be found |
|
in the :ref:`related objects reference <ref-models-relations>`. |
|
|
|
``add(obj1, obj2, ...)`` |
|
Adds the specified model objects to the related object set. |
|
|
|
``create(**kwargs)`` |
|
Creates a new object, saves it and puts it in the related object set. |
|
Returns the newly created object. |
|
|
|
``remove(obj1, obj2, ...)`` |
|
Removes the specified model objects from the related object set. |
|
|
|
``clear()`` |
|
Removes all objects from the related object set. |
|
|
|
To assign the members of a related set in one fell swoop, just assign to it |
|
from any iterable object. Example:: |
|
|
|
b = Blog.objects.get(id=1) |
|
b.entry_set = [e1, e2] |
|
|
|
If the ``clear()`` method is available, any pre-existing objects will be |
|
removed from the ``entry_set`` before all objects in the iterable (in this |
|
case, a list) are added to the set. If the ``clear()`` method is *not* |
|
available, all objects in the iterable will be added without removing any |
|
existing elements. |
|
|
|
Each "reverse" operation described in this section has an immediate effect on |
|
the database. Every addition, creation and deletion is immediately and |
|
automatically saved to the database. |
|
|
|
Many-to-many relationships |
|
-------------------------- |
|
|
|
Both ends of a many-to-many relationship get automatic API access to the other |
|
end. The API works just as a "backward" one-to-many relationship, above. |
|
|
|
The only difference is in the attribute naming: The model that defines the |
|
``ManyToManyField`` uses the attribute name of that field itself, whereas the |
|
"reverse" model uses the lowercased model name of the original model, plus |
|
``'_set'`` (just like reverse one-to-many relationships). |
|
|
|
An example makes this easier to understand:: |
|
|
|
e = Entry.objects.get(id=3) |
|
e.authors.all() # Returns all Author objects for this Entry. |
|
e.authors.count() |
|
e.authors.filter(name__contains='John') |
|
|
|
a = Author.objects.get(id=5) |
|
a.entry_set.all() # Returns all Entry objects for this Author. |
|
|
|
Like ``ForeignKey``, ``ManyToManyField`` can specify ``related_name``. In the |
|
above example, if the ``ManyToManyField`` in ``Entry`` had specified |
|
``related_name='entries'``, then each ``Author`` instance would have an |
|
``entries`` attribute instead of ``entry_set``. |
|
|
|
One-to-one relationships |
|
------------------------ |
|
|
|
One-to-one relationships are very similar to many-to-one relationships. If you |
|
define a :class:`~django.db.models.OneToOneField` on your model, instances of |
|
that model will have access to the related object via a simple attribute of the |
|
model. |
|
|
|
For example:: |
|
|
|
class EntryDetail(models.Model): |
|
entry = models.OneToOneField(Entry) |
|
details = models.TextField() |
|
|
|
ed = EntryDetail.objects.get(id=2) |
|
ed.entry # Returns the related Entry object. |
|
|
|
The difference comes in "reverse" queries. The related model in a one-to-one |
|
relationship also has access to a :class:`~django.db.models.Manager` object, but |
|
that :class:`~django.db.models.Manager` represents a single object, rather than |
|
a collection of objects:: |
|
|
|
e = Entry.objects.get(id=2) |
|
e.entrydetail # returns the related EntryDetail object |
|
|
|
If no object has been assigned to this relationship, Django will raise |
|
a ``DoesNotExist`` exception. |
|
|
|
Instances can be assigned to the reverse relationship in the same way as |
|
you would assign the forward relationship:: |
|
|
|
e.entrydetail = ed |
|
|
|
How are the backward relationships possible? |
|
-------------------------------------------- |
|
|
|
Other object-relational mappers require you to define relationships on both |
|
sides. The Django developers believe this is a violation of the DRY (Don't |
|
Repeat Yourself) principle, so Django only requires you to define the |
|
relationship on one end. |
|
|
|
But how is this possible, given that a model class doesn't know which other |
|
model classes are related to it until those other model classes are loaded? |
|
|
|
The answer lies in the :setting:`INSTALLED_APPS` setting. The first time any model is |
|
loaded, Django iterates over every model in :setting:`INSTALLED_APPS` and creates the |
|
backward relationships in memory as needed. Essentially, one of the functions |
|
of :setting:`INSTALLED_APPS` is to tell Django the entire model domain. |
|
|
|
Queries over related objects |
|
---------------------------- |
|
|
|
Queries involving related objects follow the same rules as queries involving |
|
normal value fields. When specifying the value for a query to match, you may |
|
use either an object instance itself, or the primary key value for the object. |
|
|
|
For example, if you have a Blog object ``b`` with ``id=5``, the following |
|
three queries would be identical:: |
|
|
|
Entry.objects.filter(blog=b) # Query using object instance |
|
Entry.objects.filter(blog=b.id) # Query using id from instance |
|
Entry.objects.filter(blog=5) # Query using id directly |
|
|
|
Falling back to raw SQL |
|
======================= |
|
|
|
If you find yourself needing to write an SQL query that is too complex for |
|
Django's database-mapper to handle, you can fall back into raw-SQL statement |
|
mode. |
|
|
|
The preferred way to do this is by giving your model custom methods or custom |
|
manager methods that execute queries. Although there's nothing in Django that |
|
*requires* database queries to live in the model layer, this approach keeps all |
|
your data-access logic in one place, which is smart from an code-organization |
|
standpoint. For instructions, see :ref:`topics-db-sql`. |
|
|
|
Finally, it's important to note that the Django database layer is merely an |
|
interface to your database. You can access your database via other tools, |
|
programming languages or database frameworks; there's nothing Django-specific |
|
about your database. |