Models. Django Software
Django software is a free and open-source web framework written in Python. It is designed to make the development of complex, database-driven websites quick and easy. Django emphasizes reusability and pluggability of components, rapid development, and clean, pragmatic design. It is maintained by an active community of developers worldwide.
Advertisement
Advertisement
Django Documentation, Release 1.5.12
CSRF protection middleware
class CsrfViewMiddleware
Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value. See the
Cross Site Request Forgery protection documentation .
Transaction middleware
class TransactionMiddleware
Binds commit and rollback of the default database to the request/response phase. If a view function runs successfully, a commit is done. If it fails with an exception, a rollback is done.
The order of this middleware in the stack is important: middleware modules running outside of it run with commiton-save - the default Django behavior. Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions.
See the
transaction management documentation .
X-Frame-Options middleware
class XFrameOptionsMiddleware
XFrameOptionsMiddleware was added. Simple
clickjacking protection via the X-Frame-Options header .
Models
Model API reference. For introductory material, see
Model field reference
This document contains all the gory details about all the
and
Django’s got to offer.
See also:
If the built-in fields don’t do the trick, you can try
pieces of code that are useful for particular countries or cultures. Also, you can easily
write your own custom model fields .
Note: Technically, these models are defined in
, but for convenience they’re im-
ported into
; the standard convention is to use from django.db import models and
refer to fields as models.<Foo>Field.
Field options
The following arguments are available to all field types. All are optional.
906 Chapter 6. API Reference
Django Documentation, Release 1.5.12
null
Field.null
If True, Django will store empty values as NULL in the database. Default is False.
Note that empty string values will always get stored as empty strings, not as NULL. Only use null=True for nonstring fields such as integers, booleans and dates. For both types of fields, you will also need to set blank=True if you wish to permit empty values in forms, as the
parameter only affects database storage (see
Avoid using
on string-based fields such as
and
unless you have an excellent reason.
If a string-based field has null=True, that means it has two possible values for “no data”: NULL, and the empty string. In most cases, it’s redundant to have two possible values for “no data;” Django convention is to use the empty string, not NULL.
Note: When using the Oracle database backend, the value NULL will be stored to denote the empty string regardless of this attribute.
If you want to accept
values with
instead.
blank
Field.blank
If True, the field is allowed to be blank. Default is False.
Note that this is different than
is purely database-related, whereas
is validation-related. If a field has blank=True, form validation will allow entry of an empty value. If a field has blank=False, the field will be required.
choices
Field.choices
An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this field. If this is given, the default form widget will be a select box with these choices instead of the standard text field.
The first element in each tuple is the actual value to be stored, and the second element is the human-readable name.
For example:
YEAR_IN_SCHOOL_CHOICES = (
( 'FR' , 'Freshman' ),
( 'SO' , 'Sophomore' ),
( 'JR' , 'Junior' ),
( 'SR' , 'Senior' ),
)
Generally, it’s best to define choices inside a model class, and to define a suitably-named constant for each value:
class Student
(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
JUNIOR = 'JR'
SENIOR = 'SR'
YEAR_IN_SCHOOL_CHOICES = (
6.11. Models 907
Django Documentation, Release 1.5.12
(FRESHMAN, 'Freshman' ),
(SOPHOMORE, 'Sophomore' ),
(JUNIOR, 'Junior' ),
(SENIOR, 'Senior' ),
) year_in_school = models.CharField(max_length= 2 , choices=YEAR_IN_SCHOOL_CHOICES, default=FRESHMAN)
def is_upperclass
( self ):
return
self
.
year_in_school in ( self
.
JUNIOR, self
.
SENIOR)
Though you can define a choices list outside of a model class and then refer to it, defining the choices and names for each choice inside the model class keeps all of that information with the class that uses it, and makes the choices easy to reference (e.g, Student.SOPHOMORE will work anywhere that the Student model has been imported).
You can also collect your available choices into named groups that can be used for organizational purposes:
MEDIA_CHOICES = (
( 'Audio' , (
( 'vinyl' , 'Vinyl' ),
( 'cd' , 'CD' ),
)
),
( 'Video' , (
( 'vhs' , 'VHS Tape' ),
( 'dvd' , 'DVD' ),
)
),
( 'unknown' , 'Unknown' ),
)
The first element in each tuple is the name to apply to the group. The second element is an iterable of 2-tuples, with each 2-tuple containing a value and a human-readable name for an option. Grouped options may be combined with ungrouped options within a single list (such as the unknown option in this example).
For each model field that has
set, Django will add a method to retrieve the human-readable name for the field’s current value. See
in the database API documentation.
Finally, note that choices can be any iterable object – not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking
to be dynamic, you’re probably better off using a proper database table with a
is meant for static data that doesn’t change much, if ever.
db_column
Field.db_column
The name of the database column to use for this field. If this isn’t given, Django will use the field’s name.
If your database column name is an SQL reserved word, or contains characters that aren’t allowed in Python variable names – notably, the hyphen – that’s OK. Django quotes column and table names behind the scenes.
db_index
Field.db_index
If True,
will output a CREATE INDEX statement for this field.
908 Chapter 6. API Reference
Django Documentation, Release 1.5.12
db_tablespace
Field.db_tablespace
The name of the
to use for this field’s index, if this field is indexed. The default is the project’s
setting, if set, or the
of the model, if any. If the backend doesn’t support tablespaces for indexes, this option is ignored.
default
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.
The default cannot be a mutable object (model instance, list, set, etc.), as a reference to the same instance of that object would be used as the default value in all new model instances. Instead, wrap the desired default in a callable.
For example, if you had a custom JSONField and wanted to specify a dictionary as the default, use a lambda as follows: contact_info = JSONField( "ContactInfo" , default=lambda:{ "email" : "[email protected]" })
editable
Field.editable
If False, the field will not be displayed in the admin or any other
error_messages
Field.error_messages
The error_messages argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override.
Error message keys include null, blank, invalid, invalid_choice, and unique. Additional error message keys are specified for each field in the
section below.
help_text
Field.help_text
Extra “help” text to be displayed with the form widget. It’s useful for documentation even if your field isn’t used on a form.
Note that this value is not HTML-escaped in automatically-generated forms.
This lets you include HTML in
if you so desire. For example: help_text= "Please use the following format: <em>YYYY-MM-DD</em>."
Alternatively you can use plain text and django.utils.html.escape() to escape any HTML special characters.
6.11. Models 909
Django Documentation, Release 1.5.12
primary_key
Field.primary_key
If True, this field is the primary key for the model.
If you don’t specify primary_key=True for any field in your model, Django will automatically add an
to hold the primary key, so you don’t need to set primary_key=True on any of your fields unless you want to override the default primary-key behavior. For more, see
Automatic primary key fields .
primary_key=True implies
and
. Only one primary key is allowed on an object.
unique
Field.unique
If True, this field must be unique throughout the table.
This is enforced at the database level and by model validation. If you try to save a model with a duplicate value in a
field, a
will be raised by the model’s
method.
This option is valid on all field types except
Note that when unique is True, you don’t need to specify
, because unique implies the creation of an
index.
unique_for_date
Field.unique_for_date
Set this to the name of a
or
to require that this field be unique for the value of the date field.
For example, if you have a field title that has unique_for_date="pub_date", then Django wouldn’t allow the entry of two records with the same title and pub_date.
This is enforced by model validation but not at the database level.
unique_for_month
Field.unique_for_month
Like
, but requires the field to be unique with respect to the month.
unique_for_year
Field.unique_for_year
Like
and
verbose_name
Field.verbose_name
910 Chapter 6. API Reference
Django Documentation, Release 1.5.12
A human-readable name for the field. If the verbose name isn’t given, Django will automatically create it using the field’s attribute name, converting underscores to spaces. See
validators
Field.validators
A list of validators to run for this field. See the
for more information.
Field types
AutoField
class AutoField(**options)
An
that automatically increments according to available IDs. You usually won’t need to use this directly; a primary key field will automatically be added to your model if you don’t specify otherwise. See
Automatic primary key fields .
BigIntegerField
class BigIntegerField(
[
**options
]
)
A 64 bit integer, much like an
except that it is guaranteed to fit numbers from -
9223372036854775808 to 9223372036854775807. The default form widget for this field is a
BooleanField
class BooleanField(**options)
A true/false field.
The default form widget for this field is a
If you need to accept
values then use
instead.
CharField
class CharField(max_length=None
[
, **options
]
)
A string field, for small- to large-sized strings.
For large amounts of text, use
The default form widget for this field is a
has one extra required argument:
CharField.max_length
The maximum length (in characters) of the field. The max_length is enforced at the database level and in
Django’s validation.
6.11. Models 911
Django Documentation, Release 1.5.12
Note: If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on max_length for some backends. Refer to the
for details.
MySQL users
If you are using this field with MySQLdb 1.2.2 and the utf8_bin collation (which is not the default), there are some issues to be aware of. Refer to the
for details.
CommaSeparatedIntegerField
class CommaSeparatedIntegerField(max_length=None
[
, **options
]
)
A field of integers separated by commas. As in
argument is required and the note about database portability mentioned there should be heeded.
DateField
class DateField(
[ auto_now=False , auto_now_add=False, **options
]
)
A date, represented in Python by a datetime.date instance. Has a few extra, optional arguments:
DateField.auto_now
Automatically set the field to now every time the object is saved. Useful for “last-modified” timestamps. Note that the current date is always used; it’s not just a default value that you can override.
DateField.auto_now_add
Automatically set the field to now when the object is first created. Useful for creation of timestamps. Note that the current date is always used; it’s not just a default value that you can override.
The default form widget for this field is a
TextInput . The admin adds a JavaScript calendar, and a shortcut for
“Today”. Includes an additional invalid_date error message key.
Note: As currently implemented, setting auto_now or auto_now_add to True will cause the field to have editable=False and blank=True set.
DateTimeField
class DateTimeField(
[ auto_now=False , auto_now_add=False, **options
]
)
A date and time, represented in Python by a datetime.datetime instance. Takes the same extra arguments as
The default form widget for this field is a single
TextInput . The admin uses two separate TextInput
widgets with JavaScript shortcuts.
DecimalField
class DecimalField(max_digits=None, decimal_places=None
[
, **options
]
)
912 Chapter 6. API Reference
Django Documentation, Release 1.5.12
A fixed-precision decimal number, represented in Python by a
Decimal instance. Has two required arguments:
DecimalField.max_digits
The maximum number of digits allowed in the number. Note that this number must be greater than or equal to decimal_places .
DecimalField.decimal_places
The number of decimal places to store with the number.
For example, to store numbers up to 999 with a resolution of 2 decimal places, you’d use: models.DecimalField(..., max_digits= 5 , decimal_places= 2 )
And to store numbers up to approximately one billion with a resolution of 10 decimal places: models.DecimalField(..., max_digits= 19 , decimal_places= 10 )
The default form widget for this field is a
Note: For more information about the differences between the
and
classes, please see
EmailField
class EmailField(
[ max_length=75
, **options
]
)
A
that checks that the value is a valid email address.
Incompliance to RFCs
The default 75 character max_length is not capable of storing all possible RFC3696/5321-compliant email addresses. In order to store all possible valid email addresses, a max_length of 254 is required. The default max_length of 75 exists for historical reasons. The default has not been changed in order to maintain backwards compatibility with existing uses of
FileField
class FileField(upload_to=None
[
, max_length=100, **options
]
)
A file-upload field.
Note: The primary_key and unique arguments are not supported, and will raise a TypeError if used.
Has one required argument:
FileField.upload_to
A local filesystem path that will be appended to your
setting to determine the value of the
attribute.
This path may contain strftime() formatting, which will be replaced by the date/time of the file upload (so that uploaded files don’t fill up the given directory).
6.11. Models 913
Django Documentation, Release 1.5.12
This may also be a callable, such as a function, which will be called to obtain the upload path, including the filename. This callable must be able to accept two arguments, and return a Unix-style path (with forward slashes) to be passed along to the storage system. The two arguments that will be passed are:
Argument instance filename
Description
An instance of the model where the FileField is defined. More specifically, this is the particular instance where the current file is being attached.
In most cases, this object will not have been saved to the database yet, so if it uses the default
AutoField
, it might not yet have a value for its primary key field .
The filename that was originally given to the file.
This may or may not be taken into account when determining the final destination path.
Also has one optional argument:
FileField.storage
Optional. A storage object, which handles the storage and retrieval of your files. See
for details on how to provide this object.
The default form widget for this field is a
Using a
or an
(see below) in a model takes a few steps:
1. In your settings file, you’ll need to define
as the full path to a directory where you’d like Django to store uploaded files. (For performance, these files are not stored in the database.) Define
as the base public URL of that directory. Make sure that this directory is writable by the Web server’s user account.
2. Add the
or
to your model, making sure to define the
option to tell
Django to which subdirectory of
it should upload files.
3. All that will be stored in your database is a path to the file (relative to
MEDIA_ROOT ). You’ll most likely
want to use the convenience
attribute provided by Django. For example, if your
is called mug_shot , you can get the absolute path to your image in a template with {{ object.mug_shot.url
}}
.
For example, say your
is set to '/home/media', and
is set to 'photos/%Y/%m/
%d'
. The '%Y/%m/%d' part of
is strftime() formatting; '%Y' is the four-digit year, '%m' is the two-digit month and '%d' is the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in the directory
/home/media/photos/2007/01/15
.
If you wanted to retrieve the uploaded file’s on-disk filename, or the file’s size, you could use the
and
attributes respectively; for more information on the available attributes and methods, see the
class reference and the
topic guide.
Note: The file is saved as part of saving the model in the database, so the actual file name used on disk cannot be relied on until after the model has been saved.
The uploaded file’s relative URL can be obtained using the
attribute. Internally, this calls the
method of the underlying
class. Note that whenever you deal with uploaded files, you should pay close attention to where you’re uploading them and what type of files they are, to avoid security holes. Validate all uploaded files so that you’re sure the files are what you think they are. For example, if you blindly let somebody upload files, without validation, to a directory that’s within your Web server’s document root, then somebody could upload a CGI or PHP script and execute that script by visiting its URL on your site. Don’t allow that.
914 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Also note that even an uploaded HTML file, since it can be executed by the browser (though not by the server), can pose security threats that are equivalent to XSS or CSRF attacks.
By default,
instances are created as varchar(100) columns in your database. As with other fields, you can change the maximum length using the
argument.
FileField and FieldFile
class FieldFile
When you access a
on a model, you are given an instance of
as a proxy for accessing the underlying file. This class has several attributes and methods that can be used to interact with file data:
FieldFile.url
A read-only property to access the file’s relative URL by calling the
method of the underlying
class.
FieldFile.open( mode=’rb’)
Behaves like the standard Python open() method and opens the file associated with this instance in the mode specified by mode.
FieldFile.close()
Behaves like the standard Python file.close() method and closes the file associated with this instance.
FieldFile.save( name , content, save=True)
This method takes a filename and file contents and passes them to the storage class for the field, then associates the stored file with the model field. If you want to manually associate file data with
instances on your model, the save() method is used to persist that file data.
Takes two required arguments: name which is the name of the file, and content which is an object containing the file’s contents. The optional save argument controls whether or not the instance is saved after the file has been altered. Defaults to True.
Note that the content argument should be an instance of
object. You can construct a
from an existing Python file object like this:
from
django.core.files
import
File
# Open an existing file using Python's built-in open() f = open ( '/tmp/hello.world' ) myfile = File(f)
Or you can construct one from a Python string like this:
from
django.core.files.base
import
ContentFile myfile = ContentFile( "hello world" )
For more information, see
FieldFile.delete( save=True)
Deletes the file associated with this instance and clears all attributes on the field. Note: This method will close the file if it happens to be open when delete() is called.
The optional save argument controls whether or not the instance is saved after the file has been deleted. Defaults to
True
.
6.11. Models 915
Django Documentation, Release 1.5.12
Note that when a model is deleted, related files are not deleted. If you need to cleanup orphaned files, you’ll need to handle it yourself (for instance, with a custom management command that can be run manually or scheduled to run periodically via e.g. cron).
FilePathField
class FilePathField(path=None
[
, match=None, recursive=False, max_length=100, **options
]
)
A
whose choices are limited to the filenames in a certain directory on the filesystem. Has three special arguments, of which the first is required:
FilePathField.path
Required. The absolute filesystem path to a directory from which this
should get its choices.
Example: "/home/images".
FilePathField.match
Optional. A regular expression, as a string, that
will use to filter filenames. Note that the regex will be applied to the base filename, not the full path. Example: "foo.*\.txt$", which will match a file called foo23.txt but not bar.txt or foo23.png.
FilePathField.recursive
Optional. Either True or False. Default is False. Specifies whether all subdirectories of
should be included
FilePathField.allow_files
Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or
must be True.
FilePathField.allow_folders
Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or
must be True.
Of course, these arguments can be used together.
The one potential gotcha is that
applies to the base filename, not the full path. So, this example:
FilePathField(path= "/home/images" , match= "foo.*" , recursive=True)
...will match /home/images/foo.png but not /home/images/foo/bar.png because the
applies to the base filename (foo.png and bar.png).
By default,
instances are created as varchar(100) columns in your database. As with other fields, you can change the maximum length using the
argument.
FloatField
class FloatField(
[
**options
]
)
A floating-point number represented in Python by a float instance.
The default form widget for this field is a
FloatField
vs. DecimalField
The
class is sometimes mixed up with the
class. Although they both represent real numbers, they represent those numbers differently. FloatField uses Python’s float type internally, while
916 Chapter 6. API Reference
Django Documentation, Release 1.5.12
DecimalField uses Python’s Decimal type. For information on the difference between the two, see Python’s documentation for the decimal module.
ImageField
class ImageField(upload_to=None
[
, height_field=None, width_field=None, max_length=100, **options
]
)
Inherits all attributes and methods from
, but also validates that the uploaded object is a valid image.
In addition to the special attributes that are available for
also has height and width attributes.
To facilitate querying on those attributes,
has two extra optional arguments:
ImageField.height_field
Name of a model field which will be auto-populated with the height of the image each time the model instance is saved.
ImageField.width_field
Name of a model field which will be auto-populated with the width of the image each time the model instance is saved.
Requires the Python Imaging Library .
By default,
instances are created as varchar(100) columns in your database. As with other fields, you can change the maximum length using the
argument.
The default form widget for this field is a
IntegerField
class IntegerField(
[
**options
]
)
An integer. The default form widget for this field is a
IPAddressField
class IPAddressField(
[
**options
]
)
An IP address, in string format (e.g. “192.0.2.30”). The default form widget for this field is a
GenericIPAddressField
class GenericIPAddressField(
[ protocol=both , unpack_ipv4=False, **options
]
)
An IPv4 or IPv6 address, in string format (e.g. 192.0.2.30 or 2a02:42fe::4). The default form widget for this field is a
The IPv6 address normalization follows RFC 4291#section-2.2
section 2.2, including using the IPv4 format suggested in paragraph 3 of that section, like ::ffff:192.0.2.0. For example, 2001:0::0:01 would be normalized to
2001::1
, and ::ffff:0a0a:0a0a to ::ffff:10.10.10.10. All characters are converted to lowercase.
6.11. Models 917
Django Documentation, Release 1.5.12
GenericIPAddressField.protocol
Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'.
Matching is case insensitive.
GenericIPAddressField.unpack_ipv4
Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
NullBooleanField
class NullBooleanField(
[
**options
]
)
Like a
, but allows NULL as one of the options. Use this instead of a
with null=True
. The default form widget for this field is a
PositiveIntegerField
class PositiveIntegerField(
[
**options
]
)
Like an
, but must be either positive or zero (0). The value 0 is accepted for backward compatibility
reasons.
PositiveSmallIntegerField
class PositiveSmallIntegerField(
[
**options
]
)
Like a
, but only allows values under a certain (database-dependent) point. Values up to
32767 are safe in all databases supported by Django.
SlugField
class SlugField(
[ max_length=50 , **options
]
)
is a newspaper term. A slug is a short label for something, containing only letters, numbers, underscores or hyphens. They’re generally used in URLs.
Like a CharField, you can specify
(read the note about database portability and
in that section, too). If
is not specified, Django will use a default length of 50.
Implies setting
to True.
It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using
SmallIntegerField
class SmallIntegerField(
[
**options
]
)
Like an
, but only allows values under a certain (database-dependent) point. Values from -32768 to
32767 are safe in all databases supported by Django.
918 Chapter 6. API Reference
Django Documentation, Release 1.5.12
TextField
class TextField(
[
**options
]
)
A large text field. The default form widget for this field is a
MySQL users
If you are using this field with MySQLdb 1.2.1p2 and the utf8_bin collation (which is not the default), there are some issues to be aware of. Refer to the
for details.
TimeField
class TimeField(
[ auto_now=False , auto_now_add=False, **options
]
)
A time, represented in Python by a datetime.time instance. Accepts the same auto-population options as
The default form widget for this field is a
. The admin adds some JavaScript shortcuts.
URLField
class URLField(
[ max_length=200 , **options
]
)
A
for a URL.
The default form widget for this field is a
Like all
subclasses,
takes the optional
argument. If you don’t specify
max_length , a default of 200 is used.
The current value of the field will be displayed as a clickable link above the input widget.
Relationship fields
Django also defines a set of fields that represent relations.
ForeignKey
class ForeignKey(othermodel
[
, **options
]
)
A many-to-one relationship. Requires a positional argument: the class to which the model is related. To create a recursive relationship – an object that has a many-to-one relationship with itself – use models.ForeignKey('self').
If you need to create a relationship on a model that has not yet been defined, you can use the name of the model, rather than the model object itself:
class Car
(models.Model): manufacturer = models.ForeignKey( 'Manufacturer' )
# ...
class Manufacturer
(models.Model):
# ...
6.11. Models 919
Django Documentation, Release 1.5.12
To refer to models defined in another application, you can explicitly specify a model with the full application label.
For example, if the Manufacturer model above is defined in another application called production, you’d need to use:
class Car
(models.Model): manufacturer = models.ForeignKey( 'production.Manufacturer' )
This sort of reference can be useful when resolving circular import dependencies between two applications.
A database index is automatically created on the ForeignKey. You can disable this by setting
to
False
. You may want to avoid the overhead of an index if you are creating a foreign key for consistency rather than joins, or if you will be creating an alternative index like a partial or multiple column index.
Database Representation
Behind the scenes, Django appends "_id" to the field name to create its database column name. In the above example, the database table for the Car model will have a manufacturer_id column. (You can change this explicitly by specifying
) However, your code should never have to deal with the database column name, unless you
write custom SQL. You’ll always deal with the field names of your model object.
Arguments
accepts an extra set of arguments – all optional – that define the details of how the relation works.
ForeignKey.limit_choices_to
A dictionary of lookup arguments and values (see
Making queries ) that limit the available admin or
choices for this object. For example: staff_member = models.ForeignKey(User, limit_choices_to={ 'is_staff' : True}) causes the corresponding field on the ModelForm to list only Users that have is_staff=True.
Instead of a dictionary this can also be a
object for more
complex queries . However, if limit_choices_to
is a
object then it will only have an effect on the choices available in the admin when the field is not listed in raw_id_fields in the ModelAdmin for the model.
ForeignKey.related_name
The name to use for the relation from the related object back to this one. See the
for a full explanation and example. Note that you must set this value when defining relations on
and when you do so
is available.
If you’d prefer Django not to create a backwards relation, set related_name to '+' or end it with '+'. For example, this will ensure that the User model won’t have a backwards relation to this model: user = models.ForeignKey(User, related_name= '+' )
ForeignKey.to_field
The field on the related object that the relation is to. By default, Django uses the primary key of the related object.
ForeignKey.on_delete
When an object referenced by a
is deleted, Django by default emulates the behavior of the SQL constraint ON DELETE CASCADE and also deletes the object containing the ForeignKey. This behavior can be overridden by specifying the
argument. For example, if you have a nullable
and you want it to be set null when the referenced object is deleted:
920 Chapter 6. API Reference
Django Documentation, Release 1.5.12
user = models.ForeignKey(User, blank=True, null=True, on_delete=models.SET_NULL)
The possible values for
are found in
• CASCADE
Cascade deletes; the default.
• PROTECT
Prevent deletion of the referenced object by raising
• SET_NULL
Set the
null; this is only possible if
is True.
• SET_DEFAULT
Set the
to its default value; a default for the
must be set.
• SET()
Set the
to the value passed to
, or if a callable is passed in, the result of calling it.
In most cases, passing a callable will be necessary to avoid executing queries at the time your models.py
is imported:
def get_sentinel_user
():
return
User.objects.get_or_create(username= 'deleted' )[ 0 ]
class MyModel
(models.Model): user = models.ForeignKey(User, on_delete=models.SET(get_sentinel_user))
• DO_NOTHING
Take no action.
If your database backend enforces referential integrity, this will cause an
unless you manually add a SQL ON DELETE constraint to the database field (perhaps using
ManyToManyField
class ManyToManyField(othermodel
[
, **options
]
)
A many-to-many relationship. Requires a positional argument: the class to which the model is related, which works exactly the same as it does for
and
relationships.
Related objects can be added, removed, or created with the field’s
Database Representation
Behind the scenes, Django creates an intermediary join table to represent the many-to-many relationship. By default, this table name is generated using the name of the many-to-many field and the name of the table for the model that contains it. Since some databases don’t support table names above a certain length, these table names will be automatically truncated to 64 characters and a uniqueness hash will be used. This means you might see table names like author_books_9cdf4; this is perfectly normal. You can manually provide the name of the join table using the
option.
Arguments
accepts an extra set of arguments – all optional – that control how the relationship functions.
6.11. Models 921
Django Documentation, Release 1.5.12
ManyToManyField.related_name
Same as
If you have more than one ManyToManyField pointing to the same model and want to suppress the backwards relations, set each related_name to a unique value ending with '+': users = models.ManyToManyField(User, related_name= 'u+' ) referents = models.ManyToManyField(User, related_name= 'ref+' )
ManyToManyField.limit_choices_to
Same as
limit_choices_to has no effect when used on a ManyToManyField with a custom intermediate table specified using the
parameter.
ManyToManyField.symmetrical
Only used in the definition of ManyToManyFields on self. Consider the following model:
class Person
(models.Model): friends = models.ManyToManyField( "self" )
When Django processes this model, it identifies that it has a
on itself, and as a result, it doesn’t add a person_set attribute to the Person class. Instead, the
is assumed to be symmetrical – that is, if I am your friend, then you are my friend.
If you do not want symmetry in many-to-many relationships with self, set
to False. This will force Django to add the descriptor for the reverse relationship, allowing
relationships to be non-symmetrical.
ManyToManyField.through
Django will automatically generate a table to manage many-to-many relationships. However, if you want to manually specify the intermediary table, you can use the
option to specify the Django model that represents the intermediate table that you want to use.
The most common use for this option is when you want to associate
extra data with a many-to-many relationship .
ManyToManyField.db_table
The name of the table to create for storing the many-to-many data. If this is not provided, Django will assume a default name based upon the names of: the table for the model defining the relationship and the name of the field itself.
OneToOneField
class OneToOneField(othermodel
[
, parent_link=False, **options
]
)
A one-to-one relationship. Conceptually, this is similar to a
with
side of the relation will directly return a single object.
This is most useful as the primary key of a model which “extends” another model in some way;
is implemented by adding an implicit one-to-one relation from the child model to the parent model, for example.
One positional argument is required: the class to which the model will be related. This works exactly the same as it does for
, including all the options regarding recursive
and
relationships.
If you do not specify the the
argument for the OneToOneField, Django will use the lower-case name of the current model as default value.
With the following example:
922 Chapter 6. API Reference
Django Documentation, Release 1.5.12
from
django.db
import
models
from
django.contrib.auth.models
import
User
class MySpecialUser
(models.Model): user = models.OneToOneField(User) supervisor = models.OneToOneField(User, related_name= 'supervisor_of' ) your resulting User model will have the following attributes:
>>> user = User.objects.get(pk= 1 )
>>> hasattr (user, 'myspecialuser' )
True
>>> hasattr (user, 'supervisor_of' )
True
Additionally, OneToOneField accepts all of the extra arguments accepted by
ment:
OneToOneField.parent_link
When True and used in a model which inherits from another (concrete) model, indicates that this field should be used as the link back to the parent class, rather than the extra OneToOneField which would normally be implicitly created by subclassing.
See
for usage examples of OneToOneField.
Related objects reference
class RelatedManager
A “related manager” is a manager used in a one-to-many or many-to-many related context. This happens in two cases:
•The “other side” of a
relation. That is:
class Reporter
(models.Model):
...
class Article
(models.Model): reporter = models.ForeignKey(Reporter)
In the above example, the methods below will be available on the manager reporter.article_set.
•Both sides of a
relation:
class Topping
(models.Model):
...
class Pizza
(models.Model): toppings = models.ManyToManyField(Topping)
In this example, the methods below will be available both on topping.pizza_set and on pizza.
toppings
.
These related managers have some extra methods:
add
( obj1
[
, obj2, ...
]
)
Adds the specified model objects to the related object set.
Example:
6.11. Models 923
Django Documentation, Release 1.5.12
924
>>> b = Blog.objects.get( id
=
1 )
>>> e = Entry.objects.get( id
=
234 )
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
In the example above, e.save() is called to perform the update. Using add() with a many-tomany relationship, however, will not call any save() methods, but rather create the relationships using
. If you need to execute some custom logic when a relationship is created,
listen to the
signal.
create
(
**kwargs)
Creates a new object, saves it and puts it in the related object set. Returns the newly created object:
>>> b = Blog.objects.get( id
=
1 )
>>> e = b.entry_set.create(
...
headline= 'Hello' ,
...
...
...
) body_text= 'Hi' , pub_date=datetime.date( 2005 , 1 , 1 )
# No need to call e.save() at this point -- it's already been saved.
This is equivalent to (but much simpler than):
>>> b = Blog.objects.get( id
=
1 )
>>> e = Entry(
...
...
...
blog=b, headline= 'Hello' body_text= 'Hi' ,
,
...
...
) pub_date=datetime.date(
>>> e.save(force_insert=True)
2005 , 1 , 1 )
Note that there’s no need to specify the keyword argument of the model that defines the relationship. In the above example, we don’t pass the parameter blog to create(). Django figures out that the new
Entry object’s blog field should be set to b.
remove
( obj1
[
, obj2, ...
]
)
Removes the specified model objects from the related object set:
>>> b = Blog.objects.get( id
=
1 )
>>> e = Entry.objects.get( id
=
234 )
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
Similar to
, e.save() is called in the example above to perform the update. Using remove()
with a many-to-many relationship, however, will delete the relationships using
which means no model save() methods are called; listen to the
signal if you wish to execute custom code when a relationship is deleted.
For
objects, this method only exists if null=True. If the related field can’t be set to None
(NULL), then an object can’t be removed from a relation without being added to another. In the above example, removing e from b.entry_set() is equivalent to doing e.blog = None, and because the blog
doesn’t have null=True, this is invalid.
clear
()
Removes all objects from the related object set:
>>> b = Blog.objects.get( id
=
1 )
>>> b.entry_set.clear()
Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note this doesn’t delete the related objects – it just disassociates them.
Just like remove(), clear() is only available on
Model Meta options
This document explains all the possible
that you can give your model in its internal class Meta.
Available Meta options abstract
Options.abstract
If abstract = True, this model will be an
app_label
Options.app_label
If a model exists outside of the standard models.py (for instance, if the app’s models are in submodules of myapp.models
), the model must define which app it is part of: app_label = 'myapp'
db_table
Options.db_table
The name of the database table to use for the model: db_table = 'music_album'
Table names
To save you time, Django automatically derives the name of the database table from the name of your model class and the app that contains it. A model’s database table name is constructed by joining the model’s “app label” – the name you used in
– to the model’s class name, with an underscore between them.
For example, if you have an app bookstore (as created by manage.py startapp bookstore), a model defined as class Book will have a database table named bookstore_book.
To override the database table name, use the db_table parameter in class Meta.
If your database table name is an SQL reserved word, or contains characters that aren’t allowed in Python variable names – notably, the hyphen – that’s OK. Django quotes column and table names behind the scenes.
Use lowercase table names for MySQL
It is strongly advised that you use lowercase table names when you override the table name via db_table, particularly if you are using the MySQL backend. See the
for more details.
6.11. Models 925
Django Documentation, Release 1.5.12
Table name quoting for Oracle
In order to to meet the 30-char limitation Oracle has on table names, and match the usual conventions for Oracle databases, Django may shorten table names and turn them all-uppercase. To prevent such transformations, use a quoted name as the value for db_table: db_table = '"name_left_in_lowercase"'
Such quoted names can also be used with Django’s other supported database backends; except for Oracle, however, the quotes have no effect. See the
for more details.
db_tablespace
Options.db_tablespace
The name of the
to use for this model.
The default is the project’s
setting, if set. If the backend doesn’t support tablespaces, this option is ignored.
get_latest_by
Options.get_latest_by
The name of an orderable field in the model, typically a
. This specifies the default field to use in your model
method.
Example: get_latest_by = "order_date"
See the
docs for more.
managed
Options.managed
Defaults to True, meaning Django will create the appropriate database tables in
and remove them as part of a
management command. That is, Django manages the database tables’ lifecycles.
If False, no database table creation or deletion operations will be performed for this model. This is useful if the model represents an existing table or a database view that has been created by some other means. This is the only difference when managed=False. All other aspects of model handling are exactly the same as normal.
This includes
1.Adding an automatic primary key field to the model if you don’t declare it. To avoid confusion for later code readers, it’s recommended to specify all the columns from the database table you are modeling when using unmanaged models.
2.If a model with managed=False contains a
that points to another unmanaged model, then the intermediate table for the many-to-many join will also not be created. However, the intermediary table between one managed and one unmanaged model will be created.
If you need to change this default behavior, create the intermediary table as an explicit model (with managed set as needed) and use the
attribute to make the relation use your custom model.
926 Chapter 6. API Reference
Django Documentation, Release 1.5.12
For tests involving models with managed=False, it’s up to you to ensure the correct tables are created as part of the test setup.
If you’re interested in changing the Python-level behavior of a model class, you could use managed=False and create a copy of an existing model. However, there’s a better approach for that situation:
order_with_respect_to
Options.order_with_respect_to
Marks this object as “orderable” with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object. For example, if an Answer relates to a Question object, and a question has more than one answer, and the order of answers matters, you’d do this:
class Answer
(models.Model): question = models.ForeignKey(Question)
# ...
class Meta
: order_with_respect_to = 'question'
When order_with_respect_to is set, two additional methods are provided to retrieve and to set the order of the related objects: get_RELATED_order() and set_RELATED_order(), where RELATED is the lowercased model name. For example, assuming that a Question object has multiple related Answer objects, the list returned contains the primary keys of the related Answer objects:
>>> question = Question.objects.get( id
=
1 )
>>> question.get_answer_order()
[1, 2, 3]
The order of a Question object’s related Answer objects can be set by passing in a list of Answer primary keys:
>>> question.set_answer_order([ 3 , 1 , 2 ])
The related objects also get two methods, get_next_in_order() and get_previous_in_order(), which can be used to access those objects in their proper order. Assuming the Answer objects are ordered by id :
>>> answer = Answer.objects.get( id
=
2 )
>>> answer.get_next_in_order()
<Answer: 3>
>>> answer.get_previous_in_order()
<Answer: 1>
Changing order_with_respect_to order_with_respect_to adds an additional field/database column named _order, so be sure to handle that as you would any other change to your models if you add or change order_with_respect_to after your initial
6.11. Models 927
Django Documentation, Release 1.5.12
ordering
Options.ordering
The default ordering for the object, for use when obtaining lists of objects: ordering = [ '-order_date' ]
This is a tuple or list of strings. Each string is a field name with an optional “-” prefix, which indicates descending order. Fields without a leading “-” will be ordered ascending. Use the string ”?” to order randomly.
For example, to order by a pub_date field ascending, use this: ordering = [ 'pub_date' ]
To order by pub_date descending, use this: ordering = [ '-pub_date' ]
To order by pub_date descending, then by author ascending, use this: ordering = [ '-pub_date' , 'author' ]
The Django admin honors all elements in the list/tuple; before 1.4, only the first one was respected.
permissions
Options.permissions
Extra permissions to enter into the permissions table when creating this object. Add, delete and change permissions are automatically created for each object that has admin set. This example specifies an extra permission, can_deliver_pizzas : permissions = (( "can_deliver_pizzas" , "Can deliver pizzas" ),)
This is a list or tuple of 2-tuples in the format (permission_code, human_readable_permission_name) .
proxy
Options.proxy
If proxy = True, a model which subclasses another model will be treated as a
unique_together
Options.unique_together
Sets of field names that, taken together, must be unique: unique_together = (( "driver" , "restaurant" ),)
This is a tuple of tuples that must be unique when considered together. It’s used in the Django admin and is enforced at the database level (i.e., the appropriate UNIQUE statements are included in the CREATE TABLE statement).
For convenience, unique_together can be a single tuple when dealing with a single set of fields:
928 Chapter 6. API Reference
Django Documentation, Release 1.5.12
unique_together = ( "driver" , "restaurant" )
A
cannot be included in unique_together. (It’s not clear what that would even mean!) If you need to validate uniqueness related to a
, try using a signal or an explicit
model.
index_together
Options.index_together
Sets of field names that, taken together, are indexed: index_together = [
[ "pub_date" , "deadline" ],
]
This list of fields will be indexed together (i.e. the appropriate CREATE INDEX statement will be issued.)
verbose_name
Options.verbose_name
A human-readable name for the object, singular: verbose_name = "pizza"
If this isn’t given, Django will use a munged version of the class name: CamelCase becomes camel case.
verbose_name_plural
Options.verbose_name_plural
The plural name for the object: verbose_name_plural = "stories"
If this isn’t given, Django will use
+ "s".
Model instance reference
This document describes the details of the Model API. It builds on the material presented in the
and
guides, so you’ll probably want to read and understand those documents before reading this one.
Throughout this reference we’ll use the
presented in the
Creating objects
To create a new instance of a model, just instantiate it like any other Python class: class Model(**kwargs)
The keyword arguments are simply the names of the fields you’ve defined on your model. Note that instantiating a model in no way touches your database; for that, you need to
6.11. Models 929
Django Documentation, Release 1.5.12
Note: You may be tempted to customize the model by overriding the __init__ method. If you do so, however, take care not to change the calling signature as any change may prevent the model instance from being saved. Rather than overriding __init__, try using one of these approaches:
1. Add a classmethod on the model class:
class Book
(models.Model): title = models.CharField(max_length= 100 )
@classmethod
def create
( cls , title): book = cls (title=title)
# do something with the book
return
book book = Book.create( "Pride and Prejudice" )
2. Add a method on a custom manager (usually preferred):
class BookManager
(models.Manager):
def create_book
( self , title): book = self
.
create(title=title)
# do something with the book
return
book
class Book
(models.Model): title = models.CharField(max_length= 100 ) objects = BookManager() book = Book.objects.create_book( "Pride and Prejudice" )
Validating objects
There are three steps involved in validating a model:
1. Validate the model fields -
2. Validate the model as a whole -
3. Validate the field uniqueness -
All three steps are performed when you call a model’s
method.
When you use a
will perform these validation steps for all the fields that are included on the form. See the
for more information. You should only need to call a model’s
method if you plan to handle validation errors yourself, or if you have excluded fields from the
that require validation.
Model.full_clean( exclude=None)
This method calls
Model.clean_fields() , Model.clean() , and Model.validate_unique() , in that
order and raises a
that has a message_dict attribute containing errors from all three stages.
The optional exclude argument can be used to provide a list of field names that can be excluded from validation and cleaning.
uses this argument to exclude fields that aren’t present on your form from being validated since any errors raised could not be corrected by the user.
930 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note that full_clean() will not be called automatically when you call your model’s
method, nor as a result of
validation. In the case of
validation,
clean() , and Model.validate_unique()
are all called individually.
You’ll need to call full_clean manually when you want to run one-step model validation for your own manually created models. For example:
try
: article.full_clean()
except
ValidationError as e:
# Do something based on the errors contained in e.message_dict.
# Display them to a user, or handle them programatically.
pass
The first step full_clean() performs is to clean each individual field.
Model.clean_fields( exclude=None)
This method will validate all fields on your model. The optional exclude argument lets you provide a list of field names to exclude from validation. It will raise a
if any fields fail validation.
The second step full_clean() performs is to call
. This method should be overridden to
perform custom validation on your model.
Model.clean()
This method should be used to provide custom model validation, and to modify attributes on your model if desired.
For instance, you could use it to automatically provide a value for a field, or to do validation that requires access to more than a single field:
def clean
( self ):
from
django.core.exceptions
import
ValidationError
# Don't allow draft entries to have a pub_date.
if
self
.
status == 'draft'
and
self
.
pub_date is not None:
raise
ValidationError( 'Draft entries may not have a publication date.' )
# Set the pub_date for published items if it hasn't been set already.
if
self
.
status == 'published'
and
self
.
pub_date is None: self
.
pub_date = datetime.date.today()
Any
exceptions raised by Model.clean() will be stored in a special key error dictionary key, NON_FIELD_ERRORS, that is used for errors that are tied to the entire model instead of to a specific field:
from
django.core.exceptions
import
ValidationError, NON_FIELD_ERRORS
try
: article.full_clean()
except
ValidationError as e: non_field_errors = e.message_dict[NON_FIELD_ERRORS]
Finally, full_clean() will check any unique constraints on your model.
Model.validate_unique( exclude=None)
This method is similar to
, but validates all uniqueness constraints on your model instead of
individual field values. The optional exclude argument allows you to provide a list of field names to exclude from validation. It will raise a
if any fields fail validation.
Note that if you provide an exclude argument to validate_unique(), any
constraint involving one of the fields you provided will not be checked.
6.11. Models 931
Django Documentation, Release 1.5.12
Saving objects
To save an object back to the database, call save():
Model.save(
[ force_insert=False , force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None
]
)
If you want customized saving behavior, you can override this save() method. See
Overriding predefined model methods
for more details.
The model save process also has some subtleties; see the sections below.
Auto-incrementing primary keys
If a model has an
— an auto-incrementing primary key — then that auto-incremented value will be calculated and saved as an attribute on your object the first time you call save():
>>> b2 = Blog(name= 'Cheddar Talk' , tagline= 'Thoughts on cheese.' )
>>> b2.id
>>> b2.save()
# Returns None, because b doesn't have an ID yet.
>>> b2.id # Returns the ID of your new object.
There’s no way to tell what the value of an ID will be before you call save(), because that value is calculated by your database, not by Django.
For convenience, each model has an
named id by default unless you explicitly specify primary_key=True on a field in your model. See the documentation for
for more details.
The pk property
Model.pk
Regardless of whether you define a primary key field yourself, or let Django supply one for you, each model will have a property called pk. It behaves like a normal attribute on the model, but is actually an alias for whichever attribute is the primary key field for the model. You can read and set this value, just as you would for any other attribute, and it will update the correct field in the model.
Explicitly specifying auto-primary-key values
If a model has an
but you want to define a new object’s ID explicitly when saving, just define it explicitly before saving, rather than relying on the auto-assignment of the ID:
>>> b3 = Blog( id
=
3 , name= 'Cheddar Talk' , tagline= 'Thoughts on cheese.' )
>>> b3.id
>>> b3.save()
# Returns 3.
>>> b3.id # Returns 3.
If you assign auto-primary-key values manually, make sure not to use an already-existing primary-key value! If you create a new object with an explicit primary-key value that already exists in the database, Django will assume you’re changing the existing record rather than creating a new one.
Given the above 'Cheddar Talk' blog example, this example would override the previous record in the database: b4 = Blog( id
=
3 , name= 'Not Cheddar' , tagline= 'Anything but cheese.' ) b4.save() # Overrides the previous blog with ID=3!
932 Chapter 6. API Reference
Django Documentation, Release 1.5.12
See
How Django knows to UPDATE vs. INSERT , below, for the reason this happens.
Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when you’re confident you won’t have primary-key collision.
What happens when you save?
When you save an object, Django performs the following steps:
1. Emit a pre-save signal. The
signal django.db.models.signals.pre_save
is sent, allowing any functions listening for that signal to take some customized action.
2. Pre-process the data. Each field on the object is asked to perform any automated data modification that the field may need to perform.
Most fields do no pre-processing — the field data is kept as-is. Pre-processing is only used on fields that have special behavior. For example, if your model has a
with auto_now=True, the pre-save phase will alter the data in the object to ensure that the date field contains the current date stamp. (Our documentation doesn’t yet include a list of all the fields with this “special behavior.”)
3. Prepare the data for the database. Each field is asked to provide its current value in a data type that can be written to the database.
Most fields require no data preparation. Simple data types, such as integers and strings, are ‘ready to write’ as a
Python object. However, more complex data types often require some modification.
For example,
fields use a Python datetime object to store data.
Databases don’t store datetime objects, so the field value must be converted into an ISO-compliant date string for insertion into the database.
4. Insert the data into the database. The pre-processed, prepared data is then composed into an SQL statement for insertion into the database.
5. Emit a post-save signal. The signal
django.db.models.signals.post_save
is sent, allowing any functions listening for that signal to take some customized action.
How Django knows to UPDATE vs. INSERT
You may have noticed Django database objects use the same save() method for creating and changing objects.
Django abstracts the need to use INSERT or UPDATE SQL statements. Specifically, when you call save(), Django follows this algorithm:
• If the object’s primary key attribute is set to a value that evaluates to True (i.e., a value other than None or the empty string), Django executes a SELECT query to determine whether a record with the given primary key already exists.
• If the record with the given primary key does already exist, Django executes an UPDATE query.
• If the object’s primary key attribute is not set, or if it’s set but a record doesn’t exist, Django executes an
INSERT
.
The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the primary-key value is unused. For more on this nuance, see
Explicitly specifying auto-primary-key values
above and
below.
6.11. Models 933
Django Documentation, Release 1.5.12
Forcing an INSERT or UPDATE
In some rare circumstances, it’s necessary to be able to force the
method to perform an SQL INSERT and not fall back to doing an UPDATE. Or vice-versa: update, if possible, but not insert a new row. In these cases you can pass the force_insert=True or force_update=True parameters to the
method. Obviously, passing both parameters is an error: you cannot both insert and update at the same time!
It should be very rare that you’ll need to use these parameters. Django will almost always do the right thing and trying to override that will lead to errors that are difficult to track down. This feature is for advanced use only.
Using update_fields will force an update similarly to force_update.
Updating attributes based on existing fields
Sometimes you’ll need to perform a simple arithmetic task on a field, such as incrementing or decrementing the current value. The obvious way to achieve this is to do something like:
>>> product = Product.objects.get(name= 'Venezuelan Beaver Cheese' )
>>> product.number_sold += 1
>>> product.save()
If the old number_sold value retrieved from the database was 10, then the value of 11 will be written back to the database.
This sequence has a standard update problem in that it contains a race condition. If another thread of execution has already saved an updated value after the current thread retrieved the old value, the current thread will only save the old value plus one, rather than the new (current) value plus one.
The process can be made robust and slightly faster by expressing the update relative to the original field value, rather than as an explicit assignment of a new value. Django provides
for performing this kind of relative update. Using F() expressions, the previous example is expressed as:
>>>
from
django.db.models
import
F
>>> product = Product.objects.get(name= 'Venezuelan Beaver Cheese' )
>>> product.number_sold = F( 'number_sold' ) + 1
>>> product.save()
This approach doesn’t use the initial value from the database. Instead, it makes the database do the update based on whatever value is current at the time that the
is executed.
Once the object has been saved, you must reload the object in order to access the actual value that was applied to the updated field:
>>> product = Products.objects.get(pk=product.pk)
>>> print (product.number_sold)
42
For more details, see the documentation on
and their
Specifying which fields to save
If save() is passed a list of field names in keyword argument update_fields, only the fields named in that list will be updated. This may be desirable if you want to update just one or a few fields on an object. There will be a slight performance benefit from preventing all of the model fields from being updated in the database. For example:
934 Chapter 6. API Reference
Django Documentation, Release 1.5.12
product.name = 'Name changed again' product.save(update_fields=[ 'name' ])
The update_fields argument can be any iterable containing strings. An empty update_fields iterable will skip the save. A value of None will perform an update on all fields.
Specifying update_fields will force an update.
When saving a model fetched through deferred model loading ( only()
or
defer() ) only the fields loaded from
the DB will get updated. In effect there is an automatic update_fields in this case. If you assign or change any deferred field value, the field will be added to the updated fields.
Deleting objects
Model.delete(
[ using=DEFAULT_DB_ALIAS
]
)
Issues a SQL DELETE for the object. This only deletes the object in the database; the Python instance will still exist and will still have data in its fields.
For more details, including how to delete objects in bulk, see
If you want customized deletion behavior, you can override the delete() method. See
Overriding predefined model methods
for more details.
Other model instance methods
A few object methods have special purposes.
__unicode__
Model.__unicode__()
The __unicode__() method is called whenever you call unicode() on an object. Django uses unicode(obj)
(or the related function,
) in a number of places. Most notably, to display an object in the Django admin
site and as the value inserted into a template when it displays an object. Thus, you should always return a nice, human-readable representation of the model from the __unicode__() method.
For example:
class Person
(models.Model): first_name = models.CharField(max_length= 50 ) last_name = models.CharField(max_length= 50 )
def __unicode__
( self ):
return
u'%s %s'
%
( self
.
first_name, self
.
last_name)
If you define a __unicode__() method on your model and not a
method, Django will automatically provide you with a
that calls __unicode__() and then converts the result correctly to a UTF-8 encoded string object. This is recommended development practice: define only __unicode__() and let Django take care of the conversion to string objects when required.
__str__
Model.__str__()
6.11. Models 935
Django Documentation, Release 1.5.12
The __str__() method is called whenever you call str() on an object. The main use for this method directly inside Django is when the repr() output of a model is displayed anywhere (for example, in debugging output). Thus, you should return a nice, human-readable string for the object’s __str__(). It isn’t required to put __str__() methods everywhere if you have sensible
methods.
The previous
example could be similarly written using __str__() like this:
class Person
(models.Model): first_name = models.CharField(max_length= 50 ) last_name = models.CharField(max_length= 50 )
def __str__
( self ):
# Note use of django.utils.encoding.force_bytes() here because
# first_name and last_name will be unicode strings.
return
force_bytes( '%s %s'
%
( self
.
first_name, self
.
last_name))
get_absolute_url
Model.get_absolute_url()
Define a get_absolute_url() method to tell Django how to calculate the canonical URL for an object. To callers, this method should appear to return a string that can be used to refer to the object over HTTP.
For example:
def get_absolute_url
( self ):
return
"/people/%i/"
%
self
.
id
(Whilst this code is correct and simple, it may not be the most portable way to write this kind of method. The
function is usually the best approach.)
For example:
def get_absolute_url
( self ):
return
reverse( 'people.views.details' , args=[ str ( self
.
id)])
One place Django uses get_absolute_url() is in the admin app. If an object defines this method, the objectediting page will have a “View on site” link that will jump you directly to the object’s public view, as given by get_absolute_url()
.
Similarly, a couple of other bits of Django, such as the
when it is defined. If it makes sense for your model’s instances to each have a unique URL, you should define get_absolute_url()
.
It’s good practice to use get_absolute_url() in templates, instead of hard-coding your objects’ URLs. For example, this template code is bad:
<!-- BAD template code. Avoid! -->
< a href
=
"/people/
{{
object.id
}}
/" >
{{
object.name
}}
</ a >
This template code is much better:
< a href
=
"
{{
object.get_absolute_url
}}
" >
{{
object.name
}}
</ a >
The logic here is that if you change the URL structure of your objects, even for something simple such as correcting a spelling error, you don’t want to have to track down every place that the URL might be created. Specify it once, in get_absolute_url() and have all your other code call that one place.
936 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note: The string you return from get_absolute_url() must contain only ASCII characters (required by the
URI specfication,
RFC 2396
) and be URL-encoded, if necessary.
Code and templates calling get_absolute_url() should be able to use the result directly without any further processing. You may wish to use the django.utils.encoding.iri_to_uri() function to help with this if you are using unicode strings containing characters outside the ASCII range at all.
The permalink decorator
Warning: The permalink decorator is no longer recommended. You should use
in the body of your get_absolute_url method instead.
In early versions of Django, there wasn’t an easy way to use URLs defined in URLconf file inside
That meant you would need to define the URL both in URLConf and
. The permalink decorator was added to overcome this DRY principle violation. How-
ever, since the introduction of
there is no reason to use permalink any more.
permalink
()
This decorator takes the name of a URL pattern (either a view name or a URL pattern name) and a list of position or keyword arguments and uses the URLconf patterns to construct the correct, full URL. It returns a string for the correct
URL, with all parameters substituted in the correct positions.
The permalink decorator is a Python-level equivalent to the
template tag and a high-level wrapper for the
function.
An example should make it clear how to use permalink(). Suppose your URLconf contains a line such as:
( r'^people/(\d+)/$' , 'people.views.details' ),
...your model could have a
method that looked like this:
from
django.db
import
models
@models.permalink
def get_absolute_url
( self ):
return
( 'people.views.details' , [ str ( self
.
id)])
Similarly, if you had a URLconf entry that looked like:
( r'/archive/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d{2})/$' , archive_view)
...you could reference this using permalink() as follows:
@models.permalink
def get_absolute_url
( self ):
return
( 'archive_view' , (), {
'year' : self
.
created.year,
'month' : self
.
created.strftime( '%m' ),
'day' : self
.
created.strftime( '%d' )})
Notice that we specify an empty sequence for the second parameter in this case, because we only want to pass keyword parameters, not positional ones.
6.11. Models 937
Django Documentation, Release 1.5.12
In this way, you’re associating the model’s absolute path with the view that is used to display it, without repeating the view’s URL information anywhere. You can still use the
method in templates, as before.
In some cases, such as the use of generic views or the re-use of custom views for multiple models, specifying the view function may confuse the reverse URL matcher (because multiple patterns point to the same view). For that case,
Django has
named URL patterns . Using a named URL pattern, it’s possible to give a name to a pattern, and then
reference the name rather than the view function. A named URL pattern is defined by replacing the pattern tuple by a call to the url function):
from
django.conf.urls
import
url url( r'^people/(\d+)/$' , 'blog_views.generic_detail' , name= 'people_view' ),
...and then using that name to perform the reverse URL resolution instead of the view name:
from
django.db
import
models
@models.permalink
def get_absolute_url
( self ):
return
( 'people_view' , [ str ( self
.
id)])
More details on named URL patterns are in the
Extra instance methods
In addition to
, a model object might have some of the following methods:
Model.get_FOO_display()
For every field that has
set, the object will have a get_FOO_display() method, where FOO is the name of the field. This method returns the “human-readable” value of the field.
For example:
from
django.db
import
models
class Person
(models.Model):
SHIRT_SIZES = (
( u'S' , u'Small' ),
( u'M' , u'Medium' ),
( u'L' , u'Large' ),
) name = models.CharField(max_length= 60 ) shirt_size = models.CharField(max_length= 2 , choices=SHIRT_SIZES)
>>> p = Person(name= "Fred Flintstone" , shirt_size= "L" )
>>> p.save()
>>> p.shirt_size u'L'
>>> p.get_shirt_size_display() u'Large'
Model.get_next_by_FOO(
**kwargs)
Model.get_previous_by_FOO(
**kwargs)
For every
and
that does not have
get_next_by_FOO() and get_previous_by_FOO() methods, where FOO is the name of the field. This
938 Chapter 6. API Reference
Django Documentation, Release 1.5.12
returns the next and previous object with respect to the date field, raising a
exception when appropriate.
Both of these methods will perform their queries using the default manager for the model. If you need to emulate filtering used by a custom manager, or want to perform one-off custom filtering, both methods also accept optional keyword arguments, which should be in the format described in
Note that in the case of identical date values, these methods will use the primary key as a tie-breaker. This guarantees that no records are skipped or duplicated. That also means you cannot use those methods on unsaved objects.
QuerySet API reference
This document describes the details of the QuerySet API. It builds on the material presented in the
and
guides, so you’ll probably want to read and understand those documents before reading this one.
Throughout this reference we’ll use the
presented in the
When QuerySets are evaluated
Internally, a QuerySet can be constructed, filtered, sliced, and generally passed around without actually hitting the database. No database activity actually occurs until you do something to evaluate the queryset.
You can evaluate a QuerySet in the following ways:
• Iteration. A QuerySet is iterable, and it executes its database query the first time you iterate over it. For example, this will print the headline of all entries in the database:
for
e in Entry.objects.all(): print (e.headline)
Note: Don’t use this if all you want to do is determine if at least one result exists. It’s more efficient to use
• Slicing. As explained in
Limiting QuerySets , a QuerySet can be sliced, using Python’s array-slicing syntax.
Slicing an unevaluated QuerySet usually returns another unevaluated QuerySet, but Django will execute the database query if you use the “step” parameter of slice syntax, and will return a list. Slicing a QuerySet that has been evaluated (partially or fully) also returns a list.
• Pickling/Caching. See the following section for details of what is involved when
important thing for the purposes of this section is that the results are read from the database.
• repr(). A QuerySet is evaluated when you call repr() on it. This is for convenience in the Python interactive interpreter, so you can immediately see your results when using the API interactively.
• len(). A QuerySet is evaluated when you call len() on it. This, as you might expect, returns the length of the result list.
Note: Don’t use len() on QuerySets if all you want to do is determine the number of records in the set.
It’s much more efficient to handle a count at the database level, using SQL’s SELECT COUNT(*), and Django provides a count() method for precisely this reason. See count() below.
• list(). Force evaluation of a QuerySet by calling list() on it. For example: entry_list = list (Entry.objects.all())
Be warned, though, that this could have a large memory overhead, because Django will load each element of the list into memory. In contrast, iterating over a QuerySet will take advantage of your database to load data and instantiate objects only as you need them.
6.11. Models 939
Django Documentation, Release 1.5.12
• bool(). Testing a QuerySet in a boolean context, such as using bool(), or, and or an if statement, will cause the query to be executed. If there is at least one result, the QuerySet is True, otherwise False. For example:
if
Entry.objects.filter(headline= "Test" ): print ( "There is at least one Entry with the headline Test" )
Note: Don’t use this if all you want to do is determine if at least one result exists, and don’t need the actual objects. It’s more efficient to use
(see below).
Pickling QuerySets
If you pickle a QuerySet, this will force all the results to be loaded into memory prior to pickling. Pickling is usually used as a precursor to caching and when the cached queryset is reloaded, you want the results to already be present and ready for use (reading from the database can take some time, defeating the purpose of caching). This means that when you unpickle a QuerySet, it contains the results at the moment it was pickled, rather than the results that are currently in the database.
If you only want to pickle the necessary information to recreate the QuerySet from the database at a later time, pickle the query attribute of the QuerySet. You can then recreate the original QuerySet (without any results loaded) using some code like this:
>>>
import
pickle
>>> query = pickle.loads(s)
>>> qs = MyModel.objects.all()
>>> qs.query = query
# Assuming 's' is the pickled string.
# Restore the original 'query'.
The query attribute is an opaque object. It represents the internals of the query construction and is not part of the public API. However, it is safe (and fully supported) to pickle and unpickle the attribute’s contents as described here.
You can’t share pickles between versions
Pickles of QuerySets are only valid for the version of Django that was used to generate them. If you generate a pickle using Django version N, there is no guarantee that pickle will be readable with Django version N+1. Pickles should not be used as part of a long-term archival strategy.
QuerySet API
Though you usually won’t create one manually — you’ll go through a
— here’s the formal declaration of a QuerySet: class QuerySet(
[ model=None , query=None, using=None
]
)
Usually when you’ll interact with a QuerySet you’ll use it by
chaining filters . To make this work, most
QuerySet methods return new querysets. These methods are covered in detail later in this section.
The QuerySet class has two public attributes you can use for introspection:
ordered
True if the QuerySet is ordered — i.e. has an
clause or a default ordering on the model.
False otherwise.
db
The database that will be used if this query is executed now.
940 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note: The query parameter to
exists so that specialized query subclasses such as
can reconstruct internal query state. The value of the parameter is an opaque representation of that query state and is not part of a public API. To put it simply: if you need to ask, you don’t need to use it.
Methods that return new QuerySets
Django provides a range of QuerySet refinement methods that modify either the types of results returned by the
QuerySet or the way its SQL query is executed.
filter filter
(
**kwargs)
Returns a new QuerySet containing objects that match the given lookup parameters.
The lookup parameters (**kwargs) should be in the format described in
below. Multiple parameters are joined via AND in the underlying SQL statement.
exclude exclude
(
**kwargs)
Returns a new QuerySet containing objects that do not match the given lookup parameters.
The lookup parameters (**kwargs) should be in the format described in
below. Multiple parameters are joined via AND in the underlying SQL statement, and the whole thing is enclosed in a NOT().
This example excludes all entries whose pub_date is later than 2005-1-3 AND whose headline is “Hello”:
Entry.objects.exclude(pub_date__gt=datetime.date( 2005 , 1 , 3 ), headline= 'Hello' )
In SQL terms, that evaluates to:
SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello' )
This example excludes all entries whose pub_date is later than 2005-1-3 OR whose headline is “Hello”:
Entry.objects.exclude(pub_date__gt=datetime.date( 2005 , 1 , 3 )).exclude(headline= 'Hello
˓→
' )
In SQL terms, that evaluates to:
SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'
Note the second example is more restrictive.
6.11. Models 941
Django Documentation, Release 1.5.12
annotate annotate
( *args , **kwargs)
Annotates each object in the QuerySet with the provided list of aggregate values (averages, sums, etc) that have been computed over the objects that are related to the objects in the QuerySet. Each argument to annotate() is an annotation that will be added to each object in the QuerySet that is returned.
The aggregation functions that are provided by Django are described in
below.
Annotations specified using keyword arguments will use the keyword as the alias for the annotation. Anonymous arguments will have an alias generated for them based upon the name of the aggregate function and the model field that is being aggregated.
For example, if you were manipulating a list of blogs, you may want to determine how many entries have been made in each blog:
>>> q = Blog.objects.annotate(Count( 'entry' ))
# The name of the first blog
>>> q[ 0 ].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[ 0 ].entry__count
42
The Blog model doesn’t define an entry__count attribute by itself, but by using a keyword argument to specify the aggregate function, you can control the name of the annotation:
>>> q = Blog.objects.annotate(number_of_entries=Count( 'entry' ))
# The number of entries on the first blog, using the name provided
>>> q[ 0 ].number_of_entries
42
For an in-depth discussion of aggregation, see
the topic guide on Aggregation .
order_by order_by
(
*fields)
By default, results returned by a QuerySet are ordered by the ordering tuple given by the ordering option in the model’s Meta. You can override this on a per-QuerySet basis by using the order_by method.
Example:
Entry.objects.filter(pub_date__year= 2005 ).order_by( '-pub_date' , 'headline' )
The result above will be ordered by pub_date descending, then by headline ascending. The negative sign in front of "-pub_date" indicates descending order. Ascending order is implied. To order randomly, use "?", like so:
Entry.objects.order_by( '?' )
Note: order_by('?') queries may be expensive and slow, depending on the database backend you’re using.
To order by a field in a different model, use the same syntax as when you are querying across model relations. That is, the name of the field, followed by a double underscore (__), followed by the name of the field in the new model, and so on for as many models as you want to join. For example:
942 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Entry.objects.order_by( 'blog__name' , 'headline' )
If you try to order by a field that is a relation to another model, Django will use the default ordering on the related model (or order by the related model’s primary key if there is no
specified. For example:
Entry.objects.order_by( 'blog' )
...is identical to:
Entry.objects.order_by( 'blog__id' )
...since the Blog model has no default ordering specified.
Be cautious when ordering by fields in related models if you are also using
See the note in
for an explanation of how related model ordering can change the expected results.
Note: It is permissible to specify a multi-valued field to order the results by (for example, a
field, or the reverse relation of a
field).
Consider this case:
class Event
(Model): parent = models.ForeignKey( 'self' , related_name= 'children' ) date = models.DateField()
Event.objects.order_by( 'children__date' )
Here, there could potentially be multiple ordering data for each Event; each Event with multiple children will be returned multiple times into the new QuerySet that order_by() creates. In other words, using order_by() on the QuerySet could return more items than you were working on to begin with - which is probably neither expected nor useful.
Thus, take care when using multi-valued field to order the results. If you can be sure that there will only be one ordering piece of data for each of the items you’re ordering, this approach should not present problems. If not, make sure the results are what you expect.
There’s no way to specify whether ordering should be case sensitive. With respect to case-sensitivity, Django will order results however your database backend normally orders them.
If you don’t want any ordering to be applied to a query, not even the default ordering, call
with no parameters.
You can tell if a query is ordered or not by checking the
attribute, which will be True if the
QuerySet has been ordered in any way.
reverse reverse
()
Use the reverse() method to reverse the order in which a queryset’s elements are returned. Calling reverse() a second time restores the ordering back to the normal direction.
To retrieve the “last” five items in a queryset, you could do this: my_queryset.reverse()[: 5 ]
6.11. Models 943
Django Documentation, Release 1.5.12
Note that this is not quite the same as slicing from the end of a sequence in Python. The above example will return the last item first, then the penultimate item and so on. If we had a Python sequence and looked at seq[-5:], we would see the fifth-last item first. Django doesn’t support that mode of access (slicing from the end), because it’s not possible to do it efficiently in SQL.
Also, note that reverse() should generally only be called on a QuerySet which has a defined ordering (e.g., when querying against a model which defines a default ordering, or when using
is defined for a given QuerySet, calling reverse() on it has no real effect (the ordering was undefined prior to calling reverse(), and will remain undefined afterward).
distinct distinct
(
[
*fields
]
)
Returns a new QuerySet that uses SELECT DISTINCT in its SQL query. This eliminates duplicate rows from the query results.
By default, a QuerySet will not eliminate duplicate rows. In practice, this is rarely a problem, because simple queries such as Blog.objects.all() don’t introduce the possibility of duplicate result rows. However, if your query spans multiple tables, it’s possible to get duplicate results when a QuerySet is evaluated. That’s when you’d use distinct().
Note: Any fields used in an
call are included in the SQL SELECT columns. This can sometimes lead to unexpected results when used in conjunction with distinct(). If you order by fields from a related model, those fields will be added to the selected columns and they may make otherwise duplicate rows appear to be distinct. Since the extra columns don’t appear in the returned results (they are only there to support ordering), it sometimes looks like non-distinct results are being returned.
Similarly, if you use a
query to restrict the columns selected, the columns used in any
(or default model ordering) will still be involved and may affect uniqueness of the results.
The moral here is that if you are using distinct() be careful about ordering by related models. Similarly, when using distinct() and
together, be careful when ordering by fields not in the
call.
As of Django 1.4, you can pass positional arguments (*fields) in order to specify the names of fields to which the
DISTINCT should apply. This translates to a SELECT DISTINCT ON SQL query.
Here’s the difference. For a normal distinct() call, the database compares each field in each row when determining which rows are distinct. For a distinct() call with specified field names, the database will only compare the specified field names.
Note: This ability to specify field names is only available in PostgreSQL.
Note: When you specify field names, you must provide an order_by() in the QuerySet, and the fields in order_by() must start with the fields in distinct(), in the same order.
For example, SELECT DISTINCT ON (a) gives you the first row for each value in column a. If you don’t specify an order, you’ll get some arbitrary row.
Examples:
>>> Author.objects.distinct()
[...]
944 Chapter 6. API Reference
Django Documentation, Release 1.5.12
>>> Entry.objects.order_by( 'pub_date' ).distinct( 'pub_date' )
[...]
>>> Entry.objects.order_by( 'blog' ).distinct( 'blog' )
[...]
>>> Entry.objects.order_by( 'author' , 'pub_date' ).distinct( 'author' , 'pub_date' )
[...]
>>> Entry.objects.order_by( 'blog__name' , 'mod_date' ).distinct( 'blog__name' , 'mod_date
˓→
' )
[...]
>>> Entry.objects.order_by( 'author' , 'pub_date' ).distinct( 'author' )
[...]
values values
( *fields)
Returns a ValuesQuerySet — a QuerySet subclass that returns dictionaries when used as an iterable, rather than model-instance objects.
Each of those dictionaries represents an object, with the keys corresponding to the attribute names of model objects.
This example compares the dictionaries of values() with the normal model objects:
# This list contains a Blog object.
>>>
Blog.objects.filter(name__startswith= 'Beatles' )
[<Blog: Beatles Blog>]
# This list contains a dictionary.
>>>
Blog.objects.filter(name__startswith= 'Beatles' ).values()
[{ 'id' : 1 , 'name' : 'Beatles Blog' , 'tagline' : 'All the latest Beatles news.' }]
The values() method takes optional positional arguments, *fields, which specify field names to which the
SELECT should be limited. If you specify the fields, each dictionary will contain only the field keys/values for the fields you specify. If you don’t specify the fields, each dictionary will contain a key and value for every field in the database table.
Example:
>>> Blog.objects.values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
>>> Blog.objects.values( 'id' , 'name' )
[{'id': 1, 'name': 'Beatles Blog'}]
A few subtleties that are worth mentioning:
• If you have a field called foo that is a
, the default values() call will return a dictionary
key called foo_id, since this is the name of the hidden model attribute that stores the actual value (the foo attribute refers to the related model). When you are calling values() and passing in field names, you can pass in either foo or foo_id and you will get back the same thing (the dictionary key will match the field name you passed in).
For example:
6.11. Models 945
Django Documentation, Release 1.5.12
>>> Entry.objects.values()
[{'blog_id': 1, 'headline': u'First Entry', ...}, ...]
>>> Entry.objects.values( 'blog' )
[{'blog': 1}, ...]
>>> Entry.objects.values( 'blog_id' )
[{'blog_id': 1}, ...]
• When using values() together with
, be aware that ordering can affect the results. See the
note in
for details.
• If you use a values() clause after an
call, any fields defined by a select argument in the
must be explicitly included in the values() call. Any
call made after a values() call will have its extra selected fields ignored.
A ValuesQuerySet is useful when you know you’re only going to need values from a small number of the available fields and you won’t need the functionality of a model instance object. It’s more efficient to select only the fields you need to use.
Finally, note a ValuesQuerySet is a subclass of QuerySet, so it has all methods of QuerySet. You can call filter() on it, or order_by(), or whatever. Yes, that means these two calls are identical:
Blog.objects.values().order_by( 'id' )
Blog.objects.order_by( 'id' ).values()
The people who made Django prefer to put all the SQL-affecting methods first, followed (optionally) by any outputaffecting methods (such as values()), but it doesn’t really matter. This is your chance to really flaunt your individualism.
You can also refer to fields on related models with reverse relations through OneToOneField, ForeignKey and
ManyToManyField attributes:
Blog.objects.values( 'name' , 'entry__headline' )
[{ 'name' : 'My blog' , 'entry__headline' : 'An entry' },
{ 'name' : 'My blog' , 'entry__headline' : 'Another entry' }, ...]
Warning: Because
attributes and reverse relations can have multiple related rows, including these can have a multiplier effect on the size of your result set. This will be especially pronounced if you include multiple such fields in your values() query, in which case all possible combinations will be returned.
values_list values_list
(
*fields)
This is similar to values() except that instead of returning dictionaries, it returns tuples when iterated over. Each tuple contains the value from the respective field passed into the values_list() call — so the first item is the first field, etc. For example:
>>> Entry.objects.values_list( 'id' , 'headline' )
[(1, u'First entry'), ...]
If you only pass in a single field, you can also pass in the flat parameter. If True, this will mean the returned results are single values, rather than one-tuples. An example should make the difference clearer:
946 Chapter 6. API Reference
Django Documentation, Release 1.5.12
>>> Entry.objects.values_list( 'id' ).order_by( 'id' )
[(1,), (2,), (3,), ...]
>>> Entry.objects.values_list( 'id' , flat=True).order_by( 'id' )
[1, 2, 3, ...]
It is an error to pass in flat when there is more than one field.
If you don’t pass any values to values_list(), it will return all the fields in the model, in the order they were declared.
dates dates
( field , kind, order=’ASC’)
Returns a DateQuerySet — a QuerySet that evaluates to a list of datetime.datetime objects representing all available dates of a particular kind within the contents of the QuerySet.
field should be the name of a DateField or DateTimeField of your model.
kind should be either "year", "month" or "day". Each datetime.datetime object in the result list is
“truncated” to the given type.
• "year" returns a list of all distinct year values for the field.
• "month" returns a list of all distinct year/month values for the field.
• "day" returns a list of all distinct year/month/day values for the field.
order
, which defaults to 'ASC', should be either 'ASC' or 'DESC'. This specifies how to order the results.
Examples:
>>> Entry.objects.dates( 'pub_date' , 'year' )
[datetime.datetime(2005, 1, 1)]
>>> Entry.objects.dates( 'pub_date' , 'month' )
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
>>> Entry.objects.dates( 'pub_date' , 'day' )
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
>>> Entry.objects.dates( 'pub_date' , 'day' , order= 'DESC' )
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains= 'Lennon' ).dates( 'pub_date' , 'day' )
[datetime.datetime(2005, 3, 20)]
Warning: When
is enabled, Django uses UTC in the database connection, which means the aggregation is performed in UTC. This is a known limitation of the current implementation.
none none
()
Returns an EmptyQuerySet — a QuerySet subclass that always evaluates to an empty list. This can be used in cases where you know that you should return an empty result set and your caller is expecting a QuerySet object
(instead of returning an empty list, for example.)
Examples:
6.11. Models 947
Django Documentation, Release 1.5.12
>>> Entry.objects.none()
[]
all all
()
Returns a copy of the current QuerySet (or QuerySet subclass). This can be useful in situations where you might want to pass in either a model manager or a QuerySet and do further filtering on the result. After calling all() on either object, you’ll definitely have a QuerySet to work with.
select_related select_related
()
Returns a QuerySet that will automatically “follow” foreign-key relationships, selecting that additional relatedobject data when it executes its query. This is a performance booster which results in (sometimes much) larger queries but means later use of foreign-key relationships won’t require database queries.
The following examples illustrate the difference between plain lookups and select_related() lookups. Here’s standard lookup:
# Hits the database.
e = Entry.objects.get( id
=
5 )
# Hits the database again to get the related Blog object.
b = e.blog
And here’s select_related lookup:
# Hits the database.
e = Entry.objects.select_related().get( id
=
5 )
# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog select_related() follows foreign keys as far as possible. If you have the following models:
class City
(models.Model):
# ...
pass class Person
(models.Model):
# ...
hometown = models.ForeignKey(City)
class Book
(models.Model):
# ...
author = models.ForeignKey(Person)
...then a call to Book.objects.select_related().get(id=4) will cache the related Person and the related City:
948 Chapter 6. API Reference
Django Documentation, Release 1.5.12
b = Book.objects.select_related().get( id
=
4 ) p = b.author c = p.hometown
# Doesn't hit the database.
# Doesn't hit the database.
b = Book.objects.get( id
=
4 ) # No select_related() in this example.
p = b.author # Hits the database.
c = p.hometown # Hits the database.
Note that, by default, select_related() does not follow foreign keys that have null=True.
Usually, using select_related() can vastly improve performance because your app can avoid many database calls. However, there are times you are only interested in specific related models, or have deeply nested sets of relationships, and in these cases select_related() can be optimized by explicitly passing the related field names you are interested in. Only the specified relations will be followed.
You can even do this for models that are more than one relation away by separating the field names with double underscores, just as for filters. For example, if you have this model:
class Room
(models.Model):
# ...
building = models.ForeignKey(...)
class Group
(models.Model):
# ...
teacher = models.ForeignKey(...) room = models.ForeignKey(Room) subject = models.ForeignKey(...)
...and you only needed to work with the room and subject attributes, you could write this: g = Group.objects.select_related( 'room' , 'subject' )
This is also valid: g = Group.objects.select_related( 'room__building' , 'subject' )
...and would also pull in the building relation.
You can refer to any
or
relation in the list of fields passed to select_related() . This includes foreign keys that have null=True (which are omitted in a no-parameter select_related() call).
It’s an error to use both a list of fields and the depth parameter in the same select_related() call; they are conflicting options.
You can also refer to the reverse direction of a
in the list of fields passed to select_related
— that is, you can traverse a
back to the object on which the field is defined. Instead of specifying the field name, use the
for the field on the related object.
Deprecated since version 1.5: The depth parameter to select_related() has been deprecated. You should replace it with the use of the (*fields) listing specific related fields instead as documented above.
A depth limit of relationships to follow can also be specified: b = Book.objects.select_related(depth= 1 ).get( id
=
4 ) p = b.author # Doesn't hit the database.
c = p.hometown # Requires a database call.
A
is not traversed in the reverse direction if you are performing a depth-based select_related() call.
6.11. Models 949
Django Documentation, Release 1.5.12
prefetch_related prefetch_related
( *lookups)
Returns a QuerySet that will automatically retrieve, in a single batch, related objects for each of the specified lookups.
This has a similar purpose to select_related, in that both are designed to stop the deluge of database queries that is caused by accessing related objects, but the strategy is quite different.
select_related works by creating a SQL join and including the fields of the related object in the SELECT statement. For this reason, select_related gets the related objects in the same database query. However, to avoid the much larger result set that would result from joining across a ‘many’ relationship, select_related is limited to single-valued relationships - foreign key and one-to-one.
prefetch_related
, on the other hand, does a separate lookup for each relationship, and does the ‘joining’ in Python.
This allows it to prefetch many-to-many and many-to-one objects, which cannot be done using select_related, in addition to the foreign key and one-to-one relationships that are supported by select_related
. It also supports prefetching of
and
For example, suppose you have these models:
class Topping
(models.Model): name = models.CharField(max_length= 30 )
class Pizza
(models.Model): name = models.CharField(max_length= 50 ) toppings = models.ManyToManyField(Topping)
def __unicode__
( self ):
return
u"%s (%s)"
%
( self
.
name, u", "
.
join([topping.name
for
topping in self
.
toppings.
˓→ all()])) and run:
>>> Pizza.objects.all()
[u"Hawaiian (ham, pineapple)", u"Seafood (prawns, smoked salmon)"...
The problem with this is that every time Pizza.__unicode__() asks for self.toppings.all() it has to query the database, so Pizza.objects.all() will run a query on the Toppings table for every item in the Pizza
QuerySet
.
We can reduce to just two queries using prefetch_related:
>>> Pizza.objects.all().prefetch_related( 'toppings' )
This implies a self.toppings.all() for each Pizza; now each time self.toppings.all() is called, instead of having to go to the database for the items, it will find them in a prefetched QuerySet cache that was populated in a single query.
That is, all the relevant toppings will have been fetched in a single query, and used to make QuerySets that have a pre-filled cache of the relevant results; these QuerySets are then used in the self.toppings.all() calls.
The additional queries in prefetch_related() are executed after the QuerySet has begun to be evaluated and the primary query has been executed.
Note that the result cache of the primary QuerySet and all specified related objects will then be fully loaded into memory. This changes the typical behavior of QuerySets, which normally try to avoid loading all objects into memory before they are needed, even after a query has been executed in the database.
950 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note: Remember that, as always with QuerySets, any subsequent chained methods which imply a different database query will ignore previously cached results, and retrieve data using a fresh database query. So, if you write the following:
>>> pizzas = Pizza.objects.prefetch_related( 'toppings' )
>>> [ list (pizza.toppings.filter(spicy=True)) for pizza in pizzas]
...then
the fact that pizza.toppings.all() has been prefetched will not help you.
The prefetch_related('toppings') implied pizza.toppings.all()
, but pizza.toppings.
filter() is a new and different query. The prefetched cache can’t help here; in fact it hurts performance, since you have done a database query that you haven’t used. So use this feature with caution!
You can also use the normal join syntax to do related fields of related fields. Suppose we have an additional model to the example above:
class Restaurant
(models.Model): pizzas = models.ManyToMany(Pizza, related_name= 'restaurants' ) best_pizza = models.ForeignKey(Pizza, related_name= 'championed_by' )
The following are all legal:
>>> Restaurant.objects.prefetch_related( 'pizzas__toppings' )
This will prefetch all pizzas belonging to restaurants, and all toppings belonging to those pizzas. This will result in a total of 3 database queries - one for the restaurants, one for the pizzas, and one for the toppings.
>>> Restaurant.objects.prefetch_related( 'best_pizza__toppings' )
This will fetch the best pizza and all the toppings for the best pizza for each restaurant. This will be done in 3 database queries - one for the restaurants, one for the ‘best pizzas’, and one for one for the toppings.
Of course, the best_pizza relationship could also be fetched using select_related to reduce the query count to 2:
>>> Restaurant.objects.select_related( 'best_pizza' ).prefetch_related( 'best_pizza__
˓→ toppings' )
Since the prefetch is executed after the main query (which includes the joins needed by select_related), it is able to detect that the best_pizza objects have already been fetched, and it will skip fetching them again.
Chaining prefetch_related calls will accumulate the lookups that are prefetched.
To clear any prefetch_related behavior, pass None as a parameter:
>>> non_prefetched = qs.prefetch_related(None)
One difference to note when using prefetch_related is that objects created by a query can be shared between the different objects that they are related to i.e. a single Python model instance can appear at more than one point in the tree of objects that are returned. This will normally happen with foreign key relationships. Typically this behavior will not be a problem, and will in fact save both memory and CPU time.
While prefetch_related supports prefetching GenericForeignKey relationships, the number of queries will depend on the data. Since a GenericForeignKey can reference data in multiple tables, one query per table referenced is needed, rather than one query for all the items. There could be additional queries on the ContentType table if the relevant rows have not already been fetched.
prefetch_related in most cases will be implemented using a SQL query that uses the ‘IN’ operator. This means that for a large QuerySet a large ‘IN’ clause could be generated, which, depending on the database, might have
6.11. Models 951
Django Documentation, Release 1.5.12
performance problems of its own when it comes to parsing or executing the SQL query. Always profile for your use case!
Note that if you use iterator() to run the query, prefetch_related() calls will be ignored since these two optimizations do not make sense together.
extra extra
( select=None , where=None, params=None, tables=None, order_by=None, select_params=None)
Sometimes, the Django query syntax by itself can’t easily express a complex WHERE clause. For these edge cases,
Django provides the extra() QuerySet modifier — a hook for injecting specific clauses into the SQL generated by a QuerySet.
By definition, these extra lookups may not be portable to different database engines (because you’re explicitly writing
SQL code) and violate the DRY principle, so you should avoid them if possible.
Specify one or more of params, select, where or tables. None of the arguments is required, but you should use at least one of them.
• select
The select argument lets you put extra fields in the SELECT clause. It should be a dictionary mapping attribute names to SQL clauses to use to calculate that attribute.
Example:
Entry.objects.extra(select={ 'is_recent' : "pub_date > '2006-01-01'" })
As a result, each Entry object will have an extra attribute, is_recent, a boolean representing whether the entry’s pub_date is greater than Jan. 1, 2006.
Django inserts the given SQL snippet directly into the SELECT statement, so the resulting SQL of the above example would be something like:
SELECT blog_entry.*, (pub_date > '2006-01-01' ) AS is_recent
FROM blog_entry;
The next example is more advanced; it does a subquery to give each resulting Blog object an entry_count attribute, an integer count of associated Entry objects:
Blog.objects.extra(
) select={
'entry_count' : 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id
˓→
= blog_blog.id'
},
In this particular case, we’re exploiting the fact that the query will already contain the blog_blog table in its
FROM clause.
The resulting SQL of the above example would be:
SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id =
˓→ blog_blog.id) AS entry_count
FROM blog_blog;
952 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Note that the parentheses required by most database engines around subqueries are not required in Django’s select clauses. Also note that some database backends, such as some MySQL versions, don’t support subqueries.
In some rare cases, you might wish to pass parameters to the SQL fragments in extra(select=...). For this purpose, use the select_params parameter. Since select_params is a sequence and the select attribute is a dictionary, some care is required so that the parameters are matched up correctly with the extra select pieces. In this situation, you should use a
django.utils.datastructures.SortedDict
for the select value, not just a normal Python dictionary.
This will work, for example:
Blog.objects.extra( select=SortedDict([( 'a' , '%s' ), ( 'b' , '%s' )]), select_params=( 'one' , 'two' ))
The only thing to be careful about when using select parameters in extra() is to avoid using the substring
"%%s"
(that’s two percent characters before the s) in the select strings. Django’s tracking of parameters looks for %s and an escaped % character like this isn’t detected. That will lead to incorrect results.
• where / tables
You can define explicit SQL WHERE clauses — perhaps to perform non-explicit joins — by using where. You can manually add tables to the SQL FROM clause by using tables.
where and tables both take a list of strings. All where parameters are “AND”ed to any other search criteria.
Example:
Entry.objects.extra(where=[ "foo='a' OR bar = 'a'" , "baz = 'a'" ])
...translates (roughly) into the following SQL:
SELECT * FROM blog_entry WHERE (foo= 'a' OR bar= 'a' ) AND (baz= 'a' )
Be careful when using the tables parameter if you’re specifying tables that are already used in the query.
When you add extra tables via the tables parameter, Django assumes you want that table included an extra time, if it is already included. That creates a problem, since the table name will then be given an alias. If a table appears multiple times in an SQL statement, the second and subsequent occurrences must use aliases so the database can tell them apart. If you’re referring to the extra table you added in the extra where parameter this is going to cause errors.
Normally you’ll only be adding extra tables that don’t already appear in the query. However, if the case outlined above does occur, there are a few solutions. First, see if you can get by without including the extra table and use the one already in the query. If that isn’t possible, put your extra() call at the front of the queryset construction so that your table is the first use of that table. Finally, if all else fails, look at the query produced and rewrite your where addition to use the alias given to your extra table. The alias will be the same each time you construct the queryset in the same way, so you can rely upon the alias name to not change.
• order_by
If you need to order the resulting queryset using some of the new fields or tables you have included via extra() use the order_by parameter to extra() and pass in a sequence of strings. These strings should either be model fields (as in the normal
method on querysets), of the form table_name.
column_name or an alias for a column that you specified in the select parameter to extra().
For example: q = Entry.objects.extra(select={ 'is_recent' : "pub_date > '2006-01-01'" }) q = q.extra(order_by = [ '-is_recent' ])
6.11. Models 953
Django Documentation, Release 1.5.12
This would sort all the items for which is_recent is true to the front of the result set (True sorts before
False in a descending ordering).
This shows, by the way, that you can make multiple calls to extra() and it will behave as you expect (adding new constraints each time).
• params
The where parameter described above may use standard Python database string placeholders — '%s' to indicate parameters the database engine should automatically quote. The params argument is a list of any extra parameters to be substituted.
Example:
Entry.objects.extra(where=[ 'headline=%s' ], params=[ 'Lennon' ])
Always use params instead of embedding values directly into where because params will ensure values are quoted correctly according to your particular backend. For example, quotes will be escaped correctly.
Bad:
Entry.objects.extra(where=[ "headline='Lennon'" ])
Good:
Entry.objects.extra(where=[ 'headline=%s' ], params=[ 'Lennon' ])
Warning: If you are performing queries on MySQL, note that MySQL’s silent type coercion may cause unexpected results when mixing types. If you query on a string type column, but with an integer value, MySQL will coerce the types of all values in the table to an integer before performing the comparison. For example, if your table contains the values 'abc', 'def' and you query for WHERE mycolumn=0, both rows will match. To prevent this, perform the correct typecasting before using the value in a query.
defer defer
(
*fields)
In some complex data-modeling situations, your models might contain a lot of fields, some of which could contain a lot of data (for example, text fields), or require expensive processing to convert them to Python objects. If you are using the results of a queryset in some situation where you don’t know if you need those particular fields when you initially fetch the data, you can tell Django not to retrieve them from the database.
This is done by passing the names of the fields to not load to defer():
Entry.objects.defer( "headline" , "body" )
A queryset that has deferred fields will still return model instances. Each deferred field will be retrieved from the database if you access that field (one at a time, not all the deferred fields at once).
You can make multiple calls to defer(). Each call adds new fields to the deferred set:
# Defers both the body and headline fields.
Entry.objects.defer( "body" ).filter(rating= 5 ).defer( "headline" )
The order in which fields are added to the deferred set does not matter. Calling defer() with a field name that has already been deferred is harmless (the field will still be deferred).
954 Chapter 6. API Reference
Django Documentation, Release 1.5.12
You can defer loading of fields in related models (if the related models are loading via
using the standard double-underscore notation to separate related fields:
Blog.objects.select_related().defer( "entry__headline" , "entry__body" )
If you want to clear the set of deferred fields, pass None as a parameter to defer():
# Load all fields immediately.
my_queryset.defer(None)
Some fields in a model won’t be deferred, even if you ask for them. You can never defer the loading of the primary key. If you are using
to retrieve related models, you shouldn’t defer the loading of the field that connects from the primary model to the related one, doing so will result in an error.
Note: The defer() method (and its cousin,
, below) are only for advanced use-cases. They provide an
optimization for when you have analyzed your queries closely and understand exactly what information you need and have measured that the difference between returning the fields you need and the full set of fields for the model will be significant.
Even if you think you are in the advanced use-case situation, only use defer() when you cannot, at queryset load time, determine if you will need the extra fields or not. If you are frequently loading and using a particular subset of your data, the best choice you can make is to normalize your models and put the non-loaded data into a separate model
(and database table). If the columns must stay in the one table for some reason, create a model with Meta.managed
= False
(see the
documentation) containing just the fields you normally need to load and use that where you might otherwise call defer(). This makes your code more explicit to the reader, is slightly faster and consumes a little less memory in the Python process.
Note: When calling
for instances with deferred fields, only the loaded fields will be saved. See
for more details.
only only
(
*fields)
The only() method is more or less the opposite of
. You call it with the fields that should not be deferred
when retrieving a model. If you have a model where almost all the fields need to be deferred, using only() to specify the complementary set of fields can result in simpler code.
Suppose you have a model with fields name, age and biography. The following two querysets are the same, in terms of deferred fields:
Person.objects.defer( "age" , "biography" )
Person.objects.only( "name" )
Whenever you call only() it replaces the set of fields to load immediately. The method’s name is mnemonic: only those fields are loaded immediately; the remainder are deferred. Thus, successive calls to only() result in only the final fields being considered:
# This will defer all fields except the headline.
Entry.objects.only( "body" , "rating" ).only( "headline" )
Since defer() acts incrementally (adding fields to the deferred list), you can combine calls to only() and defer() and things will behave logically:
6.11. Models 955
Django Documentation, Release 1.5.12
# Final result is that everything except "headline" is deferred.
Entry.objects.only( "headline" , "body" ).defer( "body" )
# Final result loads headline and body immediately (only() replaces any
# existing set of fields).
Entry.objects.defer( "body" ).only( "headline" , "body" )
All of the cautions in the note for the
documentation apply to only() as well. Use it cautiously and only after exhausting your other options. Also note that using
and omitting a field requested using
is an error as well.
Note: When calling
for instances with deferred fields, only the loaded fields will be saved. See
for more details.
using using
( alias)
This method is for controlling which database the QuerySet will be evaluated against if you are using more than one database. The only argument this method takes is the alias of a database, as defined in
For example:
# queries the database with the 'default' alias.
>>>
Entry.objects.all()
# queries the database with the 'backup' alias
>>>
Entry.objects.using( 'backup' )
select_for_update select_for_update
( nowait=False)
Returns a queryset that will lock rows until the end of the transaction, generating a SELECT ... FOR UPDATE
SQL statement on supported databases.
For example: entries = Entry.objects.select_for_update().filter(author=request.user)
All matched entries will be locked until the end of the transaction block, meaning that other transactions will be prevented from changing or acquiring locks on them.
Usually, if another transaction has already acquired a lock on one of the selected rows, the query will block until the lock is released. If this is not the behavior you want, call select_for_update(nowait=True). This will make the call non-blocking. If a conflicting lock is already acquired by another transaction,
will be raised when the queryset is evaluated.
Note that using select_for_update() will cause the current transaction to be considered dirty, if under transaction management. This is to ensure that Django issues a COMMIT or ROLLBACK, releasing any locks held by the
SELECT FOR UPDATE
.
956 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Currently, the postgresql_psycopg2
, oracle
, and mysql database backends support select_for_update()
.
However, MySQL has no support for the nowait argument.
Obviously, users of external third-party backends should check with their backend’s documentation for specifics in those cases.
Passing nowait=True to select_for_update using database backends that do not support nowait, such as
MySQL, will cause a
to be raised. This is in order to prevent code unexpectedly blocking.
Using select_for_update on backends which do not support SELECT ... FOR UPDATE (such as SQLite) will have no effect.
Methods that do not return QuerySets
The following QuerySet methods evaluate the QuerySet and return something other than a QuerySet.
These methods do not use a cache (see
Caching and QuerySets ). Rather, they query the database each time they’re
called.
get get
( **kwargs)
Returns the object matching the given lookup parameters, which should be in the format described in
get() raises
if more than one object was found.
exception is an attribute of the model class.
The get() raises a
exception if an object wasn’t found for the given parameters. This exception is also an attribute of the model class. Example:
Entry.objects.get( id
=
'foo' ) # raises Entry.DoesNotExist
The
exception inherits from
django.core.exceptions.ObjectDoesNotExist
can target multiple
exceptions. Example:
from
django.core.exceptions
import
ObjectDoesNotExist
try
: e = Entry.objects.get( id
=
3 ) b = Blog.objects.get( id
=
1 )
except
ObjectDoesNotExist: print ( "Either the entry or blog doesn't exist." )
create create
(
**kwargs)
A convenience method for creating an object and saving it all in one step. Thus: p = Person.objects.create(first_name= "Bruce" , last_name= "Springsteen" ) and: p = Person(first_name= "Bruce" , last_name= "Springsteen" ) p.save(force_insert=True)
6.11. Models 957
Django Documentation, Release 1.5.12
are equivalent.
The
parameter is documented elsewhere, but all it means is that a new object will always be created.
Normally you won’t need to worry about this. However, if your model contains a manual primary key value that you set and if that value already exists in the database, a call to create() will fail with an
since primary keys must be unique. Be prepared to handle the exception if you are using manual primary keys.
get_or_create get_or_create
(
**kwargs)
A convenience method for looking up an object with the given kwargs, creating one if necessary.
Returns a tuple of (object, created), where object is the retrieved or created object and created is a boolean specifying whether a new object was created.
This is meant as a shortcut to boilerplatish code. For example:
try
: obj = Person.objects.get(first_name= 'John' , last_name= 'Lennon' )
except
Person.DoesNotExist: obj = Person(first_name= 'John' , last_name= 'Lennon' , birthday=date( 1940 , 10 , 9 )) obj.save()
This pattern gets quite unwieldy as the number of fields in a model goes up. The above example can be rewritten using get_or_create() like so: obj, created = Person.objects.get_or_create(first_name= 'John' , last_name= 'Lennon' , defaults={ 'birthday' : date( 1940 , 10 , 9 )})
Any keyword arguments passed to get_or_create() — except an optional one called defaults — will be used in a
call. If an object is found, get_or_create() returns a tuple of that object and False. If multiple objects are found, get_or_create raises
MultipleObjectsReturned . If an object is not found,
get_or_create() will instantiate and save a new object, returning a tuple of the new object and True. The new object will be created roughly according to this algorithm: defaults = kwargs.pop( 'defaults' , {}) params = dict ([(k, v) for k, v in kwargs.items() if '__'
not in
k]) params.update(defaults) obj = self
.
model(**params) obj.save()
In English, that means start with any non-'defaults' keyword argument that doesn’t contain a double underscore
(which would indicate a non-exact lookup). Then add the contents of defaults, overriding any keys if necessary, and use the result as the keyword arguments to the model class. As hinted at above, this is a simplification of the algorithm that is used, but it contains all the pertinent details. The internal implementation has some more errorchecking than this and handles some extra edge-conditions; if you’re interested, read the code.
If you have a field named defaults and want to use it as an exact lookup in get_or_create(), just use
'defaults__exact'
, like so:
Foo.objects.get_or_create(defaults__exact= 'bar' , defaults={ 'defaults' : 'baz' })
The get_or_create() method has similar error behavior to
when you’re using manually specified primary keys. If an object needs to be created and the key already exists in the database, an
will be raised.
958 Chapter 6. API Reference
Django Documentation, Release 1.5.12
This method is atomic assuming correct usage, correct database configuration, and correct behavior of the underlying database. However, if uniqueness is not enforced at the database level for the kwargs used in a get_or_create call (see
or
unique_together ), this method is prone to a race-condition which can result in multiple
rows with the same parameters being inserted simultaneously.
If you are using MySQL, be sure to use the READ COMMITTED isolation level rather than REPEATABLE READ
(the default), otherwise you may see cases where get_or_create will raise an
but the object won’t appear in a subsequent
call.
Finally, a word on using get_or_create() in Django views. Please make sure to use it only in POST requests unless you have a good reason not to. GET requests shouldn’t have any effect on data. Instead, use POST whenever a request to a page has a side effect on your data. For more, see Safe methods in the HTTP spec.
bulk_create bulk_create
( objs , batch_size=None)
This method inserts the provided list of objects into the database in an efficient manner (generally only 1 query, no matter how many objects there are):
>>> Entry.objects.bulk_create([
...
...
Entry(headline=
Entry(headline=
"Django 1.0 Released" ),
"Django 1.1 Announced" ),
...
...
])
Entry(headline= "Breaking: Django is awesome" )
This has a number of caveats though:
• The model’s save() method will not be called, and the pre_save and post_save signals will not be sent.
• It does not work with child models in a multi-table inheritance scenario.
• If the model’s primary key is an
it does not retrieve and set the primary key attribute, as save() does.
The batch_size parameter controls how many objects are created in single query. The default is to create all objects in one batch, except for SQLite where the default is such that at maximum 999 variables per query is used.
The batch_size parameter was added in version 1.5.
count count
()
Returns an integer representing the number of objects in the database matching the QuerySet. The count() method never raises exceptions.
Example:
# Returns the total number of entries in the database.
Entry.objects.count()
# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains= 'Lennon' ).count()
A count() call performs a SELECT COUNT(*) behind the scenes, so you should always use count() rather than loading all of the record into Python objects and calling len() on the result (unless you need to load the objects into memory anyway, in which case len() will be faster).
6.11. Models 959
Django Documentation, Release 1.5.12
Depending on which database you’re using (e.g. PostgreSQL vs. MySQL), count() may return a long integer instead of a normal Python integer. This is an underlying implementation quirk that shouldn’t pose any real-world problems.
in_bulk in_bulk
( id_list)
Takes a list of primary-key values and returns a dictionary mapping each primary-key value to an instance of the object with the given ID.
Example:
>>> Blog.objects.in_bulk([ 1 ])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([ 1 , 2 ])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
If you pass in_bulk() an empty list, you’ll get an empty dictionary.
iterator iterator
()
Evaluates the QuerySet (by performing the query) and returns an iterator (see PEP 234 ) over the results. A
QuerySet typically caches its results internally so that repeated evaluations do not result in additional queries. In contrast, iterator() will read results directly, without doing any caching at the QuerySet level (internally, the default iterator calls iterator() and caches the return value). For a QuerySet which returns a large number of objects that you only need to access once, this can result in better performance and a significant reduction in memory.
Note that using iterator() on a QuerySet which has already been evaluated will force it to evaluate again, repeating the query.
Also, use of iterator() causes previous prefetch_related() calls to be ignored since these two optimizations do not make sense together.
Warning: Some Python database drivers like psycopg2 perform caching if using client side cursors (instantiated with connection.cursor() and what Django’s ORM uses). Using iterator() does not affect caching at the database driver level. To disable this caching, look at server side cursors .
latest latest
( field_name=None)
Returns the latest object in the table, by date, using the field_name provided as the date field.
This example returns the latest Entry in the table, according to the pub_date field:
Entry.objects.latest( 'pub_date' )
960 Chapter 6. API Reference
Django Documentation, Release 1.5.12
If your model’s
specifies
, you can leave off the field_name argument to latest().
Django will use the field specified in
by default.
Like
if there is no object with the given parameters.
Note latest() exists purely for convenience and readability.
aggregate aggregate
(
*args , **kwargs)
Returns a dictionary of aggregate values (averages, sums, etc) calculated over the QuerySet. Each argument to aggregate() specifies a value that will be included in the dictionary that is returned.
The aggregation functions that are provided by Django are described in
below.
Aggregates specified using keyword arguments will use the keyword as the name for the annotation. Anonymous arguments will have a name generated for them based upon the name of the aggregate function and the model field that is being aggregated.
For example, when you are working with blog entries, you may want to know the number of authors that have contributed blog entries:
>>> q = Blog.objects.aggregate(Count( 'entry' ))
{'entry__count': 16}
By using a keyword argument to specify the aggregate function, you can control the name of the aggregation value that is returned:
>>> q = Blog.objects.aggregate(number_of_entries=Count( 'entry' ))
{'number_of_entries': 16}
For an in-depth discussion of aggregation, see
the topic guide on Aggregation .
exists exists
()
Returns True if the
contains any results, and False if not. This tries to perform the query in the simplest and fastest way possible, but it does execute nearly the same query as a normal
query.
is useful for searches relating to both object membership in a
and to the existence of any objects in a
QuerySet , particularly in the context of a large QuerySet .
The most efficient method of finding whether a model with a unique field (e.g. primary_key) is a member of a
is: entry = Entry.objects.get(pk= 123 )
if
some_query_set.filter(pk=entry.pk).exists(): print ( "Entry contained in queryset" )
Which will be faster than the following which requires evaluating and iterating through the entire queryset:
if
entry in some_query_set: print ( "Entry contained in QuerySet" )
And to find whether a queryset contains any items:
6.11. Models 961
Django Documentation, Release 1.5.12
if
some_query_set.exists(): print ( "There is at least one object in some_query_set" )
Which will be faster than:
if
some_query_set: print ( "There is at least one object in some_query_set" )
... but not by a large degree (hence needing a large queryset for efficiency gains).
Additionally, if a some_query_set has not yet been evaluated, but you know that it will be at some point, then using some_query_set.exists() will do more overall work (one query for the existence check plus an extra one to later retrieve the results) than simply using bool(some_query_set), which retrieves the results and then checks if any were returned.
update update
( **kwargs)
Performs an SQL update query for the specified fields, and returns the number of rows matched (which may not be equal to the number of rows updated if some rows already have the new value).
For example, to turn comments off for all blog entries published in 2010, you could do this:
>>> Entry.objects.filter(pub_date__year= 2010 ).update(comments_on=False)
(This assumes your Entry model has fields pub_date and comments_on.)
You can update multiple fields — there’s no limit on how many. For example, here we update the comments_on and headline fields:
>>> Entry.objects.filter(pub_date__year= 2010 ).update(comments_on=False, headline=
˓→
'This is old' )
The update() method is applied instantly, and the only restriction on the
that is updated is that it can only update columns in the model’s main table, not on related models. You can’t do this, for example:
>>> Entry.objects.update(blog__name= 'foo' ) # Won't work!
Filtering based on related fields is still possible, though:
>>> Entry.objects.filter(blog__id= 1 ).update(comments_on=True)
You cannot call update() on a
that has had a slice taken or can otherwise no longer be filtered.
The update() method returns the number of affected rows:
>>> Entry.objects.filter( id
=
64 ).update(comments_on=True)
1
>>> Entry.objects.filter(slug= 'nonexistent-slug' ).update(comments_on=True)
0
>>> Entry.objects.filter(pub_date__year= 2010 ).update(comments_on=False)
132
962 Chapter 6. API Reference
Django Documentation, Release 1.5.12
If you’re just updating a record and don’t need to do anything with the model object, the most efficient approach is to call update(), rather than loading the model object into memory. For example, instead of doing this: e = Entry.objects.get( id
=
10 ) e.comments_on = False e.save()
...do this:
Entry.objects.filter( id
=
10 ).update(comments_on=False)
Using update() also prevents a race condition wherein something might change in your database in the short period of time between loading the object and calling save().
Finally, realize that update() does an update at the SQL level and, thus, does not call any save() methods on your models, nor does it emit the
or
signals (which are a consequence of calling
). If you want to update a bunch of records for a model that has a custom save()
method, loop over them and call
for
e in Entry.objects.filter(pub_date__year= 2010 ): e.comments_on = False e.save()
delete delete
()
Performs an SQL delete query on all rows in the
QuerySet . The delete() is applied instantly. You cannot call
delete() on a
that has had a slice taken or can otherwise no longer be filtered.
For example, to delete all the entries in a particular blog:
>>> b = Blog.objects.get(pk= 1 )
# Delete all the entries belonging to this Blog.
>>> Entry.objects.filter(blog=b).delete()
By default, Django’s
emulates the SQL constraint ON DELETE CASCADE — in other words, any objects with foreign keys pointing at the objects to be deleted will be deleted along with them. For example: blogs = Blog.objects.all()
# This will delete all Blogs and all of their Entry objects.
blogs.delete()
This cascade behavior is customizable via the
argument to the
The delete() method does a bulk delete and does not call any delete() methods on your models. It does, however, emit the
and
signals for all deleted objects (including cascaded deletions).
Allow fast-path deletion of objects Django needs to fetch objects into memory to send signals and handle cascades.
However, if there are no cascades and no signals, then Django may take a fast-path and delete objects without fetching into memory. For large deletes this can result in significantly reduced memory usage. The amount of executed queries can be reduced, too.
ForeignKeys which are set to
DO_NOTHING do not prevent taking the fast-path in deletion.
Note that the queries generated in object deletion is an implementation detail subject to change.
6.11. Models 963
Django Documentation, Release 1.5.12
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
and
For an introduction, see
models and database queries documentation
exact
Exact match. If the value provided for comparison is None, it will be interpreted as an SQL NULL (see
for more details).
Examples:
Entry.objects.get(id__exact= 14 )
Entry.objects.get(id__exact=None)
SQL equivalents:
SELECT ... WHERE id
=
14 ;
SELECT ... WHERE id IS NULL;
MySQL comparisons
In MySQL, a database table’s “collation” setting determines whether exact comparisons are case-sensitive. This is a database setting, not a Django setting. It’s possible to configure your MySQL tables to use case-sensitive comparisons, but some trade-offs are involved. For more information about this, see the
in the
documentation.
iexact
Case-insensitive exact match.
Example:
Blog.objects.get(name__iexact= 'beatles blog' )
SQL equivalent:
SELECT ... WHERE name ILIKE 'beatles blog' ;
Note this will match 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG', etc.
SQLite users
When using the SQLite backend and Unicode (non-ASCII) strings, bear in mind the
about string comparisons. SQLite does not do case-insensitive matching for Unicode strings.
contains
Case-sensitive containment test.
964 Chapter 6. API Reference
Django Documentation, Release 1.5.12
Example:
Entry.objects.get(headline__contains= 'Lennon' )
SQL equivalent:
SELECT ... WHERE headline LIKE '%Lennon%' ;
Note this will match the headline 'Lennon honored today' but not 'lennon honored today'.
SQLite users
SQLite doesn’t support case-sensitive LIKE statements; contains acts like icontains for SQLite. See the
for more information.
icontains
Case-insensitive containment test.
Example:
Entry.objects.get(headline__icontains= 'Lennon' )
SQL equivalent:
SELECT ... WHERE headline ILIKE '%Lennon%' ;
SQLite users
When using the SQLite backend and Unicode (non-ASCII) strings, bear in mind the
about string comparisons.
in
In a given list.
Example:
Entry.objects.filter(id__in=[ 1 , 3 , 4 ])
SQL equivalent:
SELECT ... WHERE id IN ( 1 , 3 , 4 );
You can also use a queryset to dynamically evaluate the list of values instead of providing a list of literal values: inner_qs = Blog.objects.filter(name__contains= 'Cheddar' ) entries = Entry.objects.filter(blog__in=inner_qs)
This queryset will be evaluated as subselect statement:
SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%' )
6.11. Models 965
Django Documentation, Release 1.5.12
If you pass in a ValuesQuerySet or ValuesListQuerySet (the result of calling values() or values_list() on a queryset) as the value to an __in lookup, you need to ensure you are only extracting one field in the result. For example, this will work (filtering on the blog names): inner_qs = Blog.objects.filter(name__contains= 'Ch' ).values( 'name' ) entries = Entry.objects.filter(blog__name__in=inner_qs)
This example will raise an exception, since the inner query is trying to extract two field values, where only one is expected:
# Bad code! Will raise a TypeError.
inner_qs = Blog.objects.filter(name__contains= 'Ch' ).values( 'name' , 'id' ) entries = Entry.objects.filter(blog__name__in=inner_qs)
Performance considerations
Be cautious about using nested queries and understand your database server’s performance characteristics (if in doubt, benchmark!). Some database backends, most notably MySQL, don’t optimize nested queries very well. It is more efficient, in those cases, to extract a list of values and then pass that into the second query. That is, execute two queries instead of one: values = Blog.objects.filter( name__contains= 'Cheddar' ).values_list( 'pk' , flat=True) entries = Entry.objects.filter(blog__in= list (values))
Note the list() call around the Blog QuerySet to force execution of the first query. Without it, a nested query would be executed, because
gt
Greater than.
Example:
Entry.objects.filter(id__gt= 4 )
SQL equivalent:
SELECT ... WHERE id
>
4 ;
gte
Greater than or equal to.
lt
Less than.
lte
Less than or equal to.
966 Chapter 6. API Reference
Django Documentation, Release 1.5.12
startswith
Case-sensitive starts-with.
Example:
Entry.objects.filter(headline__startswith= 'Will' )
SQL equivalent:
SELECT ... WHERE headline LIKE 'Will%' ;
SQLite doesn’t support case-sensitive LIKE statements; startswith acts like istartswith for SQLite.
istartswith
Case-insensitive starts-with.
Example:
Entry.objects.filter(headline__istartswith= 'will' )
SQL equivalent:
SELECT ... WHERE headline ILIKE 'Will%' ;
SQLite users
When using the SQLite backend and Unicode (non-ASCII) strings, bear in mind the
about string comparisons.
endswith
Case-sensitive ends-with.
Example:
Entry.objects.filter(headline__endswith= 'cats' )
SQL equivalent:
SELECT ... WHERE headline LIKE '%cats' ;
SQLite users
SQLite doesn’t support case-sensitive LIKE statements; endswith acts like iendswith for SQLite. Refer to the
documentation for more.
6.11. Models 967
Django Documentation, Release 1.5.12
iendswith
Case-insensitive ends-with.
Example:
Entry.objects.filter(headline__iendswith= 'will' )
SQL equivalent:
SELECT ... WHERE headline ILIKE '%will'
SQLite users
When using the SQLite backend and Unicode (non-ASCII) strings, bear in mind the
about string comparisons.
range
Range test (inclusive).
Example: start_date = datetime.date( 2005 , 1 , 1 ) end_date = datetime.date( 2005 , 3 , 31 )
Entry.objects.filter(pub_date__range=(start_date, end_date))
SQL equivalent:
SELECT ... WHERE pub_date BETWEEN '2005-01-01'
and
'2005-03-31' ;
You can use range anywhere you can use BETWEEN in SQL — for dates, numbers and even characters.
Warning: Filtering a DateTimeField with dates won’t include items on the last day, because the bounds are interpreted as “0am on the given date”. If pub_date was a DateTimeField, the above expression would be turned into this SQL:
SELECT ... WHERE pub_date BETWEEN '2005-01-01 00:00:00'
and
'2005-03-31 00:00:00' ;
Generally speaking, you can’t mix dates and datetimes.
year
For date/datetime fields, exact year match. Takes a four-digit year.
Example:
Entry.objects.filter(pub_date__year= 2005 )
SQL equivalent:
968 Chapter 6. API Reference
Django Documentation, Release 1.5.12
SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31' ;
(The exact SQL syntax varies for each database engine.)
month
For date and datetime fields, an exact month match. Takes an integer 1 (January) through 12 (December).
Example:
Entry.objects.filter(pub_date__month= 12 )
SQL equivalent:
SELECT ... WHERE EXTRACT( 'month' FROM pub_date) = '12' ;
(The exact SQL syntax varies for each database engine.)
day
For date and datetime fields, an exact day match.
Example:
Entry.objects.filter(pub_date__day= 3 )
SQL equivalent:
SELECT ... WHERE EXTRACT( 'day' FROM pub_date) = '3' ;
(The exact SQL syntax varies for each database engine.)
Note this will match any record with a pub_date on the third day of the month, such as January 3, July 3, etc.
week_day
For date and datetime fields, a ‘day of the week’ match.
Takes an integer value representing the day of week from 1 (Sunday) to 7 (Saturday).
Example:
Entry.objects.filter(pub_date__week_day= 2 )
(No equivalent SQL code fragment is included for this lookup because implementation of the relevant query varies among different database engines.)
Note this will match any record with a pub_date that falls on a Monday (day 2 of the week), regardless of the month or year in which it occurs. Week days are indexed with day 1 being Sunday and day 7 being Saturday.
Warning: When
is enabled, Django uses UTC in the database connection, which means the year
, month, day and week_day lookups are performed in UTC. This is a known limitation of the current implementation.
6.11. Models 969
Django Documentation, Release 1.5.12
isnull
Takes either True or False, which correspond to SQL queries of IS NULL and IS NOT NULL, respectively.
Example:
Entry.objects.filter(pub_date__isnull=True)
SQL equivalent:
SELECT ... WHERE pub_date IS NULL;
search
A boolean full-text search, taking advantage of full-text indexing. This is like
but is significantly faster due to full-text indexing.
Example:
Entry.objects.filter(headline__search= "+Django -jazz Python" )
SQL equivalent:
SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN
˓→
MODE);
Note this is only available in MySQL and requires direct manipulation of the database to add the full-text index. By default Django uses BOOLEAN MODE for full text searches. See the MySQL documentation for additional details.
regex
Case-sensitive regular expression match.
The regular expression syntax is that of the database backend in use. In the case of SQLite, which has no built in regular expression support, this feature is provided by a (Python) user-defined REGEXP function, and the regular expression syntax is therefore that of Python’s re module.
Example:
Entry.objects.get(title__regex= r'^(An?|The) +' )
SQL equivalents:
SELECT ... WHERE title REGEXP BINARY '^(An?|The) +' ; -- MySQL
SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +' , 'c' ); -- Oracle
SELECT ... WHERE title ~ '^(An?|The) +' ; -- PostgreSQL
SELECT ... WHERE title REGEXP '^(An?|The) +' ; -- SQLite
Using raw strings (e.g., r'foo' instead of 'foo') for passing in the regular expression syntax is recommended.
970 Chapter 6. API Reference
Django Documentation, Release 1.5.12
iregex
Case-insensitive regular expression match.
Example:
Entry.objects.get(title__iregex= r'^(an?|the) +' )
SQL equivalents:
SELECT ... WHERE title REGEXP '^(an?|the) +' ; -- MySQL
SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +' , 'i' ); -- Oracle
SELECT ... WHERE title ~* '^(an?|the) +' ; -- PostgreSQL
SELECT ... WHERE title REGEXP '(?i)^(an?|the) +' ; -- SQLite
Aggregation functions
Django provides the following aggregation functions in the django.db.models module. For details on how to use these aggregate functions, see
the topic guide on aggregation .
Avg
class Avg(field)
Returns the mean value of the given field, which must be numeric.
•Default alias: <field>__avg
•Return type: float
Count
class Count(field, distinct=False)
Returns the number of objects that are related through the provided field.
•Default alias: <field>__count
•Return type: int
Has one optional argument:
distinct
If distinct=True, the count will only include unique instances. This is the SQL equivalent of
COUNT(DISTINCT <field>) . The default value is False.
Max
class Max(field)
Returns the maximum value of the given field.
•Default alias: <field>__max
•Return type: same as input field
6.11. Models 971
Django Documentation, Release 1.5.12
Min
class Min(field)
Returns the minimum value of the given field.
•Default alias: <field>__min
•Return type: same as input field
StdDev
class StdDev(field, sample=False)
Returns the standard deviation of the data in the provided field.
•Default alias: <field>__stddev
•Return type: float
Has one optional argument:
sample
By default, StdDev returns the population standard deviation. However, if sample=True, the return value will be the sample standard deviation.
SQLite
SQLite doesn’t provide StdDev out of the box. An implementation is available as an extension module for
SQLite. Consult the SQlite documentation for instructions on obtaining and installing this extension.
Sum
class Sum(field)
Computes the sum of all values of the given field.
•Default alias: <field>__sum
•Return type: same as input field
Variance
class Variance(field, sample=False)
Returns the variance of the data in the provided field.
•Default alias: <field>__variance
•Return type: float
Has one optional argument:
sample
By default, Variance returns the population variance. However, if sample=True, the return value will be the sample variance.
SQLite
972 Chapter 6. API Reference
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Free and open-source
Written in Python
Rapid development
Reusability and pluggability
Clean and pragmatic design
Active community
Frequently asked questions
Django is a Python-based web framework designed to simplify the development of complex, database-driven websites.
Django offers features like rapid development, reusability, pluggability, clean design, and a strong community.
Django helps you build websites efficiently, with a focus on security and scalability.
