SavingForeignKey andManyToManyField fields¶

Updating aForeignKey field works exactly the sameway as saving a normal field – assign an object of the right type to the fieldin question. This example updates theblog attribute of anEntryinstanceentry, assuming appropriate instances ofEntry andBlogare already saved to the database (so we can retrieve them below):

>>>fromblog.modelsimportBlog,Entry>>>entry=Entry.objects.get(pk=1)>>>cheese_blog=Blog.objects.get(name="Cheddar Talk")>>>entry.blog=cheese_blog>>>entry.save()

Updating aManyToManyField works a littledifferently – use theadd() method on the fieldto add a record to the relation. This example adds theAuthor instancejoe to theentry object:

>>>fromblog.modelsimportAuthor>>>joe=Author.objects.create(name="Joe")>>>entry.authors.add(joe)

To add multiple records to aManyToManyField in onego, include multiple arguments in the call toadd(), like this:

>>>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.

Retrieving all objects¶

The simplest way to retrieve objects from a table is to get all of them. To dothis, use theall() method on aManager:

>>>all_entries=Entry.objects.all()

Theall() method returns aQuerySet of all the objects in the database.

Retrieving specific objects with filters¶

TheQuerySet returned byall() describes all objects in thedatabase table. Usually, though, you’ll need to select only a subset of thecomplete set of objects.

To create such a subset, you refine the initialQuerySet, adding filter conditions. The twomost common ways to refine aQuerySet are:

filter(**kwargs)

Returns a newQuerySet containing objectsthat match the given lookup parameters.

exclude(**kwargs)

Returns a newQuerySet containing objectsthat donot match the given lookup parameters.

The lookup parameters (**kwargs in the above function definitions) shouldbe in the format described inField lookups below.

For example, to get aQuerySet of blog entriesfrom the year 2006, usefilter() likeso:

Entry.objects.filter(pub_date__year=2006)

With the default manager class, it is the same as:

Entry.objects.all().filter(pub_date__year=2006)

>>>Entry.objects.filter(headline__startswith="What").exclude(...pub_date__gte=datetime.date.today()...).filter(pub_date__gte=datetime.date(2005,1,30))

>>>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())

>>>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)

Retrieving a single object withget()¶

filter() will always give you aQuerySet, even if only a single object matchesthe query - in this case, it will be aQuerySet containing a single element.

If you know there is only one object that matches your query, you can use theget() method on aManager which returns the object directly:

>>>one_entry=Entry.objects.get(pk=1)

You can use any query expression withget(), just like withfilter() - again, seeField lookupsbelow.

Note that there is a difference between usingget(), and usingfilter() with a slice of[0]. Ifthere are no results that match the query,get() will raise aDoesNotExistexception. This exception is an attribute of the model class that the query isbeing performed on - so in the code above, if there is noEntry object witha primary key of 1, Django will raiseEntry.DoesNotExist.

Similarly, Django will complain if more than one item matches theget() query. In this case, it will raiseMultipleObjectsReturned, which again is anattribute of the model class itself.

OtherQuerySet methods¶

Most of the time you’ll useall(),get(),filter() andexclude() when you need to look upobjects from the database. However, that’s far from all there is; see theQuerySet API Reference for a complete list of all thevariousQuerySet methods.

LimitingQuerySets¶

Use a subset of Python’s array-slicing syntax to limit yourQuerySet to a certain number of results. Thisis the equivalent of SQL’sLIMIT andOFFSET clauses.

For example, this returns the first 5 objects (LIMIT5):

>>>Entry.objects.all()[:5]

This returns the sixth through tenth objects (OFFSET5LIMIT5):

>>>Entry.objects.all()[5:10]

Negative indexing (i.e.Entry.objects.all()[-1]) is not supported.

Generally, slicing aQuerySet returns a newQuerySet – it doesn’t evaluate the query. Anexception is if you use the “step” parameter of Python slice syntax. Forexample, this would actually execute the query in order to return a list ofeverysecond object of the first 10:

>>>Entry.objects.all()[:10:2]

Further filtering or ordering of a sliced queryset is prohibited due to theambiguous nature of how that might work.

To retrieve asingle object rather than a list(e.g.SELECTfooFROMbarLIMIT1), use an index instead of a slice. Forexample, this returns the firstEntry in the database, after orderingentries alphabetically by headline:

>>>Entry.objects.order_by("headline")[0]

This is roughly equivalent to:

>>>Entry.objects.order_by("headline")[0:1].get()

Note, however, that the first of these will raiseIndexError while thesecond will raiseDoesNotExist if no objects match the given criteria. Seeget() for more details.

Field lookups¶

Field lookups are how you specify the meat of an SQLWHERE clause. They’respecified as keyword arguments to theQuerySetmethodsfilter(),exclude() andget().

Basic lookups keyword arguments take the formfield__lookuptype=value.(That’s a double-underscore). For example:

>>>Entry.objects.filter(pub_date__lte="2006-01-01")

translates (roughly) into the following SQL:

SELECT*FROMblog_entryWHEREpub_date<='2006-01-01';

The field specified in a lookup has to be the name of a model field. There’sone exception though, in case of aForeignKey youcan specify the field name suffixed with_id. In this case, the valueparameter is expected to contain the raw value of the foreign model’s primarykey. For example:

>>>Entry.objects.filter(blog_id=4)

If you pass an invalid keyword argument, a lookup function will raiseTypeError.

The database API supports about two dozen lookup types; a complete referencecan be found in thefield lookup reference. To give youa taste of what’s available, here’s some of the more common lookups you’llprobably use:

exact

An “exact” match. For example:

>>>Entry.objects.get(headline__exact="Cat bites dog")

Would generate SQL along these lines:

SELECT...WHEREheadline='Cat bites dog';

If you don’t provide a lookup type – that is, if your keyword argumentdoesn’t contain a double underscore – the lookup type is assumed to beexact.

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, becauseexact lookups are the common case.

iexact

A case-insensitive match. So, the query:

>>>Blog.objects.get(name__iexact="beatles blog")

Would match aBlog titled"BeatlesBlog","beatlesblog", oreven"BeAtlESblOG".

contains

Case-sensitive containment test. For example:

Entry.objects.get(headline__contains="Lennon")

Roughly translates to this SQL:

SELECT...WHEREheadlineLIKE'%Lennon%';

Note this will match the headline'TodayLennonhonored' but not'todaylennonhonored'.

There’s also a case-insensitive version,icontains.

startswith,endswith

Starts-with and ends-with search, respectively. There are alsocase-insensitive versions calledistartswith andiendswith.

Again, this only scratches the surface. A complete reference can be found inthefield lookup reference.

Lookups that span relationships¶

Django offers a powerful and intuitive way to “follow” relationships inlookups, taking care of the SQLJOINs for you automatically, behind thescenes. To span a relationship, use the field name of related fieldsacross models, separated by double underscores, until you get to the field youwant.

This example retrieves allEntry objects with aBlog whosenameis'BeatlesBlog':

>>>Entry.objects.filter(blog__name="Beatles Blog")

This spanning can be as deep as you’d like.

It works backwards, too. While itcanbecustomized, by default you refer to a “reverse”relationship in a lookup using the lowercase name of the model.

This example retrieves allBlog objects which have at least oneEntrywhoseheadline contains'Lennon':

>>>Blog.objects.filter(entry__headline__contains="Lennon")

If you are filtering across multiple relationships and one of the intermediatemodels doesn’t have a value that meets the filter condition, Django will treatit as if there is an empty (all values areNULL), but valid, object there.All this means is that no error will be raised. For example, in this filter:

Blog.objects.filter(entry__authors__name="Lennon")

(if there was a relatedAuthor model), if there was noauthorassociated with an entry, it would be treated as if there was also nonameattached, rather than raising an error because of the missingauthor.Usually this is exactly what you want to have happen. The only case where itmight be confusing is if you are usingisnull. Thus:

Blog.objects.filter(entry__authors__name__isnull=True)

will returnBlog objects that have an emptyname on theauthor andalso those which have an emptyauthor on theentry. If you don’t wantthose latter objects, you could write:

Blog.objects.filter(entry__authors__isnull=False,entry__authors__name__isnull=True)

Blog.objects.filter(entry__headline__contains="Lennon",entry__pub_date__year=2008)

Blog.objects.filter(entry__headline__contains="Lennon").filter(entry__pub_date__year=2008)

>>>fromdatetimeimportdate>>>beatles=Blog.objects.create(name="Beatles Blog")>>>pop=Blog.objects.create(name="Pop Music Blog")>>>Entry.objects.create(...blog=beatles,...headline="New Lennon Biography",...pub_date=date(2008,6,1),...)<Entry: New Lennon Biography>>>>Entry.objects.create(...blog=beatles,...headline="New Lennon Biography in Paperback",...pub_date=date(2009,6,1),...)<Entry: New Lennon Biography in Paperback>>>>Entry.objects.create(...blog=pop,...headline="Best Albums of 2008",...pub_date=date(2008,12,15),...)<Entry: Best Albums of 2008>>>>Entry.objects.create(...blog=pop,...headline="Lennon Would Have Loved Hip Hop",...pub_date=date(2020,4,1),...)<Entry: Lennon Would Have Loved Hip Hop>>>>Blog.objects.filter(...entry__headline__contains="Lennon",...entry__pub_date__year=2008,...)<QuerySet [<Blog: Beatles Blog>]>>>>Blog.objects.filter(...entry__headline__contains="Lennon",...).filter(...entry__pub_date__year=2008,...)<QuerySet [<Blog: Beatles Blog>, <Blog: Beatles Blog>, <Blog: Pop Music Blog]>

Blog.objects.exclude(entry__headline__contains="Lennon",entry__pub_date__year=2008,)

Blog.objects.exclude(entry__in=Entry.objects.filter(headline__contains="Lennon",pub_date__year=2008,),)

Filters can reference fields on the model¶

In the examples given so far, we have constructed filters that comparethe value of a model field with a constant. But what if you want to comparethe value of a model field with another field on the same model?

Django providesFexpressions to allow suchcomparisons. Instances ofF() act as a reference to a model field within aquery. These references can then be used in query filters to compare the valuesof two different fields on the same model instance.

For example, to find a list of all blog entries that have had more commentsthan pingbacks, we construct anF() object to reference the pingback count,and use thatF() object in the query:

>>>fromdjango.db.modelsimportF>>>Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks"))

Django supports the use of addition, subtraction, multiplication, division,modulo, and power arithmetic withF() objects, both with constants and withotherF() objects. To find all the blog entries with more thantwice asmany comments as pingbacks, we modify the query:

>>>Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks")*2)

To find all the entries where the rating of the entry is less than thesum of the pingback count and comment count, we would issue thequery:

>>>Entry.objects.filter(rating__lt=F("number_of_comments")+F("number_of_pingbacks"))

You can also use the double underscore notation to span relationships inanF() object. AnF() object with a double underscore will introduceany joins needed to access the related object. For example, to retrieve allthe entries where the author’s name is the same as the blog name, we couldissue the query:

>>>Entry.objects.filter(authors__name=F("blog__name"))

For date and date/time fields, you can add or subtract atimedelta object. The following would return all entriesthat were modified more than 3 days after they were published:

>>>fromdatetimeimporttimedelta>>>Entry.objects.filter(mod_date__gt=F("pub_date")+timedelta(days=3))

TheF() objects support bitwise operations by.bitand(),.bitor(),.bitxor(),.bitrightshift(), and.bitleftshift(). For example:

>>>F("somefield").bitand(16)

Expressions can reference transforms¶

Django supports using transforms in expressions.

For example, to find allEntry objects published in the same year as theywere last modified:

>>>fromdjango.db.modelsimportF>>>Entry.objects.filter(pub_date__year=F("mod_date__year"))

To find the earliest year an entry was published, we can issue the query:

>>>fromdjango.db.modelsimportMin>>>Entry.objects.aggregate(first_published_year=Min("pub_date__year"))

This example finds the value of the highest rated entry and the total numberof comments on all entries for each year:

>>>fromdjango.db.modelsimportOuterRef,Subquery,Sum>>>Entry.objects.values("pub_date__year").annotate(...top_rating=Subquery(...Entry.objects.filter(...pub_date__year=OuterRef("pub_date__year"),...)....order_by("-rating")....values("rating")[:1]...),...total_comments=Sum("number_of_comments"),...)

Thepk lookup shortcut¶

For convenience, Django provides apk lookup shortcut, which stands for“primary key”.

In the exampleBlog model, the primary key is theid field, so thesethree 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 ofpk isn’t limited to__exact queries – any query termcan be combined withpk 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 areequivalent:

>>>Entry.objects.filter(blog__id__exact=3)# Explicit form>>>Entry.objects.filter(blog__id=3)# __exact is implied>>>Entry.objects.filter(blog__pk=3)# __pk implies __id__exact

Escaping percent signs and underscores inLIKE statements¶

The field lookups that equate toLIKE SQL statements (iexact,contains,icontains,startswith,istartswith,endswithandiendswith) will automatically escape the two special characters used inLIKE statements – the percent sign and the underscore. (In aLIKEstatement, the percent sign signifies a multiple-character wildcard and theunderscore 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, use thepercent sign as any other character:

>>>Entry.objects.filter(headline__contains="%")

Django takes care of the quoting for you; the resulting SQL will look somethinglike this:

SELECT...WHEREheadlineLIKE'%\%%';

Same goes for underscores. Both percentage signs and underscores are handledfor you transparently.

Caching andQuerySets¶

EachQuerySet contains a cache to minimizedatabase access. Understanding how it works will allow you to write the mostefficient code.

In a newly createdQuerySet, the cache isempty. The first time aQuerySet is evaluated– and, hence, a database query happens – Django saves the query results intheQuerySet’s cache and returns the resultsthat have been explicitly requested (e.g., the next element, if theQuerySet is being iterated over). Subsequentevaluations of theQuerySet reuse the cachedresults.

Keep this caching behavior in mind, because it may bite you if you don’t useyourQuerySets correctly. For example, thefollowing will create twoQuerySets, evaluatethem, and throw them away:

>>>print([e.headlineforeinEntry.objects.all()])>>>print([e.pub_dateforeinEntry.objects.all()])

That means the same database query will be executed twice, effectively doublingyour database load. Also, there’s a possibility the two lists may not includethe same database records, because anEntry may have been added or deletedin the split second between the two requests.

To avoid this problem, save theQuerySet andreuse it:

>>>queryset=Entry.objects.all()>>>print([p.headlineforpinqueryset])# Evaluate the query set.>>>print([p.pub_dateforpinqueryset])# Reuse the cache from the evaluation.

>>>queryset=Entry.objects.all()>>>print(queryset[5])# Queries the database>>>print(queryset[5])# Queries the database again

>>>queryset=Entry.objects.all()>>>[entryforentryinqueryset]# Queries the database>>>print(queryset[5])# Uses cache>>>print(queryset[5])# Uses cache

>>>[entryforentryinqueryset]>>>bool(queryset)>>>entryinqueryset>>>list(queryset)

Query iteration¶

The default way of iterating over a query - withfor - will result in ablocking database query behind the scenes as Django loads the results atiteration time. To fix this, you can swap toasyncfor:

asyncforentryinAuthors.objects.filter(name__startswith="A"):...

Be aware that you also can’t do other things that might iterate over thequeryset, such as wrappinglist() around it to force its evaluation (youcan useasyncfor in a comprehension, if you want it).

BecauseQuerySet methods likefilter() andexclude() do notactually run the query - they set up the queryset to run when it’s iteratedover - you can use those freely in asynchronous code. For a guide to whichmethods can keep being used like this, and which have asynchronous versions,read the next section.

QuerySet and manager methods¶

Some methods on managers and querysets - likeget() andfirst() - forceexecution of the queryset and are blocking. Some, likefilter() andexclude(), don’t force execution and so are safe to run from asynchronouscode. But how are you supposed to tell the difference?

While you could poke around and see if there is ana-prefixed version ofthe method (for example, we haveaget() but notafilter()), there is amore logical way - look up what kind of method it is in theQuerySet reference.

In there, you’ll find the methods on QuerySets grouped into two sections:

• Methods that return new querysets: These are the non-blocking ones,and don’t have asynchronous versions. You’re free to use these in anysituation, though read the notes ondefer() andonly() before you usethem.

• Methods that do not return querysets: These are the blocking ones, andhave asynchronous versions - the asynchronous name for each is noted in itsdocumentation, though our standard pattern is to add ana prefix.

Using this distinction, you can work out when you need to use asynchronousversions, and when you don’t. For example, here’s a valid asynchronous query:

user=awaitUser.objects.filter(username=my_input).afirst()

filter() returns a queryset, and so it’s fine to keep chaining it inside anasynchronous environment, whereasfirst() evaluates and returns a modelinstance - thus, we change toafirst(), and useawait at the front ofthe whole expression in order to call it in an asynchronous-friendly way.

Transactions¶

Transactions arenot currently supported with asynchronous queries andupdates. You will find that trying to use one raisesSynchronousOnlyOperation.

If you wish to use a transaction, we suggest you write your ORM code inside aseparate, synchronous function and then call that usingsync_to_async - seeAsynchronous support for more.

Storing and querying forNone¶

As with other fields, storingNone as the field’s value will store it asSQLNULL. While not recommended, it is possible to store JSON scalarnull instead of SQLNULL by usingValue(None,JSONField()).

Whichever of the values is stored, when retrieved from the database, the Pythonrepresentation of the JSON scalarnull is the same as SQLNULL, i.e.None. Therefore, it can be hard to distinguish between them.

This only applies toNone as the top-level value of the field. IfNoneis inside alist ordict, it will always be interpretedas JSONnull.

When querying,None value will always be interpreted as JSONnull. Toquery for SQLNULL, useisnull:

>>>Dog.objects.create(name="Max",data=None)# SQL NULL.<Dog: Max>>>>Dog.objects.create(name="Archie",data=Value(None,JSONField()))# JSON null.<Dog: Archie>>>>Dog.objects.filter(data=None)<QuerySet [<Dog: Archie>]>>>>Dog.objects.filter(data=Value(None,JSONField()))<QuerySet [<Dog: Archie>]>>>>Dog.objects.filter(data__isnull=True)<QuerySet [<Dog: Max>]>>>>Dog.objects.filter(data__isnull=False)<QuerySet [<Dog: Archie>]>

Unless you are sure you wish to work with SQLNULL values, consider settingnull=False and providing a suitable default for empty values, such asdefault=dict.

Key, index, and path transforms¶

To query based on a given dictionary key, use that key as the lookup name:

>>>Dog.objects.create(...name="Rufus",...data={..."breed":"labrador",..."owner":{..."name":"Bob",..."other_pets":[...{..."name":"Fishy",...}...],...},...},...)<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"breed":"collie","owner":None})<Dog: Meg>>>>Dog.objects.filter(data__breed="collie")<QuerySet [<Dog: Meg>]>

Multiple keys can be chained together to form a path lookup:

>>>Dog.objects.filter(data__owner__name="Bob")<QuerySet [<Dog: Rufus>]>

