Fixed #17794 - Added a bunch of cross-reference links to the DB queries topic documentation. Thanks guettli for the initial patch.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@17624 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Carl Meyer
parent
8cadf1d79a
commit
7b624c6c32
|
|
@ -53,7 +53,7 @@ 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.
|
||||
then call :meth:`~django.db.models.Model.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
|
||||
|
|
@ -66,22 +66,24 @@ Assuming models live in a file ``mysite/blog/models.py``, here's an example::
|
|||
>>> b.save()
|
||||
|
||||
This performs an ``INSERT`` SQL statement behind the scenes. Django doesn't hit
|
||||
the database until you explicitly call ``save()``.
|
||||
the database until you explicitly call :meth:`~django.db.models.Model.save`.
|
||||
|
||||
The ``save()`` method has no return value.
|
||||
The :meth:`~django.db.models.Model.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.
|
||||
:meth:`~django.db.models.Model.save` takes a number of advanced options not
|
||||
described here. See the documentation for
|
||||
:meth:`~django.db.models.Model.save` for complete details.
|
||||
|
||||
To create an object and save it all in one step see the ``create()``
|
||||
method.
|
||||
To create an object and save it all in one step see the
|
||||
:meth:`~django.db.models.query.QuerySet.create()` method.
|
||||
|
||||
Saving changes to objects
|
||||
=========================
|
||||
|
||||
To save changes to an object that's already in the database, use ``save()``.
|
||||
To save changes to an object that's already in the database, use
|
||||
:meth:`~django.db.models.Model.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::
|
||||
|
|
@ -90,14 +92,15 @@ this example changes its name and updates its record in the database::
|
|||
>> b5.save()
|
||||
|
||||
This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit
|
||||
the database until you explicitly call ``save()``.
|
||||
the database until you explicitly call :meth:`~django.db.models.Model.save`.
|
||||
|
||||
Saving ``ForeignKey`` and ``ManyToManyField`` fields
|
||||
----------------------------------------------------
|
||||
|
||||
Updating a ``ForeignKey`` field works exactly the same way as saving a normal
|
||||
field; simply assign an object of the right type to the field in question.
|
||||
This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``::
|
||||
Updating a :class:`~django.db.models.ForeignKey` field works exactly the same
|
||||
way as saving a normal field; simply assign an object of the right type to the
|
||||
field in question. This example updates the ``blog`` attribute of an ``Entry``
|
||||
instance ``entry``::
|
||||
|
||||
>>> from blog.models import Entry
|
||||
>>> entry = Entry.objects.get(pk=1)
|
||||
|
|
@ -105,16 +108,19 @@ This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``::
|
|||
>>> 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. This example adds the
|
||||
``Author`` instance ``joe`` to the ``entry`` object::
|
||||
Updating a :class:`~django.db.models.ManyToManyField` works a little
|
||||
differently; use the
|
||||
:meth:`~django.db.models.fields.related.RelatedManager.add` method on the field
|
||||
to add a record to the relation. This example adds the ``Author`` instance
|
||||
``joe`` to the ``entry`` object::
|
||||
|
||||
>>> from blog.models import Author
|
||||
>>> joe = Author.objects.create(name="Joe")
|
||||
>>> entry.authors.add(joe)
|
||||
|
||||
To add multiple records to a ``ManyToManyField`` in one go, include multiple
|
||||
arguments in the call to ``add()``, like this::
|
||||
To add multiple records to a :class:`~django.db.models.ManyToManyField` in one
|
||||
go, include multiple arguments in the call to
|
||||
:meth:`~django.db.models.fields.related.RelatedManager.add`, like this::
|
||||
|
||||
>>> john = Author.objects.create(name="John")
|
||||
>>> paul = Author.objects.create(name="Paul")
|
||||
|
|
@ -127,17 +133,20 @@ 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.
|
||||
To retrieve objects from your database, you construct a
|
||||
:class:`~django.db.models.query.QuerySet` via a
|
||||
:class:`~django.db.models.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``.
|
||||
A :class:`~django.db.models.query.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
|
||||
:class:`~django.db.models.query.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::
|
||||
You get a :class:`~django.db.models.query.QuerySet` by using your model's
|
||||
:class:`~django.db.models.Manager`. Each model has at least one
|
||||
:class:`~django.db.models.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 ...>
|
||||
|
|
@ -153,64 +162,73 @@ directly via the model class, like so::
|
|||
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.
|
||||
The :class:`~django.db.models.Manager` is the main source of ``QuerySets`` for
|
||||
a model. It acts as a "root" :class:`~django.db.models.query.QuerySet` that
|
||||
describes all objects in the model's database table. For example,
|
||||
``Blog.objects`` is the initial :class:`~django.db.models.query.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``::
|
||||
The simplest way to retrieve objects from a table is to get all of them. To do
|
||||
this, use the :meth:`~django.db.models.query.QuerySet.all` method on a
|
||||
:class:`~django.db.models.Manager`::
|
||||
|
||||
>>> all_entries = Entry.objects.all()
|
||||
|
||||
The ``all()`` method returns a ``QuerySet`` of all the objects in the database.
|
||||
The :meth:`~django.db.models.query.QuerySet.all` method returns a
|
||||
:class:`~django.db.models.query.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.)
|
||||
(If ``Entry.objects`` is a :class:`~django.db.models.query.QuerySet`, why can't
|
||||
we just do ``Entry.objects``? That's because ``Entry.objects``, the root
|
||||
:class:`~django.db.models.query.QuerySet`, is a special case that cannot be
|
||||
evaluated. The :meth:`~django.db.models.query.QuerySet.all` method returns a
|
||||
:class:`~django.db.models.query.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.
|
||||
The root :class:`~django.db.models.query.QuerySet` provided by the
|
||||
:class:`~django.db.models.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:
|
||||
To create such a subset, you refine the initial
|
||||
:class:`~django.db.models.query.QuerySet`, adding filter conditions. The two
|
||||
most common ways to refine a :class:`~django.db.models.query.QuerySet` are:
|
||||
|
||||
``filter(**kwargs)``
|
||||
Returns a new ``QuerySet`` containing objects that match the given
|
||||
lookup parameters.
|
||||
Returns a new :class:`~django.db.models.query.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.
|
||||
Returns a new :class:`~django.db.models.query.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::
|
||||
For example, to get a :class:`~django.db.models.query.QuerySet` of blog entries
|
||||
from the year 2006, use :meth:`~django.db.models.query.QuerySet.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``.
|
||||
We don't have to add an :meth:`~django.db.models.query.QuerySet.all` --
|
||||
``Entry.objects.all().filter(...)``. That would still work, but you only need
|
||||
:meth:`~django.db.models.query.QuerySet.all` when you want all objects from the
|
||||
root :class:`~django.db.models.query.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::
|
||||
The result of refining a :class:`~django.db.models.query.QuerySet` is itself a
|
||||
:class:`~django.db.models.query.QuerySet`, so it's possible to chain
|
||||
refinements together. For example::
|
||||
|
||||
>>> Entry.objects.filter(
|
||||
... headline__startswith='What'
|
||||
|
|
@ -220,19 +238,22 @@ possible to chain refinements together. For example::
|
|||
... 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.
|
||||
This takes the initial :class:`~django.db.models.query.QuerySet` of all entries
|
||||
in the database, adds a filter, then an exclusion, then another filter. The
|
||||
final result is a :class:`~django.db.models.query.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.
|
||||
Each time you refine a :class:`~django.db.models.query.QuerySet`, you get a
|
||||
brand-new :class:`~django.db.models.query.QuerySet` that is in no way bound to
|
||||
the previous :class:`~django.db.models.query.QuerySet`. Each refinement creates
|
||||
a separate and distinct :class:`~django.db.models.query.QuerySet` that can be
|
||||
stored, used and reused.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -240,12 +261,13 @@ Example::
|
|||
>> 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
|
||||
These three ``QuerySets`` are separate. The first is a base
|
||||
:class:`~django.db.models.query.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
|
||||
:class:`~django.db.models.query.QuerySet` (``q1``) is unaffected by the
|
||||
refinement process.
|
||||
|
||||
.. _querysets-are-lazy:
|
||||
|
|
@ -253,10 +275,11 @@ refinement process.
|
|||
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::
|
||||
``QuerySets`` are lazy -- the act of creating a
|
||||
:class:`~django.db.models.query.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 :class:`~django.db.models.query.QuerySet` is
|
||||
*evaluated*. Take a look at this example::
|
||||
|
||||
>>> q = Entry.objects.filter(headline__startswith="What")
|
||||
>>> q = q.filter(pub_date__lte=datetime.now())
|
||||
|
|
@ -264,10 +287,12 @@ this example::
|
|||
>>> 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`.
|
||||
once, at the last line (``print q``). In general, the results of a
|
||||
:class:`~django.db.models.query.QuerySet` aren't fetched from the database
|
||||
until you "ask" for them. When you do, the
|
||||
:class:`~django.db.models.query.QuerySet` is *evaluated* by accessing the
|
||||
database. For more details on exactly when evaluation takes place, see
|
||||
:ref:`when-querysets-are-evaluated`.
|
||||
|
||||
|
||||
.. _retrieving-single-object-with-get:
|
||||
|
|
@ -275,46 +300,56 @@ exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
|
|||
Retrieving a single object with get
|
||||
-----------------------------------
|
||||
|
||||
``.filter()`` will always give you a ``QuerySet``, even if only a single
|
||||
object matches the query - in this case, it will be a ``QuerySet`` containing
|
||||
a single element.
|
||||
:meth:`~django.db.models.query.QuerySet.filter` will always give you a
|
||||
:class:`~django.db.models.query.QuerySet`, even if only a single object matches
|
||||
the query - in this case, it will be a
|
||||
:class:`~django.db.models.query.QuerySet` containing a single element.
|
||||
|
||||
If you know there is only one object that matches your query, you can use
|
||||
the ``get()`` method on a `Manager` which returns the object directly::
|
||||
If you know there is only one object that matches your query, you can use the
|
||||
:meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which
|
||||
returns the object directly::
|
||||
|
||||
>>> one_entry = Entry.objects.get(pk=1)
|
||||
|
||||
You can use any query expression with ``get()``, just like with ``filter()`` -
|
||||
again, see `Field lookups`_ below.
|
||||
You can use any query expression with
|
||||
:meth:`~django.db.models.query.QuerySet.get`, just like with
|
||||
:meth:`~django.db.models.query.QuerySet.filter` - again, see `Field lookups`_
|
||||
below.
|
||||
|
||||
Note that there is a difference between using ``.get()``, and using
|
||||
``.filter()`` with a slice of ``[0]``. If there are no results that match the
|
||||
query, ``.get()`` will raise a ``DoesNotExist`` exception. This exception is an
|
||||
attribute of the model class that the query is being performed on - so in the
|
||||
code above, if there is no ``Entry`` object with a primary key of 1, Django will
|
||||
raise ``Entry.DoesNotExist``.
|
||||
Note that there is a difference between using
|
||||
:meth:`~django.db.models.query.QuerySet.get`, and using
|
||||
:meth:`~django.db.models.query.QuerySet.filter` with a slice of ``[0]``. If
|
||||
there are no results that match the query,
|
||||
:meth:`~django.db.models.query.QuerySet.get` will raise a ``DoesNotExist``
|
||||
exception. This exception is an attribute of the model class that the query is
|
||||
being performed on - so in the code above, if there is no ``Entry`` object with
|
||||
a primary key of 1, Django will raise ``Entry.DoesNotExist``.
|
||||
|
||||
Similarly, Django will complain if more than one item matches the ``get()``
|
||||
query. In this case, it will raise ``MultipleObjectsReturned``, which again is
|
||||
an attribute of the model class itself.
|
||||
Similarly, Django will complain if more than one item matches the
|
||||
:meth:`~django.db.models.query.QuerySet.get` query. In this case, it will raise
|
||||
``MultipleObjectsReturned``, which again is an attribute of the model class
|
||||
itself.
|
||||
|
||||
|
||||
Other QuerySet methods
|
||||
----------------------
|
||||
|
||||
Most of the time you'll use ``all()``, ``get()``, ``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.
|
||||
Most of the time you'll use :meth:`~django.db.models.query.QuerySet.all`,
|
||||
:meth:`~django.db.models.query.QuerySet.get`,
|
||||
:meth:`~django.db.models.query.QuerySet.filter` and
|
||||
:meth:`~django.db.models.query.QuerySet.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 :class:`~django.db.models.query.QuerySet` methods.
|
||||
|
||||
.. _limiting-querysets:
|
||||
|
||||
Limiting QuerySets
|
||||
------------------
|
||||
|
||||
Use a subset of 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.
|
||||
Use a subset of Python's array-slicing syntax to limit your
|
||||
:class:`~django.db.models.query.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``)::
|
||||
|
||||
|
|
@ -326,10 +361,11 @@ This returns the sixth through tenth objects (``OFFSET 5 LIMIT 5``)::
|
|||
|
||||
Negative indexing (i.e. ``Entry.objects.all()[-1]``) is not supported.
|
||||
|
||||
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::
|
||||
Generally, slicing a :class:`~django.db.models.query.QuerySet` returns a new
|
||||
:class:`~django.db.models.query.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]
|
||||
|
||||
|
|
@ -354,8 +390,10 @@ 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()``.
|
||||
specified as keyword arguments to the :class:`~django.db.models.query.QuerySet`
|
||||
methods :meth:`~django.db.models.query.QuerySet.filter`,
|
||||
:meth:`~django.db.models.query.QuerySet.exclude` and
|
||||
:meth:`~django.db.models.query.QuerySet.get`.
|
||||
|
||||
Basic lookups keyword arguments take the form ``field__lookuptype=value``.
|
||||
(That's a double-underscore). For example::
|
||||
|
|
@ -377,7 +415,7 @@ translates (roughly) into the following SQL::
|
|||
.. versionchanged:: 1.4
|
||||
The field specified in a lookup has to be the name of a model field.
|
||||
There's one exception though, in case of a
|
||||
:class:`~django.db.models.fields.ForeignKey` you can specify the field
|
||||
:class:`~django.db.models.ForeignKey` you can specify the field
|
||||
name suffixed with ``_id``. In this case, the value parameter is expected
|
||||
to contain the raw value of the foreign model's primary key. For example::
|
||||
|
||||
|
|
@ -387,8 +425,9 @@ 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:
|
||||
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::
|
||||
|
|
@ -479,7 +518,7 @@ All this means is that no error will be raised. For example, in this filter::
|
|||
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::
|
||||
might be confusing is if you are using :lookup:`isnull`. Thus::
|
||||
|
||||
Blog.objects.filter(entry__authors__name__isnull=True)
|
||||
|
||||
|
|
@ -493,28 +532,32 @@ those latter objects, you could write::
|
|||
Spanning multi-valued relationships
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When you are filtering an object based on a ``ManyToManyField`` or a reverse
|
||||
``ForeignKey``, 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.
|
||||
When you are filtering an object based on a
|
||||
:class:`~django.db.models.ManyToManyField` or a reverse
|
||||
:class:`~django.db.models.ForeignKey`, 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
|
||||
The same type of situation arises with a
|
||||
:class:`~django.db.models.ManyToManyField`. For example, if an ``Entry`` has a
|
||||
:class:`~django.db.models.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
|
||||
:meth:`~django.db.models.query.QuerySet.filter` and
|
||||
:meth:`~django.db.models.query.QuerySet.exclude` calls. Everything inside a
|
||||
single :meth:`~django.db.models.query.QuerySet.filter` call is applied
|
||||
simultaneously to filter out items matching all those requirements. Successive
|
||||
:meth:`~django.db.models.query.QuerySet.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.
|
||||
earlier :meth:`~django.db.models.query.QuerySet.filter` call.
|
||||
|
||||
That may sound a bit confusing, so hopefully an example will clarify. To
|
||||
select all blogs that contain entries with both *"Lennon"* in the headline
|
||||
|
|
@ -537,11 +580,14 @@ 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.
|
||||
All of this behavior also applies to
|
||||
:meth:`~django.db.models.query.QuerySet.exclude`: all the conditions in a
|
||||
single :meth:`~django.db.models.query.QuerySet.exclude` statement apply to a
|
||||
single instance (if those conditions are talking about the same multi-valued
|
||||
relation). Conditions in subsequent
|
||||
:meth:`~django.db.models.query.QuerySet.filter` or
|
||||
:meth:`~django.db.models.query.QuerySet.exclude` calls that refer to the same
|
||||
relation may end up filtering on different linked objects.
|
||||
|
||||
.. _query-expressions:
|
||||
|
||||
|
|
@ -552,10 +598,10 @@ In the examples given so far, we have constructed filters that compare
|
|||
the value of a model field with a constant. But what if you want to compare
|
||||
the value of a model field with another field on the same model?
|
||||
|
||||
Django provides the ``F()`` object to allow such comparisons. Instances
|
||||
of ``F()`` act as a reference to a model field within a query. These
|
||||
references can then be used in query filters to compare the values of two
|
||||
different fields on the same model instance.
|
||||
Django provides the :ref:`F() expressions <query-expressions>` to allow such
|
||||
comparisons. Instances of ``F()`` act as a reference to a model field within a
|
||||
query. These references can then be used in query filters to compare the values
|
||||
of two different fields on the same model instance.
|
||||
|
||||
For example, to find a list of all blog entries that have had more comments
|
||||
than pingbacks, we construct an ``F()`` object to reference the pingback count,
|
||||
|
|
@ -587,9 +633,9 @@ issue the query::
|
|||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
For date and date/time fields, you can add or subtract a ``datetime.timedelta``
|
||||
object. The following would return all entries that were modified more than 3 days
|
||||
after they were published::
|
||||
For date and date/time fields, you can add or subtract a
|
||||
:class:`~datetime.timedelta` object. The following would return all entries
|
||||
that were modified more than 3 days after they were published::
|
||||
|
||||
>>> from datetime import timedelta
|
||||
>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))
|
||||
|
|
@ -654,19 +700,23 @@ for you transparently.
|
|||
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.
|
||||
Each :class:`~django.db.models.query.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
|
||||
In a newly created :class:`~django.db.models.query.QuerySet`, the cache is
|
||||
empty. The first time a :class:`~django.db.models.query.QuerySet` is evaluated
|
||||
-- and, hence, a database query happens -- Django saves the query results in
|
||||
the :class:`~django.db.models.query.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.
|
||||
:class:`~django.db.models.query.QuerySet` is being iterated over). Subsequent
|
||||
evaluations of the :class:`~django.db.models.query.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::
|
||||
your :class:`~django.db.models.query.QuerySet`\s correctly. For example, the
|
||||
following will create two :class:`~django.db.models.query.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()]
|
||||
|
|
@ -676,7 +726,8 @@ 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::
|
||||
To avoid this problem, simply save the
|
||||
:class:`~django.db.models.query.QuerySet` and reuse it::
|
||||
|
||||
>>> queryset = Entry.objects.all()
|
||||
>>> print [p.headline for p in queryset] # Evaluate the query set.
|
||||
|
|
@ -687,13 +738,15 @@ To avoid this problem, simply save the ``QuerySet`` and reuse it::
|
|||
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.
|
||||
Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.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.
|
||||
.. comment: Link to Q does not work, since this documentation does not exist yet.
|
||||
|
||||
A :class:`~django.db.models.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::
|
||||
|
||||
|
|
@ -719,11 +772,13 @@ that combine both a normal query and a negated (``NOT``) query::
|
|||
|
||||
Q(question__startswith='Who') | ~Q(pub_date__year=2005)
|
||||
|
||||
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::
|
||||
Each lookup function that takes keyword-arguments
|
||||
(e.g. :meth:`~django.db.models.query.QuerySet.filter`,
|
||||
:meth:`~django.db.models.query.QuerySet.exclude`,
|
||||
:meth:`~django.db.models.query.QuerySet.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'),
|
||||
|
|
@ -784,27 +839,31 @@ primary key field is called ``name``, these two statements are equivalent::
|
|||
Deleting objects
|
||||
================
|
||||
|
||||
The delete method, conveniently, is named ``delete()``. This method immediately
|
||||
deletes the object and has no return value. Example::
|
||||
The delete method, conveniently, is named
|
||||
:meth:`~django.db.models.Model.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``.
|
||||
You can also delete objects in bulk. Every
|
||||
:class:`~django.db.models.query.QuerySet` has a
|
||||
:meth:`~django.db.models.query.QuerySet.delete` method, which deletes all
|
||||
members of that :class:`~django.db.models.query.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``.
|
||||
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
|
||||
:class:`~django.db.models.query.QuerySet` and calling ``delete()`` on each
|
||||
object individually) rather than using the bulk
|
||||
:meth:`~django.db.models.query.QuerySet.delete` method of a
|
||||
:class:`~django.db.models.query.QuerySet`.
|
||||
|
||||
When Django deletes an object, by default it emulates the behavior of the SQL
|
||||
constraint ``ON DELETE CASCADE`` -- in other words, any objects which had
|
||||
|
|
@ -820,11 +879,12 @@ it. For example::
|
|||
:attr:`~django.db.models.ForeignKey.on_delete` argument to the
|
||||
:class:`~django.db.models.ForeignKey`.
|
||||
|
||||
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::
|
||||
Note that :meth:`~django.db.models.query.QuerySet.delete` is the only
|
||||
:class:`~django.db.models.query.QuerySet` method that is not exposed on a
|
||||
:class:`~django.db.models.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()
|
||||
|
||||
|
|
@ -874,15 +934,16 @@ Updating multiple objects at once
|
|||
=================================
|
||||
|
||||
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::
|
||||
a :class:`~django.db.models.query.QuerySet`. You can do this with the
|
||||
:meth:`~django.db.models.query.QuerySet.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. To update a non-relation field, provide the new value as a constant.
|
||||
To update ``ForeignKey`` fields, set the new value to be the new model
|
||||
instance you want to point to. For example::
|
||||
You can only set non-relation fields and :class:`~django.db.models.ForeignKey`
|
||||
fields using this method. To update a non-relation field, provide the new value
|
||||
as a constant. To update :class:`~django.db.models.ForeignKey` fields, set the
|
||||
new value to be the new model instance you want to point to. For example::
|
||||
|
||||
>>> b = Blog.objects.get(pk=1)
|
||||
|
||||
|
|
@ -890,10 +951,11 @@ instance you want to point to. For example::
|
|||
>>> Entry.objects.all().update(blog=b)
|
||||
|
||||
The ``update()`` method is applied instantly and returns the number of rows
|
||||
affected by the query. The only restriction on the ``QuerySet`` that is
|
||||
updated is that it can only access one database table, the model's main
|
||||
table. You can filter based on related fields, but you can only update columns
|
||||
in the model's main table. Example::
|
||||
affected by the query. The only restriction on the
|
||||
:class:`~django.db.models.query.QuerySet` that is updated is that it can only
|
||||
access one database table, the model's main table. You can filter based on
|
||||
related fields, but you can only update columns in the model's main
|
||||
table. Example::
|
||||
|
||||
>>> b = Blog.objects.get(pk=1)
|
||||
|
||||
|
|
@ -902,11 +964,13 @@ in the model's main table. Example::
|
|||
|
||||
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()``::
|
||||
:meth:`~django.db.models.Model.save` methods on your models, or emit the
|
||||
``pre_save`` or ``post_save`` signals (which are a consequence of calling
|
||||
:meth:`~django.db.models.Model.save`). If you want to save every item in a
|
||||
:class:`~django.db.models.query.QuerySet` and make sure that the
|
||||
:meth:`~django.db.models.Model.save` method is called on each instance, you
|
||||
don't need any special function to handle that. Just loop over them and call
|
||||
:meth:`~django.db.models.Model.save`::
|
||||
|
||||
for item in my_queryset:
|
||||
item.save()
|
||||
|
|
@ -931,8 +995,10 @@ a join with an ``F()`` object, a ``FieldError`` will be raised::
|
|||
Related objects
|
||||
===============
|
||||
|
||||
When you define a relationship in a model (i.e., a ``ForeignKey``,
|
||||
``OneToOneField``, or ``ManyToManyField``), instances of that model will have
|
||||
When you define a relationship in a model (i.e., a
|
||||
:class:`~django.db.models.ForeignKey`,
|
||||
:class:`~django.db.models.OneToOneField`, or
|
||||
:class:`~django.db.models.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``
|
||||
|
|
@ -958,8 +1024,9 @@ 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.
|
||||
If a model has a :class:`~django.db.models.ForeignKey`, instances of that model
|
||||
will have access to the related (foreign) object via a simple attribute of the
|
||||
model.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -967,14 +1034,14 @@ Example::
|
|||
>>> 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::
|
||||
the foreign key aren't saved to the database until you call
|
||||
:meth:`~django.db.models.Model.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``
|
||||
If a :class:`~django.db.models.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)
|
||||
|
|
@ -989,8 +1056,9 @@ object instance are cached. Example::
|
|||
>>> 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::
|
||||
Note that the :meth:`~django.db.models.query.QuerySet.select_related`
|
||||
:class:`~django.db.models.query.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.
|
||||
|
|
@ -1001,12 +1069,13 @@ the cache of all one-to-many relationships ahead of time. Example::
|
|||
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.
|
||||
If a model has a :class:`~django.db.models.ForeignKey`, instances of the
|
||||
foreign-key model will have access to a :class:`~django.db.models.Manager` that
|
||||
returns all instances of the first model. By default, this
|
||||
:class:`~django.db.models.Manager` is named ``FOO_set``, where ``FOO`` is the
|
||||
source model name, lowercased. This :class:`~django.db.models.Manager` returns
|
||||
``QuerySets``, which can be filtered and manipulated as described in the
|
||||
"Retrieving objects" section above.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -1029,18 +1098,20 @@ above example code would look like this::
|
|||
>>> 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::
|
||||
You cannot access a reverse :class:`~django.db.models.ForeignKey`
|
||||
:class:`~django.db.models.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 :doc:`related objects reference </ref/models/relations>`.
|
||||
In addition to the :class:`~django.db.models.query.QuerySet` methods defined in
|
||||
"Retrieving objects" above, the :class:`~django.db.models.ForeignKey`
|
||||
:class:`~django.db.models.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 :doc:`related objects reference </ref/models/relations>`.
|
||||
|
||||
``add(obj1, obj2, ...)``
|
||||
Adds the specified model objects to the related object set.
|
||||
|
|
@ -1084,9 +1155,9 @@ 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).
|
||||
:class:`~django.db.models.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::
|
||||
|
||||
|
|
@ -1098,10 +1169,11 @@ An example makes this easier to understand::
|
|||
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``.
|
||||
Like :class:`~django.db.models.ForeignKey`,
|
||||
:class:`~django.db.models.ManyToManyField` can specify ``related_name``. In the
|
||||
above example, if the :class:`~django.db.models.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
|
||||
------------------------
|
||||
|
|
@ -1147,10 +1219,11 @@ 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.
|
||||
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
|
||||
----------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue