Once you’ve created your data models, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains how to use this API. Refer to the data model reference for full details of all the various model lookup options.
Throughout this guide (and in the reference), we’ll refer to the following models, which comprise a Weblog application:
from django.db import models class Blog(models.Model): name = models.CharField(max_length=100) tagline = models.TextField() def __str__(self): # __unicode__ on Python 2 return self.name class Author(models.Model): name = models.CharField(max_length=50) email = models.EmailField() def __str__(self): # __unicode__ on Python 2 return self.name class Entry(models.Model): blog = models.ForeignKey(Blog) headline = models.CharField(max_length=255) body_text = models.TextField() pub_date = models.DateField() mod_date = models.DateField() authors = models.ManyToManyField(Author) n_comments = models.IntegerField() n_pingbacks = models.IntegerField() rating = models.IntegerField() def __str__(self): # __unicode__ on Python 2 return self.headline
To represent database-table data in Python objects, Django uses an intuitive system: A model class represents a database table, and an instance of that class represents a particular record in the database table.
To create an object, instantiate it using keyword arguments to the model class, then call
save() to save it to the database.
Assuming models live in a file
mysite/blog/models.py, here’s an example:
>>> from blog.models import Blog >>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.') >>> b.save()
This performs an
INSERT SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call
save() method has no return value.
To create and save an object in a single step, use the
To save changes to an object that’s already in the database, use
b5 that has already been saved to the database, this example changes its name and updates its record in the database:
>>> b5.name = 'New name' >>> b5.save()
This performs an
UPDATE SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call
ForeignKey field works exactly the same way as saving a normal field – simply assign an object of the right type to the field in question. This example updates the
blog attribute of an
entry, assuming appropriate instances of
Blog are already saved to the database (so we can retrieve them below):
>>> from blog.models import Entry >>> entry = Entry.objects.get(pk=1) >>> cheese_blog = Blog.objects.get(name="Cheddar Talk") >>> entry.blog = cheese_blog >>> entry.save()
>>> from blog.models import Author >>> joe = Author.objects.create(name="Joe") >>> entry.authors.add(joe)
>>> john = Author.objects.create(name="John") >>> paul = Author.objects.create(name="Paul") >>> george = Author.objects.create(name="George") >>> ringo = Author.objects.create(name="Ringo") >>> entry.authors.add(john, paul, george, ringo)
Django will complain if you try to assign or add an object of the wrong type.
QuerySet represents a collection of objects from your database. It can have zero, one or many filters. Filters narrow down the query results based on the given parameters. In SQL terms, a
QuerySet equates to a
SELECT statement, and a filter is a limiting clause such as
>>> Blog.objects <django.db.models.manager.Manager object at ...> >>> b = Blog(name='Foo', tagline='Bar') >>> b.objects Traceback: ... AttributeError: "Manager isn't accessible via Blog instances."
Managers are accessible only via model classes, rather than from model instances, to enforce a separation between “table-level” operations and “record-level” operations.
>>> all_entries = Entry.objects.all()
QuerySetcontaining objects that match the given lookup parameters.
QuerySetcontaining objects that do not match the given lookup parameters.
The lookup parameters (
**kwargs in the above function definitions) should be in the format described in Field lookups below.
With the default manager class, it is the same as:
>>> Entry.objects.filter( ... headline__startswith='What' ... ).exclude( ... pub_date__gte=datetime.date.today() ... ).filter( ... pub_date__gte=datetime(2005, 1, 30) ... )
This takes the initial
QuerySet of all entries in the database, adds a filter, then an exclusion, then another filter. The final result is a
QuerySet containing all entries with a headline that starts with “What”, that were published between January 30, 2005, and the current day.
Each time you refine a
QuerySet, you get a brand-new
QuerySet that is in no way bound to the previous
QuerySet. Each refinement creates a separate and distinct
QuerySet that can be stored, used and reused.
>>> q1 = Entry.objects.filter(headline__startswith="What") >>> q2 = q1.exclude(pub_date__gte=datetime.date.today()) >>> q3 = q1.filter(pub_date__gte=datetime.date.today())
QuerySets are separate. The first is a base
QuerySet containing all entries that contain a headline starting with “What”. The second is a subset of the first, with an additional criteria that excludes records whose
pub_date is today or in the future. The third is a subset of the first, with an additional criteria that selects only the records whose
pub_date is today or in the future. The initial
q1) is unaffected by the refinement process.
QuerySets are lazy – the act of creating a
QuerySet doesn’t involve any database activity. You can stack filters together all day long, and Django won’t actually run the query until the
QuerySet is evaluated. Take a look at this example:
>>> q = Entry.objects.filter(headline__startswith="What") >>> q = q.filter(pub_date__lte=datetime.date.today()) >>> q = q.exclude(body_text__icontains="food") >>> print(q)
Though this looks like three database hits, in fact it hits the database only once, at the last line (
print(q)). In general, the results of a
QuerySet aren’t fetched from the database until you “ask” for them. When you do, the
QuerySet is evaluated by accessing the database. For more details on exactly when evaluation takes place, see When QuerySets are evaluated.
>>> one_entry = Entry.objects.get(pk=1)
Note that there is a difference between using
get(), and using
filter() with a slice of
. If there are no results that match the query,
get() will raise a
DoesNotExist exception. This exception is an attribute of the model class that the query is being performed on - so in the code above, if there is no
Entry object with a primary key of 1, Django will raise
Most of the time you’ll use
exclude() when you need to look up objects from the database. However, that’s far from all there is; see the QuerySet API Reference for a complete list of all the various
Use a subset of Python’s array-slicing syntax to limit your
QuerySet to a certain number of results. This is the equivalent of SQL’s
For example, this returns the first 5 objects (
This returns the sixth through tenth objects (
OFFSET 5 LIMIT 5):
Negative indexing (i.e.
Entry.objects.all()[-1]) is not supported.
Generally, slicing a
QuerySet returns a new
QuerySet – it doesn’t evaluate the query. An exception is if you use the “step” parameter of Python slice syntax. For example, this would actually execute the query in order to return a list of every second object of the first 10:
To retrieve a single object rather than a list (e.g.
SELECT foo FROM bar LIMIT 1), use a simple index instead of a slice. For example, this returns the first
Entry in the database, after ordering entries alphabetically by headline:
This is roughly equivalent to:
Note, however, that the first of these will raise
IndexError while the second will raise
DoesNotExist if no objects match the given criteria. See
get() for more details.
Basic lookups keyword arguments take the form
field__lookuptype=value. (That’s a double-underscore). For example:
translates (roughly) into the following SQL:
SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';
How this is possible
Python has the ability to define functions that accept arbitrary name-value arguments whose names and values are evaluated at runtime. For more information, see Keyword Arguments in the official Python tutorial.
The field specified in a lookup has to be the name of a model field. There’s one exception though, in case of a
ForeignKey you can specify the field name suffixed with
_id. In this case, the value parameter is expected to contain the raw value of the foreign model’s primary key. For example:
If you pass an invalid keyword argument, a lookup function will raise
The database API supports about two dozen lookup types; a complete reference can be found in the field lookup reference. To give you a taste of what’s available, here’s some of the more common lookups you’ll probably use:
An “exact” match. For example:
>>> Entry.objects.get(headline__exact="Man bites dog")
Would generate SQL along these lines:
SELECT ... WHERE headline = 'Man bites dog';
If you don’t provide a lookup type – that is, if your keyword argument doesn’t contain a double underscore – the lookup type is assumed to be
For example, the following two statements are equivalent:
>>> Blog.objects.get(id__exact=14) # Explicit form >>> Blog.objects.get(id=14) # __exact is implied
This is for convenience, because
exact lookups are the common case.
A case-insensitive match. So, the query:
>>> Blog.objects.get(name__iexact="beatles blog")
Would match a
"beatles blog", or even
Case-sensitive containment test. For example:
Roughly translates to this SQL:
SELECT ... WHERE headline LIKE '%Lennon%';
Note this will match the headline
'Today Lennon honored' but not
'today lennon honored'.
There’s also a case-insensitive version,
Again, this only scratches the surface. A complete reference can be found in the field lookup reference.
Django offers a powerful and intuitive way to “follow” relationships in lookups, taking care of the SQL
JOINs for you automatically, behind the scenes. To span a relationship, just use the field name of related fields across models, separated by double underscores, until you get to the field you want.
This example retrieves all
Entry objects with a
>>> Entry.objects.filter(blog__name='Beatles Blog')
This spanning can be as deep as you’d like.
It works backwards, too. To refer to a “reverse” relationship, just use the lowercase name of the model.
This example retrieves all
Blog objects which have at least one
If you are filtering across multiple relationships and one of the intermediate models doesn’t have a value that meets the filter condition, Django will treat it as if there is an empty (all values are
NULL), but valid, object there. All this means is that no error will be raised. For example, in this filter:
(if there was a related
Author model), if there was no
author associated with an entry, it would be treated as if there was also no
name attached, rather than raising an error because of the missing
author. Usually this is exactly what you want to have happen. The only case where it might be confusing is if you are using
Blog objects that have an empty
name on the
author and also those which have an empty
author on the
entry. If you don’t want those latter objects, you could write:
When you are filtering an object based on a
ManyToManyField or a reverse
ForeignKey, there are two different sorts of filter you may be interested in. Consider the
Entry relationship (
Entry is a one-to-many relation). We might be interested in finding blogs that have an entry which has both “Lennon” in the headline and was published in 2008. Or we might want to find blogs that have an entry with “Lennon” in the headline as well as an entry that was published in 2008. Since there are multiple entries associated with a single
Blog, both of these queries are possible and make sense in some situations.
The same type of situation arises with a
ManyToManyField. For example, if an
Entry has a
tags, we might want to find entries linked to tags called “music” and “bands” or we might want an entry that contains a tag with a name of “music” and a status of “public”.
To handle both of these situations, Django has a consistent way of processing
filter() calls. Everything inside a single
filter() call is applied simultaneously to filter out items matching all those requirements. Successive
filter() calls further restrict the set of objects, but for multi-valued relations, they apply to any object linked to the primary model, not necessarily those objects that were selected by an earlier
That may sound a bit confusing, so hopefully an example will clarify. To select all blogs that contain entries with both “Lennon” in the headline and that were published in 2008 (the same entry satisfying both conditions), we would write:
To select all blogs that contain an entry with “Lennon” in the headline as well as an entry that was published in 2008, we would write:
Suppose there is only one blog that had both entries containing “Lennon” and entries from 2008, but that none of the entries from 2008 contained “Lennon”. The first query would not return any blogs, but the second query would return that one blog.
In the second example, the first filter restricts the queryset to all those blogs linked to entries with “Lennon” in the headline. The second filter restricts the set of blogs further to those that are also linked to entries that were published in 2008. The entries selected by the second filter may or may not be the same as the entries in the first filter. We are filtering the
Blog items with each filter statement, not the
The behavior of
filter() for queries that span multi-value relationships, as described above, is not implemented equivalently for
exclude(). Instead, the conditions in a single
exclude() call will not necessarily refer to the same item.
For example, the following query would exclude blogs that contain both entries with “Lennon” in the headline and entries published in 2008:
Blog.objects.exclude( entry__headline__contains='Lennon', entry__pub_date__year=2008, )
However, unlike the behavior when using
filter(), this will not limit blogs based on entries that satisfy both conditions. In order to do that, i.e. to select all blogs that do not contain entries published with “Lennon” that were published in 2008, you need to make two queries:
Blog.objects.exclude( entry=Entry.objects.filter( headline__contains='Lennon', pub_date__year=2008, ), )
In the examples given so far, we have constructed filters that compare the value of a model field with a constant. But what if you want to compare the value of a model field with another field on the same model?
F expressions to allow such comparisons. Instances of
F() act as a reference to a model field within a query. These references can then be used in query filters to compare the values of two different fields on the same model instance.
For example, to find a list of all blog entries that have had more comments than pingbacks, we construct an
F() object to reference the pingback count, and use that
F() object in the query:
>>> from django.db.models import F >>> Entry.objects.filter(n_comments__gt=F('n_pingbacks'))
Django supports the use of addition, subtraction, multiplication, division, modulo, and power arithmetic with
F() objects, both with constants and with other
F() objects. To find all the blog entries with more than twice as many comments as pingbacks, we modify the query:
>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks') * 2)
The power operator
** was added.
To find all the entries where the rating of the entry is less than the sum of the pingback count and comment count, we would issue the query:
>>> Entry.objects.filter(rating__lt=F('n_comments') + F('n_pingbacks'))
You can also use the double underscore notation to span relationships in an
F() object. An
F() object with a double underscore will introduce any joins needed to access the related object. For example, to retrieve all the entries where the author’s name is the same as the blog name, we could issue the query:
For date and date/time fields, you can add or subtract a
timedelta object. The following would return all entries that were modified more than 3 days after they were published:
>>> from datetime import timedelta >>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))
F() objects support bitwise operations by
.bitor(), for example:
For convenience, Django provides a
pk lookup shortcut, which stands for “primary key”.
In the example
Blog model, the primary key is the
id field, so these three statements are equivalent:
>>> Blog.objects.get(id__exact=14) # Explicit form >>> Blog.objects.get(id=14) # __exact is implied >>> Blog.objects.get(pk=14) # pk implies id__exact
The use of
pk isn’t limited to
__exact queries – any query term can be combined with
pk to perform a query on the primary key of a model:
# Get blogs entries with id 1, 4 and 7 >>> Blog.objects.filter(pk__in=[1,4,7]) # Get all blog entries with id > 14 >>> Blog.objects.filter(pk__gt=14)
pk lookups also work across joins. For example, these three statements are equivalent:
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form >>> Entry.objects.filter(blog__id=3) # __exact is implied >>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact
The field lookups that equate to
LIKE SQL statements (
iendswith) will automatically escape the two special characters used in
LIKE statements – the percent sign and the underscore. (In a
LIKE statement, the percent sign signifies a multiple-character wildcard and the underscore signifies a single-character wildcard.)
This means things should work intuitively, so the abstraction doesn’t leak. For example, to retrieve all the entries that contain a percent sign, just use the percent sign as any other character:
Django takes care of the quoting for you; the resulting SQL will look something like this:
SELECT ... WHERE headline LIKE '%\%%';
Same goes for underscores. Both percentage signs and underscores are handled for you transparently.
QuerySet contains a cache to minimize database access. Understanding how it works will allow you to write the most efficient code.
In a newly created
QuerySet, the cache is empty. The first time a
QuerySet is evaluated – and, hence, a database query happens – Django saves the query results in the
QuerySet’s cache and returns the results that have been explicitly requested (e.g., the next element, if the
QuerySet is being iterated over). Subsequent evaluations of the
QuerySet reuse the cached results.
>>> print([e.headline for e in Entry.objects.all()]) >>> print([e.pub_date for e in Entry.objects.all()])
That means the same database query will be executed twice, effectively doubling your database load. Also, there’s a possibility the two lists may not include the same database records, because an
Entry may have been added or deleted in the split second between the two requests.
To avoid this problem, simply save the
QuerySet and reuse it:
>>> queryset = Entry.objects.all() >>> print([p.headline for p in queryset]) # Evaluate the query set. >>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.
Querysets do not always cache their results. When evaluating only part of the queryset, the cache is checked, but if it is not populated then the items returned by the subsequent query are not cached. Specifically, this means that limiting the queryset using an array slice or an index will not populate the cache.
For example, repeatedly getting a certain index in a queryset object will query the database each time:
>>> queryset = Entry.objects.all() >>> print queryset # Queries the database >>> print queryset # Queries the database again
However, if the entire queryset has already been evaluated, the cache will be checked instead:
>>> queryset = Entry.objects.all() >>> [entry for entry in queryset] # Queries the database >>> print queryset # Uses cache >>> print queryset # Uses cache
Here are some examples of other actions that will result in the entire queryset being evaluated and therefore populate the cache:
>>> [entry for entry in queryset] >>> bool(queryset) >>> entry in queryset >>> list(queryset)
Simply printing the queryset will not populate the cache. This is because the call to
__repr__() only returns a slice of the entire queryset.
Q object (
django.db.models.Q) is an object used to encapsulate a collection of keyword arguments. These keyword arguments are specified as in “Field lookups” above.
For example, this
Q object encapsulates a single
from django.db.models import Q Q(question__startswith='What')
Q objects can be combined using the
| operators. When an operator is used on two
Q objects, it yields a new
For example, this statement yields a single
Q object that represents the “OR” of two
Q(question__startswith='Who') | Q(question__startswith='What')
This is equivalent to the following SQL
WHERE question LIKE 'Who%' OR question LIKE 'What%'
You can compose statements of arbitrary complexity by combining
Q objects with the
| operators and use parenthetical grouping. Also,
Q objects can be negated using the
~ operator, allowing for combined lookups that combine both a normal query and a negated (
Q(question__startswith='Who') | ~Q(pub_date__year=2005)
Each lookup function that takes keyword-arguments (e.g.
get()) can also be passed one or more
Q objects as positional (not-named) arguments. If you provide multiple
Q object arguments to a lookup function, the arguments will be “AND”ed together. For example:
Poll.objects.get( Q(question__startswith='Who'), Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) )
... roughly translates into the SQL:
SELECT * from polls WHERE question LIKE 'Who%' AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')
Lookup functions can mix the use of
Q objects and keyword arguments. All arguments provided to a lookup function (be they keyword arguments or
Q objects) are “AND”ed together. However, if a
Q object is provided, it must precede the definition of any keyword arguments. For example:
Poll.objects.get( Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)), question__startswith='Who')
... would be a valid query, equivalent to the previous example; but:
# INVALID QUERY Poll.objects.get( question__startswith='Who', Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)))
... would not be valid.
The OR lookups examples in the Django unit tests show some possible uses of
To compare two model instances, just use the standard Python comparison operator, the double equals sign:
==. Behind the scenes, that compares the primary key values of two models.
Entry example above, the following two statements are equivalent:
>>> some_entry == other_entry >>> some_entry.id == other_entry.id
If a model’s primary key isn’t called
id, no problem. Comparisons will always use the primary key, whatever it’s called. For example, if a model’s primary key field is called
name, these two statements are equivalent:
>>> some_obj == other_obj >>> some_obj.name == other_obj.name
The delete method, conveniently, is named
delete(). This method immediately deletes the object and has no return value. Example:
For example, this deletes all
Entry objects with a
pub_date year of 2005:
Keep in mind that this will, whenever possible, be executed purely in SQL, and so the
delete() methods of individual object instances will not necessarily be called during the process. If you’ve provided a custom
delete() method on a model class and want to ensure that it is called, you will need to “manually” delete instances of that model (e.g., by iterating over a
QuerySet and calling
delete() on each object individually) rather than using the bulk
delete() method of a
When Django deletes an object, by default it emulates the behavior of the SQL constraint
ON DELETE CASCADE – in other words, any objects which had foreign keys pointing at the object to be deleted will be deleted along with it. For example:
b = Blog.objects.get(pk=1) # This will delete the Blog and all of its Entry objects. b.delete()
delete() is the only
QuerySet method that is not exposed on a
Manager itself. This is a safety mechanism to prevent you from accidentally requesting
Entry.objects.delete(), and deleting all the entries. If you do want to delete all the objects, then you have to explicitly request a complete query set:
Although there is no built-in method for copying model instances, it is possible to easily create new instance with all fields’ values copied. In the simplest case, you can just set
None. Using our blog example:
blog = Blog(name='My blog', tagline='Blogging is easy') blog.save() # blog.pk == 1 blog.pk = None blog.save() # blog.pk == 2
Things get more complicated if you use inheritance. Consider a subclass of
class ThemeBlog(Blog): theme = models.CharField(max_length=200) django_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python') django_blog.save() # django_blog.pk == 3
Due to how inheritance works, you have to set both
id to None:
django_blog.pk = None django_blog.id = None django_blog.save() # django_blog.pk == 4
This process does not copy related objects. If you want to copy relations, you have to write a little bit more code. In our example,
Entry has a many to many field to
entry = Entry.objects.all() # some previous entry old_authors = entry.authors.all() entry.pk = None entry.save() entry.authors = old_authors # saves new many2many relations
# Update all the headlines with pub_date in 2007. Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')
You can only set non-relation fields and
ForeignKey fields using this method. To update a non-relation field, provide the new value as a constant. To update
ForeignKey fields, set the new value to be the new model instance you want to point to. For example:
>>> b = Blog.objects.get(pk=1) # Change every Entry so that it belongs to this Blog. >>> Entry.objects.all().update(blog=b)
update() method is applied instantly and returns the number of rows matched by the query (which may not be equal to the number of rows updated if some rows already have the new value). The only restriction on the
QuerySet being updated is that it can only access one database table: the model’s main table. You can filter based on related fields, but you can only update columns in the model’s main table. Example:
>>> b = Blog.objects.get(pk=1) # Update all the headlines belonging to this Blog. >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same')
Be aware that the
update() method is converted directly to an SQL statement. It is a bulk operation for direct updates. It doesn’t run any
save() methods on your models, or emit the
post_save signals (which are a consequence of calling
save()), or honor the
auto_now field option. If you want to save every item in a
QuerySet and make sure that the
save() method is called on each instance, you don’t need any special function to handle that. Just loop over them and call
for item in my_queryset: item.save()
Calls to update can also use
F expressions to update one field based on the value of another field in the model. This is especially useful for incrementing counters based upon their current value. For example, to increment the pingback count for every entry in the blog:
>>> Entry.objects.all().update(n_pingbacks=F('n_pingbacks') + 1)
F() objects in filter and exclude clauses, you can’t introduce joins when you use
F() objects in an update – you can only reference fields local to the model being updated. If you attempt to introduce a join with an
F() object, a
FieldError will be raised:
# THIS WILL RAISE A FieldError >>> Entry.objects.update(headline=F('blog__name'))
Using the models at the top of this page, for example, an
e can get its associated
Blog object by accessing the
(Behind the scenes, this functionality is implemented by Python descriptors. This shouldn’t really matter to you, but we point it out here for the curious.)
Django also creates API accessors for the “other” side of the relationship – the link from the related model to the model that defines the relationship. For example, a
b has access to a list of all related
Entry objects via the
All examples in this section use the sample
Entry models defined at the top of this page.
If a model has a
ForeignKey, instances of that model will have access to the related (foreign) object via a simple attribute of the model.
>>> e = Entry.objects.get(id=2) >>> e.blog # Returns the related Blog object.
You can get and set via a foreign-key attribute. As you may expect, changes to the foreign key aren’t saved to the database until you call
>>> e = Entry.objects.get(id=2) >>> e.blog = some_blog >>> e.save()
ForeignKey field has
null=True set (i.e., it allows
NULL values), you can assign
None to remove the relation. Example:
>>> e = Entry.objects.get(id=2) >>> e.blog = None >>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"
Forward access to one-to-many relationships is cached the first time the related object is accessed. Subsequent accesses to the foreign key on the same object instance are cached. Example:
>>> e = Entry.objects.get(id=2) >>> print(e.blog) # Hits the database to retrieve the associated Blog. >>> print(e.blog) # Doesn't hit the database; uses cached version.
>>> e = Entry.objects.select_related().get(id=2) >>> print(e.blog) # Doesn't hit the database; uses cached version. >>> print(e.blog) # Doesn't hit the database; uses cached version.
If a model has a
ForeignKey, instances of the foreign-key model will have access to a
Manager that returns all instances of the first model. By default, this
Manager is named
FOO is the source model name, lowercased. This
QuerySets, which can be filtered and manipulated as described in the “Retrieving objects” section above.
>>> b = Blog.objects.get(id=1) >>> b.entry_set.all() # Returns all Entry objects related to Blog. # b.entry_set is a Manager that returns QuerySets. >>> b.entry_set.filter(headline__contains='Lennon') >>> b.entry_set.count()
You can override the
FOO_set name by setting the
related_name parameter in the
ForeignKey definition. For example, if the
Entry model was altered to
blog = ForeignKey(Blog, related_name='entries'), the above example code would look like this:
>>> b = Blog.objects.get(id=1) >>> b.entries.all() # Returns all Entry objects related to Blog. # b.entries is a Manager that returns QuerySets. >>> b.entries.filter(headline__contains='Lennon') >>> b.entries.count()
By default the
RelatedManager used for reverse relations is a subclass of the default manager for that model. If you would like to specify a different manager for a given query you can use the following syntax:
from django.db import models class Entry(models.Model): #... objects = models.Manager() # Default Manager entries = EntryManager() # Custom Manager b = Blog.objects.get(id=1) b.entry_set(manager='entries').all()
EntryManager performed default filtering in its
get_queryset() method, that filtering would apply to the
Of course, specifying a custom reverse manager also enables you to call its custom methods:
In addition to the
QuerySet methods defined in “Retrieving objects” above, the
Manager has additional methods used to handle the set of related objects. A synopsis of each is below, and complete details can be found in the related objects reference.
add(obj1, obj2, ...)
remove(obj1, obj2, ...)
To assign the members of a related set in one fell swoop, just assign to it from any iterable object. The iterable can contain object instances, or just a list of primary key values. For example:
b = Blog.objects.get(id=1) b.entry_set = [e1, e2]
In this example,
e2 can be full Entry instances, or integer primary key values.
clear() method is available, any pre-existing objects will be removed from the
entry_set before all objects in the iterable (in this case, a list) are added to the set. If the
clear() method is not available, all objects in the iterable will be added without removing any existing elements.
Each “reverse” operation described in this section has an immediate effect on the database. Every addition, creation and deletion is immediately and automatically saved to the database.
Both ends of a many-to-many relationship get automatic API access to the other end. The API works just as a “backward” one-to-many relationship, above.
The only difference is in the attribute naming: The model that defines the
ManyToManyField uses the attribute name of that field itself, whereas the “reverse” model uses the lowercased model name of the original model, plus
'_set' (just like reverse one-to-many relationships).
An example makes this easier to understand:
e = Entry.objects.get(id=3) e.authors.all() # Returns all Author objects for this Entry. e.authors.count() e.authors.filter(name__contains='John') a = Author.objects.get(id=5) a.entry_set.all() # Returns all Entry objects for this Author.
ManyToManyField can specify
related_name. In the above example, if the
Entry had specified
related_name='entries', then each
Author instance would have an
entries attribute instead of
One-to-one relationships are very similar to many-to-one relationships. If you define a
OneToOneField on your model, instances of that model will have access to the related object via a simple attribute of the model.
class EntryDetail(models.Model): entry = models.OneToOneField(Entry) details = models.TextField() ed = EntryDetail.objects.get(id=2) ed.entry # Returns the related Entry object.
The difference comes in “reverse” queries. The related model in a one-to-one relationship also has access to a
Manager object, but that
Manager represents a single object, rather than a collection of objects:
e = Entry.objects.get(id=2) e.entrydetail # returns the related EntryDetail object
If no object has been assigned to this relationship, Django will raise a
Instances can be assigned to the reverse relationship in the same way as you would assign the forward relationship:
e.entrydetail = ed
Other object-relational mappers require you to define relationships on both sides. The Django developers believe this is a violation of the DRY (Don’t Repeat Yourself) principle, so Django only requires you to define the relationship on one end.
But how is this possible, given that a model class doesn’t know which other model classes are related to it until those other model classes are loaded?
The answer lies in the
app registry. When Django starts, it imports each application listed in
INSTALLED_APPS, and then the
models module inside each application. Whenever a new model class is created, Django adds backward-relationships to any related models. If the related models haven’t been imported yet, Django keeps tracks of the relationships and adds them when the related models eventually are imported.
For this reason, it’s particularly important that all the models you’re using be defined in applications listed in
INSTALLED_APPS. Otherwise, backwards relations may not work properly.
Queries involving related objects follow the same rules as queries involving normal value fields. When specifying the value for a query to match, you may use either an object instance itself, or the primary key value for the object.
For example, if you have a Blog object
id=5, the following three queries would be identical:
Entry.objects.filter(blog=b) # Query using object instance Entry.objects.filter(blog=b.id) # Query using id from instance Entry.objects.filter(blog=5) # Query using id directly
If you find yourself needing to write an SQL query that is too complex for Django’s database-mapper to handle, you can fall back on writing SQL by hand. Django has a couple of options for writing raw SQL queries; see Performing raw SQL queries.
Finally, it’s important to note that the Django database layer is merely an interface to your database. You can access your database via other tools, programming languages or database frameworks; there’s nothing Django-specific about your database.
© Django Software Foundation and individual contributors
Licensed under the BSD License.