If the key is an integer, it will be interpreted as an index transform in anarray:

>>>Dog.objects.filter(data__owner__other_pets__0__name="Fishy")<QuerySet [<Dog: Rufus>]>

If the key is a negative integer, it cannot be used in a filter keyworddirectly, but you can still use dictionary unpacking to use it in a query:

>>>Dog.objects.filter(**{"data__owner__other_pets__-1__name":"Fishy"})<QuerySet [<Dog: Rufus>]>

If the key you wish to query by clashes with the name of another lookup, usethecontains lookup instead.

To query for missing keys, use theisnull lookup:

>>>Dog.objects.create(name="Shep",data={"breed":"collie"})<Dog: Shep>>>>Dog.objects.filter(data__owner__isnull=True)<QuerySet [<Dog: Shep>]>

Containment and key lookups¶

>>>Dog.objects.create(name="Rufus",data={"breed":"labrador","owner":"Bob"})<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"breed":"collie","owner":"Bob"})<Dog: Meg>>>>Dog.objects.create(name="Fred",data={})<Dog: Fred>>>>Dog.objects.create(...name="Merry",data={"breed":"pekingese","tricks":["fetch","dance"]}...)>>>Dog.objects.filter(data__contains={"owner":"Bob"})<QuerySet [<Dog: Rufus>, <Dog: Meg>]>>>>Dog.objects.filter(data__contains={"breed":"collie"})<QuerySet [<Dog: Meg>]>>>>Dog.objects.filter(data__contains={"tricks":["dance"]})<QuerySet [<Dog: Merry>]>

>>>Dog.objects.create(name="Rufus",data={"breed":"labrador","owner":"Bob"})<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"breed":"collie","owner":"Bob"})<Dog: Meg>>>>Dog.objects.create(name="Fred",data={})<Dog: Fred>>>>Dog.objects.create(...name="Merry",data={"breed":"pekingese","tricks":["fetch","dance"]}...)>>>Dog.objects.filter(data__contained_by={"breed":"collie","owner":"Bob"})<QuerySet [<Dog: Meg>, <Dog: Fred>]>>>>Dog.objects.filter(data__contained_by={"breed":"collie"})<QuerySet [<Dog: Fred>]>>>>Dog.objects.filter(...data__contained_by={"breed":"pekingese","tricks":["dance","fetch","hug"]}...)<QuerySet [<Dog: Merry>, <Dog: Fred>]>

>>>Dog.objects.create(name="Rufus",data={"breed":"labrador"})<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"breed":"collie","owner":"Bob"})<Dog: Meg>>>>Dog.objects.filter(data__has_key="owner")<QuerySet [<Dog: Meg>]>

>>>Dog.objects.create(name="Rufus",data={"breed":"labrador"})<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"breed":"collie","owner":"Bob"})<Dog: Meg>>>>Dog.objects.filter(data__has_keys=["breed","owner"])<QuerySet [<Dog: Meg>]>

>>>Dog.objects.create(name="Rufus",data={"breed":"labrador"})<Dog: Rufus>>>>Dog.objects.create(name="Meg",data={"owner":"Bob"})<Dog: Meg>>>>Dog.objects.filter(data__has_any_keys=["owner","breed"])<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

One-to-many relationships¶

>>>e=Entry.objects.get(id=2)>>>e.blog# Returns the related Blog object.

>>>e=Entry.objects.get(id=2)>>>e.blog=some_blog>>>e.save()

>>>e=Entry.objects.get(id=2)>>>e.blog=None>>>e.save()# "UPDATE blog_entry SET blog_id = NULL ...;"

>>>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.

>>>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()

>>>b=Blog.objects.get(id=1)>>>b.entries.all()# Returns all Entry objects related to Blog.# b.entries is a Manager that returns ``QuerySet`` instances.>>>b.entries.filter(headline__contains="Lennon")>>>b.entries.count()

