mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 10:59:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/.

Browse source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss 2008-08-23 22:25:40 +00:00
parent b3688e8194
commit 97cb07c3a1
188 changed files with 19913 additions and 17059 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/topics/db/index.txt Normal file
View file

@ -0,0 +1,17 @@
.. _topics-db-index:
Models and databases
====================
A model is the single, definitive source of data about your data. It contains
the essential fields and behaviors of the data you're storing. Generally, each
model maps to a single database table.
.. toctree::
:maxdepth: 1
models
queries
managers
sql
transactions

191
docs/topics/db/managers.txt Normal file
View file

@ -0,0 +1,191 @@
.. _topics-db-managers:
========
Managers
========
.. currentmodule:: django.db.models
.. class:: Manager()
A ``Manager`` is the interface through which database query operations are
provided to Django models. At least one ``Manager`` exists for every model in
a Django application.
The way ``Manager`` classes work is documented :ref:`topics-db-queries`; this
document specifically touches on model options that customize ``Manager``
behavior.
Manager names
=============
By default, Django adds a ``Manager`` with the name ``objects`` to every Django
model class. However, if you want to use ``objects`` as a field name, or if you
want to use a name other than ``objects`` for the ``Manager``, you can rename
it on a per-model basis. To rename the ``Manager`` for a given class, define a
class attribute of type ``models.Manager()`` on that model. For example::
from django.db import models
class Person(models.Model):
#...
people = models.Manager()
Using this example model, ``Person.objects`` will generate an
``AttributeError`` exception, but ``Person.people.all()`` will provide a list
of all ``Person`` objects.
.. _custom-managers:
Custom Managers
===============
You can use a custom ``Manager`` in a particular model by extending the base
``Manager`` class and instantiating your custom ``Manager`` in your model.
There are two reasons you might want to customize a ``Manager``: to add extra
``Manager`` methods, and/or to modify the initial ``QuerySet`` the ``Manager``
returns.
Adding extra Manager methods
----------------------------
Adding extra ``Manager`` methods is the preferred way to add "table-level"
functionality to your models. (For "row-level" functionality -- i.e., functions
that act on a single instance of a model object -- use :ref:`Model methods
<model-methods>`, not custom ``Manager`` methods.)
A custom ``Manager`` method can return anything you want. It doesn't have to
return a ``QuerySet``.
For example, this custom ``Manager`` offers a method ``with_counts()``, which
returns a list of all ``OpinionPoll`` objects, each with an extra
``num_responses`` attribute that is the result of an aggregate query::
class PollManager(models.Manager):
def with_counts(self):
from django.db import connection
cursor = connection.cursor()
cursor.execute("""
SELECT p.id, p.question, p.poll_date, COUNT(*)
FROM polls_opinionpoll p, polls_response r
WHERE p.id = r.poll_id
GROUP BY 1, 2, 3
ORDER BY 3 DESC""")
result_list = []
for row in cursor.fetchall():
p = self.model(id=row[0], question=row[1], poll_date=row[2])
p.num_responses = row[3]
result_list.append(p)
return result_list
class OpinionPoll(models.Model):
question = models.CharField(max_length=200)
poll_date = models.DateField()
objects = PollManager()
class Response(models.Model):
poll = models.ForeignKey(Poll)
person_name = models.CharField(max_length=50)
response = models.TextField()
With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return
that list of ``OpinionPoll`` objects with ``num_responses`` attributes.
Another thing to note about this example is that ``Manager`` methods can
access ``self.model`` to get the model class to which they're attached.
Modifying initial Manager QuerySets
-----------------------------------
A ``Manager``'s base ``QuerySet`` returns all objects in the system. For
example, using this model::
class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=50)
...the statement ``Book.objects.all()`` will return all books in the database.
You can override a ``Manager``\'s base ``QuerySet`` by overriding the
``Manager.get_query_set()`` method. ``get_query_set()`` should return a
``QuerySet`` with the properties you require.
For example, the following model has *two* ``Manager``\s -- one that returns
all objects, and one that returns only the books by Roald Dahl::
# First, define the Manager subclass.
class DahlBookManager(models.Manager):
def get_query_set(self):
return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl')
# Then hook it into the Book model explicitly.
class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=50)
objects = models.Manager() # The default manager.
dahl_objects = DahlBookManager() # The Dahl-specific manager.
With this sample model, ``Book.objects.all()`` will return all books in the
database, but ``Book.dahl_objects.all()`` will only return the ones written by
Roald Dahl.
Of course, because ``get_query_set()`` returns a ``QuerySet`` object, you can
use ``filter()``, ``exclude()`` and all the other ``QuerySet`` methods on it.
So these statements are all legal::
Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()
This example also pointed out another interesting technique: using multiple
managers on the same model. You can attach as many ``Manager()`` instances to
a model as you'd like. This is an easy way to define common "filters" for your
models.
For example::
class MaleManager(models.Manager):
def get_query_set(self):
return super(MaleManager, self).get_query_set().filter(sex='M')
class FemaleManager(models.Manager):
def get_query_set(self):
return super(FemaleManager, self).get_query_set().filter(sex='F')
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
people = models.Manager()
men = MaleManager()
women = FemaleManager()
This example allows you to request ``Person.men.all()``, ``Person.women.all()``,
and ``Person.people.all()``, yielding predictable results.
If you use custom ``Manager`` objects, take note that the first
``Manager`` Django encounters (in the order in which they're defined
in the model) has a special status. Django interprets this first
``Manager`` defined in a class as the "default" ``Manager``, and
several parts of Django (though not the admin application) will use
that ``Manager`` exclusively for that model. As a result, it's often a
good idea to be careful in your choice of default manager, in order to
avoid a situation where overriding of ``get_query_set()`` results in
an inability to retrieve objects you'd like to work with.
Using managers for related object access
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, Django uses a "bare" (i.e. default) manager when accessing related
objects (i.e. ``choice.poll``). If this default isn't appropriate for your
default manager, you can force Django to use a custom manager for related object
attributes by giving it a ``use_for_related_fields`` property::
class MyManager(models.Manager)::
use_for_related_fields = True
...
...

746
docs/topics/db/models.txt Normal file
View file

@ -0,0 +1,746 @@
.. _topics-db-models:
==============
Writing models
==============
.. module:: django.db.models
A model is the single, definitive source of data about your data. It contains
the essential fields and behaviors of the data you're storing. Generally, each
model maps to a single database table.
The basics:
* Each model is a Python class that subclasses
:class:`django.db.models.Model`.
* Each attribute of the model represents a database field.
* With all of this, Django gives you an automatically-generated
database-access API; see :ref:`topics-db-queries`.
.. seealso::
A companion to this document is the `official repository of model
examples`_. (In the Django source distribution, these examples are in the
``tests/modeltests`` directory.)
.. _official repository of model examples: http://www.djangoproject.com/documentation/models/
Quick example
=============
This example model defines a ``Person``, which has a ``first_name`` and
``last_name``::
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=30)
last_name = models.CharField(max_length=30)
``first_name`` and ``last_name`` are :term:`fields <field>` of the model. Each
field is specified as a class attribute, and each attribute maps to a database
column.
The above ``Person`` model would create a database table like this:
.. code-block:: sql
CREATE TABLE myapp_person (
"id" serial NOT NULL PRIMARY KEY,
"first_name" varchar(30) NOT NULL,
"last_name" varchar(30) NOT NULL
);
Some technical notes:
* The name of the table, ``myapp_person``, is automatically derived from
some model metadata but can be overridden. See :ref:`table-names` for more
details..
* An ``id`` field is added automatically, but this behavior can be
overridden. See :ref:`automatic-primary-key-fields`.
* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
syntax, but it's worth noting Django uses SQL tailored to the database
backend specified in your :ref:`settings file <topics-settings>`.
Using models
============
Once you have defined your models, you need to tell Django you're going to *use*
those models. Do this by editing your settings file and changing the
:setting:`INSTALLED_APPS` setting to add the name of the module that contains
your ``models.py``.
For example, if the models for your application live in the module
``mysite.myapp.models`` (the package structure that is created for an
application by the :djadmin:`manage.py startapp <startapp>` script),
:setting:`INSTALLED_APPS` should read, in part::
INSTALLED_APPS = (
#...
'mysite.myapp',
#...
)
When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
:djadmin:`manage.py syncdb <syncdb>`.
Fields
======
The most important part of a model -- and the only required part of a model --
is the list of database fields it defines. Fields are specified by class
attributes.
Example::
class Musician(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
instrument = models.CharField(max_length=100)
class Album(models.Model):
artist = models.ForeignKey(Musician)
name = models.CharField(max_length=100)
release_date = models.DateField()
num_stars = models.IntegerField()
Field types
-----------
Each field in your model should be an instance of the appropriate
:class:`~django.db.models.Field` class. Django uses the field class types to
determine a few things:
* The database column type (e.g. ``INTEGER``, ``VARCHAR``).
* The widget to use in Django's admin interface, if you care to use it
(e.g. ``<input type="text">``, ``<select>``).
* The minimal validation requirements, used in Django's admin and in
automatically-generated forms.
Django ships with dozens of built-in field types; you can find the complete list
in the :ref:`model field reference <model-field-types>`. You can easily write
your own fields if Django's built-in ones don't do the trick; see
:ref:`howto-custom-model-fields`.
Field options
-------------
Each field takes a certain set of field-specific arguments (documented in the
:ref:`model field reference <model-field-types>`). For example,
:class:`~django.db.models.CharField` (and its subclasses) require a
:attr:`~django.db.models.CharField.max_length` argument which specifies the size
of the ``VARCHAR`` database field used to store the data.
There's also a set of common arguments available to all field types. All are
optional. They're fully explained in the :ref:`reference
<common-model-field-options>`, but here's a quick summary of the most often-used
ones:
:attr:`~Field.null`
If ``True``, Django will store empty values as ``NULL`` in the database.
Default is ``False``.
:attr:`~ieldblank`
If ``True``, the field is allowed to be blank. Default is ``False``.
Note that this is different than :attr:`~Field.null`.
:attr:`~Field.null` is purely database-related, whereas
:attr:`~Field.blank` is validation-related. If a field has
:attr:`blank=True <Field.blank>`, validation on Django's admin site will
allow entry of an empty value. If a field has :attr:`blank=False
<Field.blank>`, the field will be required.
:attr:`~Field.choices`
An iterable (e.g., a list or tuple) of 2-tuples to use as choices for
this field. If this is given, Django's admin will use a select box
instead of the standard text field and will limit choices to the choices
given.
A choices list looks like this::
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
('GR', 'Graduate'),
)
:attr:`~Field.default`
The default value for the field. This can be a value or a callable
object. If callable it will be called every time a new object is
created.
:attr:`~Field.help_text`
Extra "help" text to be displayed under the field on the object's admin
form. It's useful for documentation even if your object doesn't have an
admin form.
:attr:`~Field.primary_key``
If ``True``, this field is the primary key for the model.
If you don't specify :attr:`primary_key=True <Field.primary_key>` for
any fields in your model, Django will automatically add an
:class:`IntegerField` to hold the primary key, so you don't need to set
:attr:`primary_key=True <Field.primary_key>` on any of your fields
unless you want to override the default primary-key behavior. For more,
see :ref:`automatic-primary-key-fields`.
:attr:`~Field.unique`
If ``True``, this field must be unique throughout the table.
Again, these are just short descriptions of the most common field options. Full
details can be found in the :ref:`common model field option reference
<common-model-field-options>`.
.. _automatic-primary-key-fields:
Automatic primary key fields
----------------------------
By default, Django gives each model the following field::
id = models.AutoField(primary_key=True)
This is an auto-incrementing primary key.
If you'd like to specify a custom primary key, just specify
:attr:`primary_key=True <Field.primary_key>` on one of your fields. If Django
sees you've explicitly set :attr:`Field.primary_key`, it won't add the automatic
``id`` column.
Each model requires exactly one field to have :attr:`primary_key=True
<Field.primary_key>`.
Verbose field names
-------------------
Each field type, except for :class:`~django.db.models.ForeignKey`,
:class:`~django.db.models.ManyToManyField` and
:class:`~django.db.models.OneToOneField`, takes an optional first positional
argument -- a verbose name. If the verbose name isn't given, Django will
automatically create it using the field's attribute name, converting underscores
to spaces.
In this example, the verbose name is ``"Person's first name"``::
first_name = models.CharField("Person's first name", max_length=30)
In this example, the verbose name is ``"first name"``::
first_name = models.CharField(max_length=30)
:class:`~django.db.models.ForeignKey`,
:class:`~django.db.models.ManyToManyField` and
:class:`~django.db.models.OneToOneField` require the first argument to be a
model class, so use the :attr:`~Field.verbose_name` keyword argument::
poll = models.ForeignKey(Poll, verbose_name="the related poll")
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(Place, verbose_name="related place")
The convention is not to capitalize the first letter of the
:attr:`~Field.verbose_name`. Django will automatically capitalize the first
letter where it needs to.
Relationships
-------------
Clearly, the power of relational databases lies in relating tables to each
other. Django offers ways to define the three most common types of database
relationships: Many-to-one, many-to-many and one-to-one.
Many-to-one relationships
~~~~~~~~~~~~~~~~~~~~~~~~~
To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
You use it just like any other :class:`~django.db.models.Field` type: by
including it as a class attribute of your model.
:class:`~django.db.models.ForeignKey` requires a positional argument: the class
to which the model is related.
For example, if a ``Car`` model has a ``Manufacturer`` -- that is, a
``Manufacturer`` makes multiple cars but each ``Car`` only has one
``Manufacturer`` -- use the following definitions::
class Manufacturer(models.Model):
# ...
class Car(models.Model):
manufacturer = models.ForeignKey(Manufacturer)
# ...
You can also create :ref:`recursive relationships <recursive-relationships>` (an
object with a many-to-one relationship to itself) and :ref:`relationsips to
models not yet defined <lazy-relationships>`; see :ref:`the model field
reference <ref-foreignkey>` for details.`
It's suggested, but not required, that the name of a
:class:`~django.db.models.ForeignKey` field (``manufacturer`` in the example
above) be the name of the model, lowercase. You can, of course, call the field
whatever you want. For example::
class Car(models.Model):
company_that_makes_it = models.ForeignKey(Manufacturer)
# ...
.. seealso::
See the `Many-to-one relationship model example`_ for a full example.
.. _Many-to-one relationship model example: http://www.djangoproject.com/models/many_to_one/
:class:`~django.db.models.ForeignKey` fields also accept a number of extra
arguments which are explained in :ref:`the model field reference
<foreign-key-arguments>`. These options help define how the relationship should
work; all are optional.
Many-to-many relationships
~~~~~~~~~~~~~~~~~~~~~~~~~~
To define a many-to-many relationship, use
:class:`~django.db.models.ManyToManyField`. You use it just like any other
:class:`~django.db.models.Field` type: by including it as a class attribute of
your model.
:class:`~django.db.models.ManyToManyField` requires a positional argument: the
class to which the model is related.
For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a
``Topping`` can be on multiple pizzas and each ``Pizza`` has multiple toppings
-- here's how you'd represent that::
class Topping(models.Model):
# ...
class Pizza(models.Model):
# ...
toppings = models.ManyToManyField(Topping)
As with :class:`~django.db.models.ForeignKey`, you can also create
:ref:`recursive relationships <recursive-relationships>` (an object with a
many-to-one relationship to itself) and :ref:`relationships to models not yet
defined <lazy-relationships>`; see :ref:`the model field reference
<ref-manytomany>` for details.`
It's suggested, but not required, that the name of a
:class:`~django.db.models.ManyToManyField` (``toppings`` in the example above)
be a plural describing the set of related model objects.
It doesn't matter which model gets the
:class:`~django.db.models.ManyToManyField`, but you only need it in one of the
models -- not in both.
Generally, :class:`~django.db.models.ManyToManyField` instances should go in the
object that's going to be edited in the admin interface, if you're using
Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than
``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )
because it's more natural to think about a ``Pizza`` having toppings than a
topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
form would let users select the toppings.
.. seealso::
See the `Many-to-many relationship model example`_ for a full example.
.. _Many-to-many relationship model example: http://www.djangoproject.com/models/many_to_many/
:class:`~django.db.models.ManyToManyField` fields also accept a number of extra
arguments which are explained in :ref:`the model field reference
<manytomany-arguments>`. These options help define how the relationship should
work; all are optional.
Extra fields on many-to-many relationships
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**New in Django development version**
When you're only dealing with simple many-to-many relationships such as
mixing and matching pizzas and toppings, a standard ``ManyToManyField``
is all you need. However, sometimes you may need to associate data with the
relationship between two models.
For example, consider the case of an application tracking the musical groups
which musicians belong to. There is a many-to-many relationship between a person
and the groups of which they are a member, so you could use a ManyToManyField
to represent this relationship. However, there is a lot of detail about the
membership that you might want to collect, such as the date at which the person
joined the group.
For these situations, Django allows you to specify the model that will be used
to govern the many-to-many relationship. You can then put extra fields on the
intermediate model. The intermediate model is associated with the
``ManyToManyField`` using the ``through`` argument to point to the model
that will act as an intermediary. For our musician example, the code would look
something like this::
class Person(models.Model):
name = models.CharField(max_length=128)
def __unicode__(self):
return self.name
class Group(models.Model):
name = models.CharField(max_length=128)
members = models.ManyToManyField(Person, through='Membership')
def __unicode__(self):
return self.name
class Membership(models.Model):
person = models.ForeignKey(Person)
group = models.ForeignKey(Group)
date_joined = models.DateField()
invite_reason = models.CharField(max_length=64)
When you set up the intermediary model, you explicitly specify foreign
keys to the models that are involved in the ManyToMany relation. This
explicit declaration defines how the two models are related.
There are a few restrictions on the intermediate model:
* Your intermediate model must contain one - and *only* one - foreign key
on the target model (this would be ``Person`` in our example). If you
have more than one foreign key, a validation error will be raised.
* Your intermediate model must contain one - and *only* one - foreign key
on the source model (this would be ``Group`` in our example). If you
have more than one foreign key, a validation error will be raised.
* The only exception to this is a model which has a many-to-many
relationship to itself, through an intermediary model. In this
case, two foreign keys to the same model are permitted, but they
will be treated as the two (different) sides of the many-to-many
relation.
* When defining a many-to-many relationship from a model to
itself, using an intermediary model, you *must* use
``symmetrical=False`` (see the documentation for
``ManyToManyField`` above).
Now that you have set up your ``ManyToManyField`` to use your intermediary
model (Membership, in this case), you're ready to start creating some
many-to-many relationships. You do this by creating instances of the
intermediate model::
>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(person=ringo, group=beatles,
... date_joined=date(1962, 8, 16),
... invite_reason= "Needed a new drummer.")
>>> m1.save()
>>> beatles.members.all()
[<Person: Ringo Starr>]
>>> ringo.group_set.all()
[<Group: The Beatles>]
>>> m2 = Membership.objects.create(person=paul, group=beatles,
... date_joined=date(1960, 8, 1),
... invite_reason= "Wanted to form a band.")
>>> beatles.members.all()
[<Person: Ringo Starr>, <Person: Paul McCartney>]
Unlike normal many-to-many fields, you *can't* use ``add``, ``create``,
or assignment (i.e., ``beatles.members = [...]``) to create relationships::
# THIS WILL NOT WORK
>>> beatles.members.add(john)
# NEITHER WILL THIS
>>> beatles.members.create(name="George Harrison")
# AND NEITHER WILL THIS
>>> beatles.members = [john, paul, ringo, george]
Why? You can't just create a relationship between a Person and a Group - you
need to specify all the detail for the relationship required by the
Membership table. The simple ``add``, ``create`` and assignment calls
don't provide a way to specify this extra detail. As a result, they are
disabled for many-to-many relationships that use an intermediate model.
The only way to create a many-to-many relationship with an intermediate table
is to create instances of the intermediate model.
The ``remove`` method is disabled for similar reasons. However, the
``clear()`` method can be used to remove all many-to-many relationships
for an instance::
# Beatles have broken up
>>> beatles.members.clear()
Once you have established the many-to-many relationships by creating instances
of your intermediate model, you can issue queries. Just as with normal
many-to-many relationships, you can query using the attributes of the
many-to-many-related model::
# Find all the groups with a member whose name starts with 'Paul'
>>> Groups.objects.filter(person__name__startswith='Paul')
[<Group: The Beatles>]
As you are using an intermediate table, you can also query on the attributes
of the intermediate model::
# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
... group__name='The Beatles',
... membership__date_joined__gt=date(1961,1,1))
[<Person: Ringo Starr]
One-to-one relationships
------------------------
One-to-one relationships are very similar to many-to-one relationships. If you
define a ``OneToOneField`` on your model, instances of that model will have
access to the related object via a simple attribute of the model.
For example::
class EntryDetail(models.Model):
entry = models.OneToOneField(Entry)
details = models.TextField()
ed = EntryDetail.objects.get(id=2)
ed.entry # Returns the related Entry object.
The difference comes in "reverse" queries. The related model in a one-to-one
relationship also has access to a ``Manager`` object, but that ``Manager``
represents a single object, rather than a collection of objects::
e = Entry.objects.get(id=2)
e.entrydetail # returns the related EntryDetail object
If no object has been assigned to this relationship, Django will raise
a ``DoesNotExist`` exception.
Instances can be assigned to the reverse relationship in the same way as
you would assign the forward relationship::
e.entrydetail = ed
Models across files
~~~~~~~~~~~~~~~~~~~
It's perfectly OK to relate a model to one from another app. To do this, just
import the related model at the top of the model that holds your model. Then,
just refer to the other model class wherever needed. For example::
from mysite.geography.models import ZipCode
class Restaurant(models.Model):
# ...
zip_code = models.ForeignKey(ZipCode)
Field name restrictions
-----------------------
Django places only two restrictions on model field names:
1. A field name cannot be a Python reserved word, because that would result
in a Python syntax error. For example::
class Example(models.Model):
pass = models.IntegerField() # 'pass' is a reserved word!
2. A field name cannot contain more than one underscore in a row, due to
the way Django's query lookup syntax works. For example::
class Example(models.Model):
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
These limitations can be worked around, though, because your field name doesn't
necessarily have to match your database column name. See the
:attr:`~Field.db_column` option.
SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as
model field names, because Django escapes all database table names and column
names in every underlying SQL query. It uses the quoting syntax of your
particular database engine.
Custom field types
------------------
**New in Django development version**
If one of the existing model fields cannot be used to fit your purposes, or if
you wish to take advantage of some less common database column types, you can
create your own field class. Full coverage of creating your own fields is
provided in :ref:`howto-custom-model-fields`.
.. _meta-options:
Meta options
============
Give your model metadata by using an inner ``class Meta``, like so::
class Ox(models.Model):
horn_length = models.IntegerField()
class Meta:
ordering = ["horn_length"]
verbose_name_plural = "oxen"
Model metadata is "anything that's not a field", such as ordering options
(:attr:`~Options.ordering`), database table name (:attr:`~Options.db_table`), or
human-readable singular and plural names (:attr:`~Options.verbose_name` and
:attr:`~Options.verbose_name_plural`). None are required, and adding ``class
Meta`` to a model is completely optional.
A complete list of all possible ``Meta`` options can be found in the :ref:`model
option reference <ref-models-options>`.
.. _model-methods:
Model methods
=============
Define custom methods on a model to add custom "row-level" functionality to your
objects. Whereas :class:`~django.db.models.Manager` methods are intended to do
"table-wide" things, model methods should act on a particular model instance.
This is a valuable technique for keeping business logic in one place -- the
model.
For example, this model has a few custom methods::
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
birth_date = models.DateField()
address = models.CharField(max_length=100)
city = models.CharField(max_length=50)
state = models.USStateField() # Yes, this is America-centric...
def baby_boomer_status(self):
"Returns the person's baby-boomer status."
import datetime
if datetime.date(1945, 8, 1) <= self.birth_date <= datetime.date(1964, 12, 31):
return "Baby boomer"
if self.birth_date < datetime.date(1945, 8, 1):
return "Pre-boomer"
return "Post-boomer"
def is_midwestern(self):
"Returns True if this person is from the Midwest."
return self.state in ('IL', 'WI', 'MI', 'IN', 'OH', 'IA', 'MO')
def _get_full_name(self):
"Returns the person's full name."
return '%s %s' % (self.first_name, self.last_name)
full_name = property(_get_full_name)
The last method in this example is a :term:`property`. `Read more about
properties`_.
.. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property
The :ref:`model instance reference <ref-models-instances>` has a complete list
of `methods automatically given to each model <model-instance-methods>`. You can
override most of these -- see `overriding predefined model methods`_, below --
but there are a couple that you'll almost always want to define:
:meth:`~Model.__unicode__`
A Python "magic method" that returns a unicode "representation" of any
object. This is what Python and Django will use whenever a model
instance needs to be coerced and displayed as a plain string. Most
notably, this happens when you display an object in an interactive
console or in the admin.
You'll always want to define this method; the default isn't very helpful
at all.
:meth:`~Model.get_absolute_url`
This tells Django how to calculate the URL for an object. Django uses
this in its admin interface, and any time it needs to figure out a URL
for an object.
Any object that has a URL that uniquely identifies it should define this
method.
Overriding predefined model methods
-----------------------------------
There's another set of :ref:`model methods <model-instance-methods>` that
encapsulate a bunch of database behavior that you'll want to customize. In
particular you'll often want to change the way :meth:`~Model.save` and
:meth:`~Model.delete` work.
You're free to override these methods (and any other model method) to alter
behavior.
A classic use-case for overriding the built-in methods is if you want something
to happen whenever you save an object. For example::
class Blog(models.Model):
name = models.CharField(max_length=100)
tagline = models.TextField()
def save(self):
do_something()
super(Blog, self).save() # Call the "real" save() method.
do_something_else()
You can also prevent saving::
class Blog(models.Model):
name = models.CharField(max_length=100)
tagline = models.TextField()
def save(self):
if self.name == "Yoko Ono's blog":
return # Yoko shall never have her own blog!
else:
super(Blog, self).save() # Call the "real" save() method.
It's important to remember to call the superclass method -- that's that
``super(Blog, self).save()`` business -- to ensure that the object still gets
saved into the database. If you forget to call the superclass method, the
default behavior won't happen and the database won't get touched.
Executing custom SQL
--------------------
Another common pattern is writing custom SQL statements in model methods and
module-level methods. The object :class:`django.db.connection
<django.db.backends.DatabaseWrapper>` represents the current database
connection. To use it, call :meth:`connection.cursor()
<django.db.backends.DatabaseWrapper.cursor>` to get a cursor object. Then, call
``cursor.execute(sql, [params])`` to execute the SQL and
:meth:`cursor.fetchone() <django.db.backends.CursorWrapper.fetchone>` or
:meth:`cursor.fetchall() <django.db.backends.CursorWrapper.fetchall>` to return
the resulting rows. For example::
def my_custom_sql(self):
from django.db import connection
cursor = connection.cursor()
cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
row = cursor.fetchone()
return row
:class:`connection <django.db.backends.DatabaseWrapper>` and
:class:`<django.db.backends.CursorWrapper>` mostly implement the standard Python
DB-API -- see :pep:249 -- with the addition of Django's :ref:`transaction
handling <topics-db-transactions>`. If you're not familiar with the Python
DB-API, note that the SQL statement in :meth:`cursor.execute()
<django.db.backends.CursorWrapper.execute>` uses placeholders, ``"%s"``, rather
than adding parameters directly within the SQL. If you use this technique, the
underlying database library will automatically add quotes and escaping to your
parameter(s) as necessary. (Also note that Django expects the ``"%s"``
placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite Python
bindings. This is for the sake of consistency and sanity.)
A final note: If all you want to do is a custom ``WHERE`` clause, you can use
the :meth:`~QuerySet.extra` lookup method, which lets you add custom SQL to a
query.

968
docs/topics/db/queries.txt Normal file
View file

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

35
docs/topics/db/sql.txt Normal file
View file

@ -0,0 +1,35 @@
.. _topics-db-sql:
Performing raw SQL queries
==========================
Feel free to write custom SQL statements in custom model methods and
module-level methods. The object ``django.db.connection`` represents the
current database connection. To use it, call ``connection.cursor()`` to get a
cursor object. Then, call ``cursor.execute(sql, [params])`` to execute the SQL
and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting
rows. Example::
def my_custom_sql(self):
from django.db import connection
cursor = connection.cursor()
cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
row = cursor.fetchone()
return row
``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
(except when it comes to :ref:`transaction handling <topics-db-transactions>`).
If you're not familiar with the Python DB-API, note that the SQL statement in
``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
directly within the SQL. If you use this technique, the underlying database
library will automatically add quotes and escaping to your parameter(s) as
necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the
``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
the sake of consistency and sanity.)
A final note: If all you want to do is a custom ``WHERE`` clause, you can just
use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
API.
.. _Python DB-API: http://www.python.org/peps/pep-0249.html

165
docs/topics/db/transactions.txt Normal file
View file

@ -0,0 +1,165 @@
.. _topics-db-transactions:
==============================
Managing database transactions
==============================
Django gives you a few ways to control how database transactions are managed,
if you're using a database that supports transactions.
Django's default transaction behavior
=====================================
Django's default behavior is to commit automatically when any built-in,
data-altering model function is called. For example, if you call
``model.save()`` or ``model.delete()``, the change will be committed
immediately.
This is much like the auto-commit setting for most databases. As soon as you
perform an action that needs to write to the database, Django produces the
``INSERT``/``UPDATE``/``DELETE`` statements and then does the ``COMMIT``.
There's no implicit ``ROLLBACK``.
Tying transactions to HTTP requests
===================================
The recommended way to handle transactions in Web requests is to tie them to
the request and response phases via Django's ``TransactionMiddleware``.
It works like this: When a request starts, Django starts a transaction. If the
response is produced without problems, Django commits any pending transactions.
If the view function produces an exception, Django rolls back any pending
transactions.
To activate this feature, just add the ``TransactionMiddleware`` middleware to
your ``MIDDLEWARE_CLASSES`` setting::
MIDDLEWARE_CLASSES = (
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.cache.CacheMiddleware',
'django.middleware.transaction.TransactionMiddleware',
)
The order is quite important. The transaction middleware applies not only to
view functions, but also for all middleware modules that come after it. So if
you use the session middleware after the transaction middleware, session
creation will be part of the transaction.
An exception is ``CacheMiddleware``, which is never affected. The cache
middleware uses its own database cursor (which is mapped to its own database
connection internally).
Controlling transaction management in views
===========================================
For most people, implicit request-based transactions work wonderfully. However,
if you need more fine-grained control over how transactions are managed, you
can use Python decorators to change the way transactions are handled by a
particular view function.
.. note::
Although the examples below use view functions as examples, these
decorators can be applied to non-view functions as well.
``django.db.transaction.autocommit``
------------------------------------
Use the ``autocommit`` decorator to switch a view function to Django's default
commit behavior, regardless of the global transaction setting.
Example::
from django.db import transaction
@transaction.autocommit
def viewfunc(request):
....
Within ``viewfunc()``, transactions will be committed as soon as you call
``model.save()``, ``model.delete()``, or any other function that writes to the
database.
``django.db.transaction.commit_on_success``
-------------------------------------------
Use the ``commit_on_success`` decorator to use a single transaction for
all the work done in a function::
from django.db import transaction
@transaction.commit_on_success
def viewfunc(request):
....
If the function returns successfully, then Django will commit all work done
within the function at that point. If the function raises an exception, though,
Django will roll back the transaction.
``django.db.transaction.commit_manually``
-----------------------------------------
Use the ``commit_manually`` decorator if you need full control over
transactions. It tells Django you'll be managing the transaction on your own.
If your view changes data and doesn't ``commit()`` or ``rollback()``, Django
will raise a ``TransactionManagementError`` exception.
Manual transaction management looks like this::
from django.db import transaction
@transaction.commit_manually
def viewfunc(request):
...
# You can commit/rollback however and whenever you want
transaction.commit()
...
# But you've got to remember to do it yourself!
try:
...
except:
transaction.rollback()
else:
transaction.commit()
.. admonition:: An important note to users of earlier Django releases:
The database ``connection.commit()`` and ``connection.rollback()`` methods
(called ``db.commit()`` and ``db.rollback()`` in 0.91 and earlier) no
longer exist. They've been replaced by ``transaction.commit()`` and
``transaction.rollback()``.
How to globally deactivate transaction management
=================================================
Control freaks can totally disable all transaction management by setting
``DISABLE_TRANSACTION_MANAGEMENT`` to ``True`` in the Django settings file.
If you do this, Django won't provide any automatic transaction management
whatsoever. Middleware will no longer implicitly commit transactions, and
you'll need to roll management yourself. This even requires you to commit
changes done by middleware somewhere else.
Thus, this is best used in situations where you want to run your own
transaction-controlling middleware or do something really strange. In almost
all situations, you'll be better off using the default behavior, or the
transaction middleware, and only modify selected functions as needed.
Transactions in MySQL
=====================
If you're using MySQL, your tables may or may not support transactions; it
depends on your MySQL version and the table types you're using. (By
"table types," we mean something like "InnoDB" or "MyISAM".) MySQL transaction
peculiarities are outside the scope of this article, but the MySQL site has
`information on MySQL transactions`_.
If your MySQL setup does *not* support transactions, then Django will function
in auto-commit mode: Statements will be executed and committed as soon as
they're called. If your MySQL setup *does* support transactions, Django will
handle transactions as explained in this document.
.. _information on MySQL transactions: http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html