QuerySet API reference

======================

This document describes the details of the ``QuerySet`` API. It builds on the

material presented in the :ref:`model <topics-db-models>` and :ref:`database

Related objects reference

=========================

This document describes extra methods available on managers when used in a one-to-many or many-to-many related context. This happens in two cases:

* The "other side" of a ``ForeignKey`` relation. That is::

class Reporter(models.Model):

...

class Article(models.Model):

reporter = models.ForeignKey(Reporter)

In the above example, the methods below will be available on

the manager ``reporter.article_set``.

* Both sides of a ``ManyToManyField`` relation::

class Topping(models.Model):

...

class Pizza(models.Model):

toppings = models.ManyToManyField(Topping)

In this example, the methods below will be available both on

``topping.pizza_set`` and on ``pizza.toppings``.

Adds the specified model objects to the related object set.

>>> e = Entry.objects.get(id=234)

>>> b.entry_set.add(e) # Associates Entry e with Blog b.

Creates a new object, saves it and puts it in the related object set.

Returns the newly created object::

>>> b = Blog.objects.get(id=1)

>>> e = b.entry_set.create(

... pub_date=datetime.date(2005, 1, 1)

... )

# No need to call e.save() at this point -- it's already been saved.

This is equivalent to (but much simpler than)::

>>> b = Blog.objects.get(id=1)

>>> e = Entry(

.... pub_date=datetime.date(2005, 1, 1)

.... )

>>> e.save(force_insert=True)

``blog`` to ``create()``. Django figures out that the new ``Entry`` object's

``blog`` field should be set to ``b``.

Removes the specified model objects from the related object set::

>>> b = Blog.objects.get(id=1)

>>> e = Entry.objects.get(id=234)

>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.

``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the

``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid.

Removes all objects from the related object set::