fromdjango.dbimportmodelsclassEntry(models.Model):# ...objects=models.Manager()# Default Managerentries=EntryManager()# Custom Managerb=Blog.objects.get(id=1)b.entry_set(manager="entries").all()

b.entry_set(manager="entries").is_published()

fromdjango.db.modelsimportPrefetchprefetch_manager=Prefetch("entry_set",queryset=Entry.entries.all())Blog.objects.prefetch_related(prefetch_manager)

b=Blog.objects.get(id=1)b.entry_set.set([e1,e2])

Many-to-many relationships¶

Both ends of a many-to-many relationship get automatic API access to the otherend. The API works similar to a “backward” one-to-many relationship, above.

One difference is in the attribute naming: The model that defines theManyToManyField uses the attribute name of thatfield itself, whereas the “reverse” model uses the lowercased model name of theoriginal 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.

LikeForeignKey,ManyToManyField can specifyrelated_name. In the above example,if theManyToManyField inEntry had specifiedrelated_name='entries', then eachAuthor instance would have anentries attribute instead ofentry_set.

Another difference from one-to-many relationships is that in addition to modelinstances, theadd(),set(), andremove() methods on many-to-manyrelationships accept primary key values. For example, ife1 ande2 areEntry instances, then theseset() calls work identically:

a=Author.objects.get(id=5)a.entry_set.set([e1,e2])a.entry_set.set([e1.pk,e2.pk])

>>>fromdatetimeimportdate>>>batucada=Blog.objects.create(name="Batucada Blog")>>>e=Entry.objects.create(...blog=batucada,...headline="Supporting social movements with drums",...pub_date=date(2019,6,14),...)>>>gloria=Author.objects.create(name="Gloria")>>>anna=Author.objects.create(name="Anna")>>>e.authors.add(gloria,anna)>>>anna.entry_set.filter(authors__name="Gloria")<QuerySet []>

>>>anna.entry_set.filter().filter(authors__name="Gloria")<QuerySet [<Entry: Supporting social movements with drums>]>

>>>anna.entry_set.exclude(authors__name="Gloria")<QuerySet [<Entry: Supporting social movements with drums>]>

>>>anna.entry_set.exclude().exclude(authors__name="Gloria")<QuerySet []>

One-to-one relationships¶

One-to-one relationships are very similar to many-to-one relationships. If youdefine aOneToOneField on your model, instances ofthat model will have access to the related object via an attribute of themodel.

For example:

classEntryDetail(models.Model):entry=models.OneToOneField(Entry,on_delete=models.CASCADE)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-onerelationship also has access to aManager object,but thatManager represents a single object, ratherthan 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 raiseaDoesNotExist exception.

Instances can be assigned to the reverse relationship in the same way asyou would assign the forward relationship:

e.entrydetail=ed

How are the backward relationships possible?¶

Other object-relational mappers require you to define relationships on bothsides. The Django developers believe this is a violation of the DRY (Don’tRepeat Yourself) principle, so Django only requires you to define therelationship on one end.

But how is this possible, given that a model class doesn’t know which othermodel classes are related to it until those other model classes are loaded?

The answer lies in theappregistry. When Djangostarts, it imports each application listed inINSTALLED_APPS, andthen themodels module inside each application. Whenever a new model classis created, Django adds backward-relationships to any related models. If therelated models haven’t been imported yet, Django keeps tracks of therelationships and adds them when the related models eventually are imported.

For this reason, it’s particularly important that all the models you’re usingbe defined in applications listed inINSTALLED_APPS. Otherwise,backwards relations may not work properly.

Queries over related objects¶

Queries involving related objects follow the same rules as queries involvingnormal value fields. When specifying the value for a query to match, you mayuse either an object instance itself, or the primary key value for the object.

For example, if you have a Blog objectb withid=5, the followingthree queries would be identical:

Entry.objects.filter(blog=b)# Query using object instanceEntry.objects.filter(blog=b.id)# Query using id from instanceEntry.objects.filter(blog=5)# Query using id directly