django/django

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Fixed #17794 - Added a bunch of cross-reference links to the DB queri…

…es topic documentation. Thanks guettli for the initial patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17624 bcc190cf-cafb-0310-a4f2-bffc1f526a37

Loading branch information...

commit 7b624c6c3205094b4fbf2ef2b7164ff7668665a5 1 parent 8cadf1d

carljm authored March 02, 2012

Showing 1 changed file with 294 additions and 221 deletions. Show diff stats Hide diff stats

515  docs/topics/db/queries.txt

515  docs/topics/db/queries.txt

show inline notes

View

              
    @@ -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.
      
        -
      
        -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
      
        +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
      
        +: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
      
         ----------------------------

0 notes on commit `7b624c6`

Please sign in to comment.

public django/django

HTTPS clone URL

Subversion checkout URL

0 notes on commit 7b624c6

0 notes on commit `7b624c6`