CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="ROBOTS" content="ALL" /> <meta name="MSSmartTagsPreventParsing" content="true" /> <meta name="Copyright" content="Django Software Foundation" /> <meta name="keywords" content="Python, Django, framework, open-source" /> <meta name="description" content="" /> <link rel="canonical" href="https://docs.djangoproject.com/en/5.1/topics/db/queries/"> <link rel="alternate" hreflang="el" href="https://docs.djangoproject.com/el/1.10/topics/db/queries/"> <link rel="alternate" hreflang="en" href="https://docs.djangoproject.com/en/1.10/topics/db/queries/"> <link rel="alternate" hreflang="es" href="https://docs.djangoproject.com/es/1.10/topics/db/queries/"> <link rel="alternate" hreflang="fr" href="https://docs.djangoproject.com/fr/1.10/topics/db/queries/"> <link rel="alternate" hreflang="id" href="https://docs.djangoproject.com/id/1.10/topics/db/queries/"> <link rel="alternate" hreflang="ja" href="https://docs.djangoproject.com/ja/1.10/topics/db/queries/"> <link rel="alternate" hreflang="pl" href="https://docs.djangoproject.com/pl/1.10/topics/db/queries/"> <link rel="alternate" hreflang="pt-br" href="https://docs.djangoproject.com/pt-br/1.10/topics/db/queries/"> <link rel="search" type="application/opensearchdescription+xml" href="https://docs.djangoproject.com/en/1.10/search/description/" title="Django documentation">  <link rel="apple-touch-icon" href="https://static.djangoproject.com/img/icon-touch.e4872c4da341.png"> <link rel="icon" sizes="192x192" href="https://static.djangoproject.com/img/icon-touch.e4872c4da341.png"> <link rel="shortcut icon" href="https://static.djangoproject.com/img/favicon.6dbf28c0650e.ico"> <meta name="msapplication-TileColor" content="#113228"> <meta name="msapplication-TileImage" content="https://static.djangoproject.com/img/icon-tile.b01ac0ef9f67.png"> <meta name="theme-color" content="#0C4B33"> <meta property="og:title" content="Making queries | Django documentation" /> <meta property="og:description" content="The web framework for perfectionists with deadlines." /> <meta property="og:image" content="https://static.djangoproject.com/img/logos/django-logo-negative.1d528e2cb5fb.png" /> <meta property="og:image:alt" content="Django logo" /> <meta property="og:image:width" content="1200" /> <meta property="og:image:height" content="546" /> <meta property="og:image:type" content="image/png" /> <meta property="og:url" content="https://docs.djangoproject.com/en/1.10/topics/db/queries/" /> <meta property="og:site_name" content="Django Project" /> <meta property="twitter:creator" content="djangoproject" /> <meta property="twitter:site" content="djangoproject" /> <meta property="twitter:card" content="summary"> <title>Making queries | Django documentation | Django</title> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,300;0,400;0,700;1,400;1,700&display=swap" rel="stylesheet"> <link rel="stylesheet" href="https://static.djangoproject.com/css/output.4bab36a7ad8a.css" > <script src="https://static.djangoproject.com/js/mod/switch-dark-mode.bd4be131d69b.js"></script> </head> <body id="generic" class=""> <div role="banner" id="top"> <div class="container container--flex--wrap--mobile"> <a class="logo" href="https://www.djangoproject.com/">Django</a> The web framework for perfectionists with deadlines. <div class="mobile-toggle"> <button class="theme-toggle"> <div class="visually-hidden theme-label-when-auto">Toggle theme (current theme: auto)</div> <div class="visually-hidden theme-label-when-light">Toggle theme (current theme: light)</div> <div class="visually-hidden theme-label-when-dark">Toggle theme (current theme: dark)</div> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg aria-hidden="true" class="theme-icon-when-auto"> <use xlink:href="#icon-auto" /> </svg> <svg aria-hidden="true" class="theme-icon-when-dark"> <use xlink:href="#icon-moon" /> </svg> <svg aria-hidden="true" class="theme-icon-when-light"> <use xlink:href="#icon-sun" /> </svg> </button> </div> <button class="menu-button"> Menu </button> <div role="navigation"> <ul> <li> <a href="https://www.djangoproject.com/start/overview/">Overview</a> </li> <li> <a href="https://www.djangoproject.com/download/">Download</a> </li> <li class="active"> <a href="https://docs.djangoproject.com/">Documentation</a> </li> <li> <a href="https://www.djangoproject.com/weblog/">News</a> </li> <li> <a href="https://www.djangoproject.com/community/">Community</a> </li> <li> <a href="https://github.com/django/django" target="_blank" rel="noopener">Code</a> </li> <li> <a href="https://code.djangoproject.com/">Issues</a> </li> <li> <a href="https://www.djangoproject.com/foundation/">About</a> </li> <li> <a href="https://www.djangoproject.com/fundraising/">♥ Donate</a> </li> <li> <button class="theme-toggle"> <div class="visually-hidden theme-label-when-auto">Toggle theme (current theme: auto)</div> <div class="visually-hidden theme-label-when-light">Toggle theme (current theme: light)</div> <div class="visually-hidden theme-label-when-dark">Toggle theme (current theme: dark)</div> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg aria-hidden="true" class="theme-icon-when-auto"> <use xlink:href="#icon-auto" /> </svg> <svg aria-hidden="true" class="theme-icon-when-dark"> <use xlink:href="#icon-moon" /> </svg> <svg aria-hidden="true" class="theme-icon-when-light"> <use xlink:href="#icon-sun" /> </svg> </button> </li> </ul> </div> </div> </div> <div class="copy-banner"> <div class="container container--flex container--flex--wrap--mobile "> <h1><a href="https://docs.djangoproject.com/en/1.10/">Documentation</a></h1> <form action="https://docs.djangoproject.com/en/1.10/search/" class="search form-input" role="search"> <label class="visuallyhidden" for="id_q">Search:</label> <input type="search" name="q" placeholder="Search 1.10 documentation" id="id_q"> <button type="submit"> Search </button> </form> </div> </div> <div id="billboard"></div> <div class="container sidebar-right"> <div role="main"> <div id="version-switcher"> <ul id="faq-link"> <li class="current-link"> <a href="https://docs.djangoproject.com/en/1.10/faq/help/"> Getting Help </a> </li> </ul> <ul id="doc-languages" class="language-switcher doc-switcher"> <li class="other"> <a href="https://docs.djangoproject.com/el/1.10/topics/db/queries/">el</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/es/1.10/topics/db/queries/">es</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/fr/1.10/topics/db/queries/">fr</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/id/1.10/topics/db/queries/">id</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/ja/1.10/topics/db/queries/">ja</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/pl/1.10/topics/db/queries/">pl</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/pt-br/1.10/topics/db/queries/">pt-br</a> </li> <li class="current" title="Click on the links on the left to switch to another language."> Language: en </li> </ul> <ul id="doc-versions" class="version-switcher doc-switcher"> <li class="other"> <a href="https://docs.djangoproject.com/en/1.8/topics/db/queries/">1.8</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/1.11/topics/db/queries/">1.11</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/2.0/topics/db/queries/">2.0</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/2.1/topics/db/queries/">2.1</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/2.2/topics/db/queries/">2.2</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/3.0/topics/db/queries/">3.0</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/3.1/topics/db/queries/">3.1</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/3.2/topics/db/queries/">3.2</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/4.0/topics/db/queries/">4.0</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/4.1/topics/db/queries/">4.1</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/4.2/topics/db/queries/">4.2</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/5.0/topics/db/queries/">5.0</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/5.1/topics/db/queries/">5.1</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/5.2/topics/db/queries/">5.2</a> </li> <li class="other"> <a href="https://docs.djangoproject.com/en/dev/topics/db/queries/">dev</a> </li> <li class="current" title="This document describes Django 1.10. Click on the links on the left to see other versions."> Documentation version: 1.10 </li> </ul> <ul id="backtotop-link"> <li class="current-link"> <a href="#top" aria-label="Back to top" class="icon-chevron-up-align"></a> </li> </ul> </div> <div id="docs-content"> <div class="section" id="s-making-queries"> <h1>Making queries<a class="headerlink" href="#making-queries" title="Permalink to this headline">¶</a></h1> Once you’ve created your <a class="reference internal" href="../models/">data models</a>, 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 <a class="reference internal" href="../../../ref/models/">data model reference</a> 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: <div class="highlight-python notranslate" id="queryset-model-example"><div class="highlight"><pre>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=200) 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 </pre></div> </div> <div class="section" id="s-creating-objects"> <h2>Creating objects<a class="headerlink" href="#creating-objects" title="Permalink to this headline">¶</a></h2> 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 <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> to save it to the database. Assuming models live in a file <code class="docutils literal notranslate">mysite/blog/models.py</code>, here’s an example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from blog.models import Blog >>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.') >>> b.save() </pre></div> </div> This performs an <code class="docutils literal notranslate">INSERT</code> SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>. The <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> method has no return value. <div class="admonition seealso"> See also <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> takes a number of advanced options not described here. See the documentation for <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> for complete details. To create and save an object in a single step, use the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.create" title="django.db.models.query.QuerySet.create"><code class="xref py py-meth docutils literal notranslate">create()</code></a> method. </div> </div> <div class="section" id="s-saving-changes-to-objects"> <h2>Saving changes to objects<a class="headerlink" href="#saving-changes-to-objects" title="Permalink to this headline">¶</a></h2> To save changes to an object that’s already in the database, use <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>. Given a <code class="docutils literal notranslate">Blog</code> instance <code class="docutils literal notranslate">b5</code> that has already been saved to the database, this example changes its name and updates its record in the database: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> b5.name = 'New name' >>> b5.save() </pre></div> </div> This performs an <code class="docutils literal notranslate">UPDATE</code> SQL statement behind the scenes. Django doesn’t hit the database until you explicitly call <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>. <div class="section" id="s-saving-foreignkey-and-manytomanyfield-fields"> <h3>Saving <code class="docutils literal notranslate">ForeignKey</code> and <code class="docutils literal notranslate">ManyToManyField</code> fields<a class="headerlink" href="#saving-foreignkey-and-manytomanyfield-fields" title="Permalink to this headline">¶</a></h3> Updating a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> 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 <code class="docutils literal notranslate">blog</code> attribute of an <code class="docutils literal notranslate">Entry</code> instance <code class="docutils literal notranslate">entry</code>, assuming appropriate instances of <code class="docutils literal notranslate">Entry</code> and <code class="docutils literal notranslate">Blog</code> are already saved to the database (so we can retrieve them below): <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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() </pre></div> </div> Updating a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> works a little differently – use the <a class="reference internal" href="../../../ref/models/relations/#django.db.models.fields.related.RelatedManager.add" title="django.db.models.fields.related.RelatedManager.add"><code class="xref py py-meth docutils literal notranslate">add()</code></a> method on the field to add a record to the relation. This example adds the <code class="docutils literal notranslate">Author</code> instance <code class="docutils literal notranslate">joe</code> to the <code class="docutils literal notranslate">entry</code> object: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from blog.models import Author >>> joe = Author.objects.create(name="Joe") >>> entry.authors.add(joe) </pre></div> </div> To add multiple records to a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> in one go, include multiple arguments in the call to <a class="reference internal" href="../../../ref/models/relations/#django.db.models.fields.related.RelatedManager.add" title="django.db.models.fields.related.RelatedManager.add"><code class="xref py py-meth docutils literal notranslate">add()</code></a>, like this: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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) </pre></div> </div> Django will complain if you try to assign or add an object of the wrong type. </div> </div> <div class="section" id="s-retrieving-objects"> <h2>Retrieving objects<a class="headerlink" href="#retrieving-objects" title="Permalink to this headline">¶</a></h2> To retrieve objects from your database, construct a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> via a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> on your model class. A <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> 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 <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> equates to a <code class="docutils literal notranslate">SELECT</code> statement, and a filter is a limiting clause such as <code class="docutils literal notranslate">WHERE</code> or <code class="docutils literal notranslate">LIMIT</code>. You get a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> by using your model’s <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a>. Each model has at least one <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a>, and it’s called <a class="reference internal" href="../../../ref/models/class/#django.db.models.Model.objects" title="django.db.models.Model.objects"><code class="xref py py-attr docutils literal notranslate">objects</code></a> by default. Access it directly via the model class, like so: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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." </pre></div> </div> <div class="admonition note"> Note <code class="docutils literal notranslate">Managers</code> are accessible only via model classes, rather than from model instances, to enforce a separation between “table-level” operations and “record-level” operations. </div> The <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> is the main source of <code class="docutils literal notranslate">QuerySets</code> for a model. For example, <code class="docutils literal notranslate">Blog.objects.all()</code> returns a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> that contains all <code class="docutils literal notranslate">Blog</code> objects in the database. <div class="section" id="s-retrieving-all-objects"> <h3>Retrieving all objects<a class="headerlink" href="#retrieving-all-objects" title="Permalink to this headline">¶</a></h3> The simplest way to retrieve objects from a table is to get all of them. To do this, use the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.all" title="django.db.models.query.QuerySet.all"><code class="xref py py-meth docutils literal notranslate">all()</code></a> method on a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> all_entries = Entry.objects.all() </pre></div> </div> The <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.all" title="django.db.models.query.QuerySet.all"><code class="xref py py-meth docutils literal notranslate">all()</code></a> method returns a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> of all the objects in the database. </div> <div class="section" id="s-retrieving-specific-objects-with-filters"> <h3>Retrieving specific objects with filters<a class="headerlink" href="#retrieving-specific-objects-with-filters" title="Permalink to this headline">¶</a></h3> The <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> returned by <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.all" title="django.db.models.query.QuerySet.all"><code class="xref py py-meth docutils literal notranslate">all()</code></a> describes all objects in the database table. Usually, though, you’ll need to select only a subset of the complete set of objects. To create such a subset, you refine the initial <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>, adding filter conditions. The two most common ways to refine a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> are: <dl class="docutils"> <dt><code class="docutils literal notranslate">filter(**kwargs)</code></dt> <dd>Returns a new <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> containing objects that match the given lookup parameters.</dd> <dt><code class="docutils literal notranslate">exclude(**kwargs)</code></dt> <dd>Returns a new <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> containing objects that do not match the given lookup parameters.</dd> </dl> The lookup parameters (<code class="docutils literal notranslate">**kwargs</code> in the above function definitions) should be in the format described in <a class="reference internal" href="#field-lookups">Field lookups</a> below. For example, to get a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> of blog entries from the year 2006, use <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> like so: <div class="highlight-default notranslate"><div class="highlight"><pre>Entry.objects.filter(pub_date__year=2006) </pre></div> </div> With the default manager class, it is the same as: <div class="highlight-default notranslate"><div class="highlight"><pre>Entry.objects.all().filter(pub_date__year=2006) </pre></div> </div> <div class="section" id="s-chaining-filters"> <h4>Chaining filters<a class="headerlink" href="#chaining-filters" title="Permalink to this headline">¶</a></h4> The result of refining a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> is itself a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>, so it’s possible to chain refinements together. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter( ... headline__startswith='What' ... ).exclude( ... pub_date__gte=datetime.date.today() ... ).filter( ... pub_date__gte=datetime(2005, 1, 30) ... ) </pre></div> </div> This takes the initial <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> of all entries in the database, adds a filter, then an exclusion, then another filter. The final result is a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> containing all entries with a headline that starts with “What”, that were published between January 30, 2005, and the current day. </div> <div class="section" id="s-filtered-querysets-are-unique"> <h4>Filtered <code class="docutils literal notranslate">QuerySet</code>s are unique<a class="headerlink" href="#filtered-querysets-are-unique" title="Permalink to this headline">¶</a></h4> Each time you refine a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>, you get a brand-new <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> that is in no way bound to the previous <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>. Each refinement creates a separate and distinct <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> that can be stored, used and reused. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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()) </pre></div> </div> These three <code class="docutils literal notranslate">QuerySets</code> are separate. The first is a base <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> 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 <code class="docutils literal notranslate">pub_date</code> is today or in the future. The third is a subset of the first, with an additional criteria that selects only the records whose <code class="docutils literal notranslate">pub_date</code> is today or in the future. The initial <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> (<code class="docutils literal notranslate">q1</code>) is unaffected by the refinement process. </div> <div class="section" id="s-querysets-are-lazy"> <h4><code class="docutils literal notranslate">QuerySet</code>s are lazy<a class="headerlink" href="#querysets-are-lazy" title="Permalink to this headline">¶</a></h4> <code class="docutils literal notranslate">QuerySets</code> are lazy – the act of creating a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> doesn’t involve any database activity. You can stack filters together all day long, and Django won’t actually run the query until the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> is evaluated. Take a look at this example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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) </pre></div> </div> Though this looks like three database hits, in fact it hits the database only once, at the last line (<code class="docutils literal notranslate">print(q)</code>). In general, the results of a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> aren’t fetched from the database until you “ask” for them. When you do, the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> is evaluated by accessing the database. For more details on exactly when evaluation takes place, see <a class="reference internal" href="../../../ref/models/querysets/#when-querysets-are-evaluated">When QuerySets are evaluated</a>. </div> </div> <div class="section" id="s-retrieving-a-single-object-with-get"> <h3>Retrieving a single object with <code class="docutils literal notranslate">get()</code><a class="headerlink" href="#retrieving-a-single-object-with-get" title="Permalink to this headline">¶</a></h3> <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> will always give you a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>, even if only a single object matches the query - in this case, it will be a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> containing a single element. If you know there is only one object that matches your query, you can use the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a> method on a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> which returns the object directly: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> one_entry = Entry.objects.get(pk=1) </pre></div> </div> You can use any query expression with <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a>, just like with <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> - again, see <a class="reference internal" href="#field-lookups">Field lookups</a> below. Note that there is a difference between using <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a>, and using <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> with a slice of <code class="docutils literal notranslate">[0]</code>. If there are no results that match the query, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a> will raise a <code class="docutils literal notranslate">DoesNotExist</code> 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 <code class="docutils literal notranslate">Entry</code> object with a primary key of 1, Django will raise <code class="docutils literal notranslate">Entry.DoesNotExist</code>. Similarly, Django will complain if more than one item matches the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a> query. In this case, it will raise <a class="reference internal" href="../../../ref/exceptions/#django.core.exceptions.MultipleObjectsReturned" title="django.core.exceptions.MultipleObjectsReturned"><code class="xref py py-exc docutils literal notranslate">MultipleObjectsReturned</code></a>, which again is an attribute of the model class itself. </div> <div class="section" id="s-other-queryset-methods"> <h3>Other <code class="docutils literal notranslate">QuerySet</code> methods<a class="headerlink" href="#other-queryset-methods" title="Permalink to this headline">¶</a></h3> Most of the time you’ll use <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.all" title="django.db.models.query.QuerySet.all"><code class="xref py py-meth docutils literal notranslate">all()</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> and <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.exclude" title="django.db.models.query.QuerySet.exclude"><code class="xref py py-meth docutils literal notranslate">exclude()</code></a> when you need to look up objects from the database. However, that’s far from all there is; see the <a class="reference internal" href="../../../ref/models/querysets/#queryset-api">QuerySet API Reference</a> for a complete list of all the various <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> methods. </div> <div class="section" id="s-limiting-querysets"> <h3>Limiting <code class="docutils literal notranslate">QuerySet</code>s<a class="headerlink" href="#limiting-querysets" title="Permalink to this headline">¶</a></h3> Use a subset of Python’s array-slicing syntax to limit your <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> to a certain number of results. This is the equivalent of SQL’s <code class="docutils literal notranslate">LIMIT</code> and <code class="docutils literal notranslate">OFFSET</code> clauses. For example, this returns the first 5 objects (<code class="docutils literal notranslate">LIMIT 5</code>): <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.all()[:5] </pre></div> </div> This returns the sixth through tenth objects (<code class="docutils literal notranslate">OFFSET 5 LIMIT 5</code>): <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.all()[5:10] </pre></div> </div> Negative indexing (i.e. <code class="docutils literal notranslate">Entry.objects.all()[-1]</code>) is not supported. Generally, slicing a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> returns a new <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> – 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.all()[:10:2] </pre></div> </div> To retrieve a single object rather than a list (e.g. <code class="docutils literal notranslate">SELECT foo FROM bar LIMIT 1</code>), use a simple index instead of a slice. For example, this returns the first <code class="docutils literal notranslate">Entry</code> in the database, after ordering entries alphabetically by headline: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.order_by('headline')[0] </pre></div> </div> This is roughly equivalent to: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.order_by('headline')[0:1].get() </pre></div> </div> Note, however, that the first of these will raise <code class="docutils literal notranslate">IndexError</code> while the second will raise <code class="docutils literal notranslate">DoesNotExist</code> if no objects match the given criteria. See <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a> for more details. </div> <div class="section" id="s-field-lookups"> <h3>Field lookups<a class="headerlink" href="#field-lookups" title="Permalink to this headline">¶</a></h3> Field lookups are how you specify the meat of an SQL <code class="docutils literal notranslate">WHERE</code> clause. They’re specified as keyword arguments to the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> methods <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.exclude" title="django.db.models.query.QuerySet.exclude"><code class="xref py py-meth docutils literal notranslate">exclude()</code></a> and <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a>. Basic lookups keyword arguments take the form <code class="docutils literal notranslate">field__lookuptype=value</code>. (That’s a double-underscore). For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(pub_date__lte='2006-01-01') </pre></div> </div> translates (roughly) into the following SQL: <div class="highlight-sql notranslate"><div class="highlight"><pre>SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01'; </pre></div> </div> <div class="admonition-how-this-is-possible admonition"> How this is possible Python has the ability to define functions that accept arbitrary name-value arguments whose names and values are evaluated at runtime. For more information, see <a class="reference external" href="https://docs.python.org/3/tutorial/controlflow.html#tut-keywordargs" title="(in Python v3.8)">Keyword Arguments</a> in the official Python tutorial. </div> The field specified in a lookup has to be the name of a model field. There’s one exception though, in case of a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> you can specify the field name suffixed with <code class="docutils literal notranslate">_id</code>. In this case, the value parameter is expected to contain the raw value of the foreign model’s primary key. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(blog_id=4) </pre></div> </div> If you pass an invalid keyword argument, a lookup function will raise <code class="docutils literal notranslate">TypeError</code>. The database API supports about two dozen lookup types; a complete reference can be found in the <a class="reference internal" href="../../../ref/models/querysets/#field-lookups">field lookup reference</a>. To give you a taste of what’s available, here’s some of the more common lookups you’ll probably use: <dl class="docutils"> <dt><a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-exact"><code class="xref std std-lookup docutils literal notranslate">exact</code></a></dt> <dd>An “exact” match. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.get(headline__exact="Cat bites dog") </pre></div> </div> Would generate SQL along these lines: <div class="highlight-sql notranslate"><div class="highlight"><pre>SELECT ... WHERE headline = 'Cat bites dog'; </pre></div> </div> 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 <code class="docutils literal notranslate">exact</code>. For example, the following two statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Blog.objects.get(id__exact=14) # Explicit form >>> Blog.objects.get(id=14) # __exact is implied </pre></div> </div> This is for convenience, because <code class="docutils literal notranslate">exact</code> lookups are the common case. </dd> <dt><a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-iexact"><code class="xref std std-lookup docutils literal notranslate">iexact</code></a></dt> <dd>A case-insensitive match. So, the query: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Blog.objects.get(name__iexact="beatles blog") </pre></div> </div> Would match a <code class="docutils literal notranslate">Blog</code> titled <code class="docutils literal notranslate">"Beatles Blog"</code>, <code class="docutils literal notranslate">"beatles blog"</code>, or even <code class="docutils literal notranslate">"BeAtlES blOG"</code>. </dd> <dt><a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-contains"><code class="xref std std-lookup docutils literal notranslate">contains</code></a></dt> <dd>Case-sensitive containment test. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>Entry.objects.get(headline__contains='Lennon') </pre></div> </div> Roughly translates to this SQL: <div class="highlight-sql notranslate"><div class="highlight"><pre>SELECT ... WHERE headline LIKE '%Lennon%'; </pre></div> </div> Note this will match the headline <code class="docutils literal notranslate">'Today Lennon honored'</code> but not <code class="docutils literal notranslate">'today lennon honored'</code>. There’s also a case-insensitive version, <a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-icontains"><code class="xref std std-lookup docutils literal notranslate">icontains</code></a>. </dd> <dt><a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-startswith"><code class="xref std std-lookup docutils literal notranslate">startswith</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-endswith"><code class="xref std std-lookup docutils literal notranslate">endswith</code></a></dt> <dd>Starts-with and ends-with search, respectively. There are also case-insensitive versions called <a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-istartswith"><code class="xref std std-lookup docutils literal notranslate">istartswith</code></a> and <a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-iendswith"><code class="xref std std-lookup docutils literal notranslate">iendswith</code></a>.</dd> </dl> Again, this only scratches the surface. A complete reference can be found in the <a class="reference internal" href="../../../ref/models/querysets/#field-lookups">field lookup reference</a>. </div> <div class="section" id="s-lookups-that-span-relationships"> <h3>Lookups that span relationships<a class="headerlink" href="#lookups-that-span-relationships" title="Permalink to this headline">¶</a></h3> Django offers a powerful and intuitive way to “follow” relationships in lookups, taking care of the SQL <code class="docutils literal notranslate">JOIN</code>s for you automatically, behind the scenes. To span a relationship, just use the field name of related fields across models, separated by double underscores, until you get to the field you want. This example retrieves all <code class="docutils literal notranslate">Entry</code> objects with a <code class="docutils literal notranslate">Blog</code> whose <code class="docutils literal notranslate">name</code> is <code class="docutils literal notranslate">'Beatles Blog'</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(blog__name='Beatles Blog') </pre></div> </div> 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 <code class="docutils literal notranslate">Blog</code> objects which have at least one <code class="docutils literal notranslate">Entry</code> whose <code class="docutils literal notranslate">headline</code> contains <code class="docutils literal notranslate">'Lennon'</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Blog.objects.filter(entry__headline__contains='Lennon') </pre></div> </div> 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 <code class="docutils literal notranslate">NULL</code>), but valid, object there. All this means is that no error will be raised. For example, in this filter: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.filter(entry__authors__name='Lennon') </pre></div> </div> (if there was a related <code class="docutils literal notranslate">Author</code> model), if there was no <code class="docutils literal notranslate">author</code> associated with an entry, it would be treated as if there was also no <code class="docutils literal notranslate">name</code> attached, rather than raising an error because of the missing <code class="docutils literal notranslate">author</code>. Usually this is exactly what you want to have happen. The only case where it might be confusing is if you are using <a class="reference internal" href="../../../ref/models/querysets/#std:fieldlookup-isnull"><code class="xref std std-lookup docutils literal notranslate">isnull</code></a>. Thus: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.filter(entry__authors__name__isnull=True) </pre></div> </div> will return <code class="docutils literal notranslate">Blog</code> objects that have an empty <code class="docutils literal notranslate">name</code> on the <code class="docutils literal notranslate">author</code> and also those which have an empty <code class="docutils literal notranslate">author</code> on the <code class="docutils literal notranslate">entry</code>. If you don’t want those latter objects, you could write: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True) </pre></div> </div> <div class="section" id="s-spanning-multi-valued-relationships"> <h4>Spanning multi-valued relationships<a class="headerlink" href="#spanning-multi-valued-relationships" title="Permalink to this headline">¶</a></h4> When you are filtering an object based on a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> or a reverse <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>, there are two different sorts of filter you may be interested in. Consider the <code class="docutils literal notranslate">Blog</code>/<code class="docutils literal notranslate">Entry</code> relationship (<code class="docutils literal notranslate">Blog</code> to <code class="docutils literal notranslate">Entry</code> 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 <code class="docutils literal notranslate">Blog</code>, both of these queries are possible and make sense in some situations. The same type of situation arises with a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a>. For example, if an <code class="docutils literal notranslate">Entry</code> has a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> called <code class="docutils literal notranslate">tags</code>, 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 <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> calls. Everything inside a single <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> call is applied simultaneously to filter out items matching all those requirements. Successive <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> 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 <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> call. That may sound a bit confusing, so hopefully an example will clarify. To select all blogs that contain entries with both “Lennon” in the headline and that were published in 2008 (the same entry satisfying both conditions), we would write: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008) </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008) </pre></div> </div> 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 <code class="docutils literal notranslate">Blog</code> items with each filter statement, not the <code class="docutils literal notranslate">Entry</code> items. <div class="admonition note"> Note The behavior of <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a> for queries that span multi-value relationships, as described above, is not implemented equivalently for <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.exclude" title="django.db.models.query.QuerySet.exclude"><code class="xref py py-meth docutils literal notranslate">exclude()</code></a>. Instead, the conditions in a single <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.exclude" title="django.db.models.query.QuerySet.exclude"><code class="xref py py-meth docutils literal notranslate">exclude()</code></a> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>Blog.objects.exclude( entry__headline__contains='Lennon', entry__pub_date__year=2008, ) </pre></div> </div> However, unlike the behavior when using <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a>, 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: <div class="last highlight-default notranslate"><div class="highlight"><pre>Blog.objects.exclude( entry__in=Entry.objects.filter( headline__contains='Lennon', pub_date__year=2008, ), ) </pre></div> </div> </div> </div> </div> <div class="section" id="s-filters-can-reference-fields-on-the-model"> <h3>Filters can reference fields on the model<a class="headerlink" href="#filters-can-reference-fields-on-the-model" title="Permalink to this headline">¶</a></h3> In the examples given so far, we have constructed filters that compare the value of a model field with a constant. But what if you want to compare the value of a model field with another field on the same model? Django provides <a class="reference internal" href="../../../ref/models/expressions/#django.db.models.F" title="django.db.models.F"><code class="xref py py-class docutils literal notranslate">F expressions</code></a> to allow such comparisons. Instances of <code class="docutils literal notranslate">F()</code> 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 <code class="docutils literal notranslate">F()</code> object to reference the pingback count, and use that <code class="docutils literal notranslate">F()</code> object in the query: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from django.db.models import F >>> Entry.objects.filter(n_comments__gt=F('n_pingbacks')) </pre></div> </div> Django supports the use of addition, subtraction, multiplication, division, modulo, and power arithmetic with <code class="docutils literal notranslate">F()</code> objects, both with constants and with other <code class="docutils literal notranslate">F()</code> objects. To find all the blog entries with more than twice as many comments as pingbacks, we modify the query: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks') * 2) </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(rating__lt=F('n_comments') + F('n_pingbacks')) </pre></div> </div> You can also use the double underscore notation to span relationships in an <code class="docutils literal notranslate">F()</code> object. An <code class="docutils literal notranslate">F()</code> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(authors__name=F('blog__name')) </pre></div> </div> For date and date/time fields, you can add or subtract a <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.timedelta" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object. The following would return all entries that were modified more than 3 days after they were published: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> from datetime import timedelta >>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3)) </pre></div> </div> The <code class="docutils literal notranslate">F()</code> objects support bitwise operations by <code class="docutils literal notranslate">.bitand()</code> and <code class="docutils literal notranslate">.bitor()</code>, for example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> F('somefield').bitand(16) </pre></div> </div> </div> <div class="section" id="s-the-pk-lookup-shortcut"> <h3>The <code class="docutils literal notranslate">pk</code> lookup shortcut<a class="headerlink" href="#the-pk-lookup-shortcut" title="Permalink to this headline">¶</a></h3> For convenience, Django provides a <code class="docutils literal notranslate">pk</code> lookup shortcut, which stands for “primary key”. In the example <code class="docutils literal notranslate">Blog</code> model, the primary key is the <code class="docutils literal notranslate">id</code> field, so these three statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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 </pre></div> </div> The use of <code class="docutils literal notranslate">pk</code> isn’t limited to <code class="docutils literal notranslate">__exact</code> queries – any query term can be combined with <code class="docutils literal notranslate">pk</code> to perform a query on the primary key of a model: <div class="highlight-default notranslate"><div class="highlight"><pre># 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) </pre></div> </div> <code class="docutils literal notranslate">pk</code> lookups also work across joins. For example, these three statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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 </pre></div> </div> </div> <div class="section" id="s-escaping-percent-signs-and-underscores-in-like-statements"> <h3>Escaping percent signs and underscores in <code class="docutils literal notranslate">LIKE</code> statements<a class="headerlink" href="#escaping-percent-signs-and-underscores-in-like-statements" title="Permalink to this headline">¶</a></h3> The field lookups that equate to <code class="docutils literal notranslate">LIKE</code> SQL statements (<code class="docutils literal notranslate">iexact</code>, <code class="docutils literal notranslate">contains</code>, <code class="docutils literal notranslate">icontains</code>, <code class="docutils literal notranslate">startswith</code>, <code class="docutils literal notranslate">istartswith</code>, <code class="docutils literal notranslate">endswith</code> and <code class="docutils literal notranslate">iendswith</code>) will automatically escape the two special characters used in <code class="docutils literal notranslate">LIKE</code> statements – the percent sign and the underscore. (In a <code class="docutils literal notranslate">LIKE</code> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(headline__contains='%') </pre></div> </div> Django takes care of the quoting for you; the resulting SQL will look something like this: <div class="highlight-sql notranslate"><div class="highlight"><pre>SELECT ... WHERE headline LIKE '%\%%'; </pre></div> </div> Same goes for underscores. Both percentage signs and underscores are handled for you transparently. </div> <div class="section" id="s-caching-and-querysets"> <h3>Caching and <code class="docutils literal notranslate">QuerySet</code>s<a class="headerlink" href="#caching-and-querysets" title="Permalink to this headline">¶</a></h3> Each <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> contains a cache to minimize database access. Understanding how it works will allow you to write the most efficient code. In a newly created <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>, the cache is empty. The first time a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> is evaluated – and, hence, a database query happens – Django saves the query results in the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>’s cache and returns the results that have been explicitly requested (e.g., the next element, if the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> is being iterated over). Subsequent evaluations of the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> reuse the cached results. Keep this caching behavior in mind, because it may bite you if you don’t use your <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>s correctly. For example, the following will create two <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>s, evaluate them, and throw them away: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> print([e.headline for e in Entry.objects.all()]) >>> print([e.pub_date for e in Entry.objects.all()]) </pre></div> </div> 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 <code class="docutils literal notranslate">Entry</code> may have been added or deleted in the split second between the two requests. To avoid this problem, simply save the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> and reuse it: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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. </pre></div> </div> <div class="section" id="s-when-querysets-are-not-cached"> <h4>When <code class="docutils literal notranslate">QuerySet</code>s are not cached<a class="headerlink" href="#when-querysets-are-not-cached" title="Permalink to this headline">¶</a></h4> 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 <a class="reference internal" href="#limiting-querysets">limiting the queryset</a> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> queryset = Entry.objects.all() >>> print(queryset[5]) # Queries the database >>> print(queryset[5]) # Queries the database again </pre></div> </div> However, if the entire queryset has already been evaluated, the cache will be checked instead: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> queryset = Entry.objects.all() >>> [entry for entry in queryset] # Queries the database >>> print(queryset[5]) # Uses cache >>> print(queryset[5]) # Uses cache </pre></div> </div> Here are some examples of other actions that will result in the entire queryset being evaluated and therefore populate the cache: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> [entry for entry in queryset] >>> bool(queryset) >>> entry in queryset >>> list(queryset) </pre></div> </div> <div class="admonition note"> Note Simply printing the queryset will not populate the cache. This is because the call to <code class="docutils literal notranslate">__repr__()</code> only returns a slice of the entire queryset. </div> </div> </div> </div> <div class="section" id="s-complex-lookups-with-q-objects"> <h2>Complex lookups with <code class="docutils literal notranslate">Q</code> objects<a class="headerlink" href="#complex-lookups-with-q-objects" title="Permalink to this headline">¶</a></h2> Keyword argument queries – in <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a>, etc. – are “AND”ed together. If you need to execute more complex queries (for example, queries with <code class="docutils literal notranslate">OR</code> statements), you can use <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.Q" title="django.db.models.Q"><code class="xref py py-class docutils literal notranslate">Q objects</code></a>. A <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.Q" title="django.db.models.Q"><code class="xref py py-class docutils literal notranslate">Q object</code></a> (<code class="docutils literal notranslate">django.db.models.Q</code>) is an object used to encapsulate a collection of keyword arguments. These keyword arguments are specified as in “Field lookups” above. For example, this <code class="docutils literal notranslate">Q</code> object encapsulates a single <code class="docutils literal notranslate">LIKE</code> query: <div class="highlight-default notranslate"><div class="highlight"><pre>from django.db.models import Q Q(question__startswith='What') </pre></div> </div> <code class="docutils literal notranslate">Q</code> objects can be combined using the <code class="docutils literal notranslate">&</code> and <code class="docutils literal notranslate">|</code> operators. When an operator is used on two <code class="docutils literal notranslate">Q</code> objects, it yields a new <code class="docutils literal notranslate">Q</code> object. For example, this statement yields a single <code class="docutils literal notranslate">Q</code> object that represents the “OR” of two <code class="docutils literal notranslate">"question__startswith"</code> queries: <div class="highlight-default notranslate"><div class="highlight"><pre>Q(question__startswith='Who') | Q(question__startswith='What') </pre></div> </div> This is equivalent to the following SQL <code class="docutils literal notranslate">WHERE</code> clause: <div class="highlight-default notranslate"><div class="highlight"><pre>WHERE question LIKE 'Who%' OR question LIKE 'What%' </pre></div> </div> You can compose statements of arbitrary complexity by combining <code class="docutils literal notranslate">Q</code> objects with the <code class="docutils literal notranslate">&</code> and <code class="docutils literal notranslate">|</code> operators and use parenthetical grouping. Also, <code class="docutils literal notranslate">Q</code> objects can be negated using the <code class="docutils literal notranslate">~</code> operator, allowing for combined lookups that combine both a normal query and a negated (<code class="docutils literal notranslate">NOT</code>) query: <div class="highlight-default notranslate"><div class="highlight"><pre>Q(question__startswith='Who') | ~Q(pub_date__year=2005) </pre></div> </div> Each lookup function that takes keyword-arguments (e.g. <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.filter" title="django.db.models.query.QuerySet.filter"><code class="xref py py-meth docutils literal notranslate">filter()</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.exclude" title="django.db.models.query.QuerySet.exclude"><code class="xref py py-meth docutils literal notranslate">exclude()</code></a>, <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.get" title="django.db.models.query.QuerySet.get"><code class="xref py py-meth docutils literal notranslate">get()</code></a>) can also be passed one or more <code class="docutils literal notranslate">Q</code> objects as positional (not-named) arguments. If you provide multiple <code class="docutils literal notranslate">Q</code> object arguments to a lookup function, the arguments will be “AND”ed together. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>Poll.objects.get( Q(question__startswith='Who'), Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) ) </pre></div> </div> … roughly translates into the SQL: <div class="highlight-default notranslate"><div class="highlight"><pre>SELECT * from polls WHERE question LIKE 'Who%' AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06') </pre></div> </div> Lookup functions can mix the use of <code class="docutils literal notranslate">Q</code> objects and keyword arguments. All arguments provided to a lookup function (be they keyword arguments or <code class="docutils literal notranslate">Q</code> objects) are “AND”ed together. However, if a <code class="docutils literal notranslate">Q</code> object is provided, it must precede the definition of any keyword arguments. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>Poll.objects.get( Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)), question__startswith='Who', ) </pre></div> </div> … would be a valid query, equivalent to the previous example; but: <div class="highlight-default notranslate"><div class="highlight"><pre># INVALID QUERY Poll.objects.get( question__startswith='Who', Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)) ) </pre></div> </div> … would not be valid. <div class="admonition seealso"> See also The <a class="reference external" href="https://github.com/django/django/blob/master/tests/or_lookups/tests.py">OR lookups examples</a> in the Django unit tests show some possible uses of <code class="docutils literal notranslate">Q</code>. </div> </div> <div class="section" id="s-comparing-objects"> <h2>Comparing objects<a class="headerlink" href="#comparing-objects" title="Permalink to this headline">¶</a></h2> To compare two model instances, just use the standard Python comparison operator, the double equals sign: <code class="docutils literal notranslate">==</code>. Behind the scenes, that compares the primary key values of two models. Using the <code class="docutils literal notranslate">Entry</code> example above, the following two statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> some_entry == other_entry >>> some_entry.id == other_entry.id </pre></div> </div> If a model’s primary key isn’t called <code class="docutils literal notranslate">id</code>, no problem. Comparisons will always use the primary key, whatever it’s called. For example, if a model’s primary key field is called <code class="docutils literal notranslate">name</code>, these two statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> some_obj == other_obj >>> some_obj.name == other_obj.name </pre></div> </div> </div> <div class="section" id="s-deleting-objects"> <h2>Deleting objects<a class="headerlink" href="#deleting-objects" title="Permalink to this headline">¶</a></h2> The delete method, conveniently, is named <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.delete" title="django.db.models.Model.delete"><code class="xref py py-meth docutils literal notranslate">delete()</code></a>. This method immediately deletes the object and returns the number of objects deleted and a dictionary with the number of deletions per object type. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> e.delete() (1, {'weblog.Entry': 1}) </pre></div> </div> <div class="versionchanged"> Changed in Django 1.9: The return value describing the number of objects deleted was added. </div> You can also delete objects in bulk. Every <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> has a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.delete" title="django.db.models.query.QuerySet.delete"><code class="xref py py-meth docutils literal notranslate">delete()</code></a> method, which deletes all members of that <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>. For example, this deletes all <code class="docutils literal notranslate">Entry</code> objects with a <code class="docutils literal notranslate">pub_date</code> year of 2005: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.filter(pub_date__year=2005).delete() (5, {'webapp.Entry': 5}) </pre></div> </div> Keep in mind that this will, whenever possible, be executed purely in SQL, and so the <code class="docutils literal notranslate">delete()</code> methods of individual object instances will not necessarily be called during the process. If you’ve provided a custom <code class="docutils literal notranslate">delete()</code> 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 <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> and calling <code class="docutils literal notranslate">delete()</code> on each object individually) rather than using the bulk <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.delete" title="django.db.models.query.QuerySet.delete"><code class="xref py py-meth docutils literal notranslate">delete()</code></a> method of a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>. <div class="versionchanged"> Changed in Django 1.9: The return value describing the number of objects deleted was added. </div> When Django deletes an object, by default it emulates the behavior of the SQL constraint <code class="docutils literal notranslate">ON DELETE CASCADE</code> – in other words, any objects which had foreign keys pointing at the object to be deleted will be deleted along with it. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>b = Blog.objects.get(pk=1) # This will delete the Blog and all of its Entry objects. b.delete() </pre></div> </div> This cascade behavior is customizable via the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey.on_delete" title="django.db.models.ForeignKey.on_delete"><code class="xref py py-attr docutils literal notranslate">on_delete</code></a> argument to the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>. Note that <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.delete" title="django.db.models.query.QuerySet.delete"><code class="xref py py-meth docutils literal notranslate">delete()</code></a> is the only <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> method that is not exposed on a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> itself. This is a safety mechanism to prevent you from accidentally requesting <code class="docutils literal notranslate">Entry.objects.delete()</code>, and deleting all the entries. If you do want to delete all the objects, then you have to explicitly request a complete query set: <div class="highlight-default notranslate"><div class="highlight"><pre>Entry.objects.all().delete() </pre></div> </div> </div> <div class="section" id="s-copying-model-instances"> <h2>Copying model instances<a class="headerlink" href="#copying-model-instances" title="Permalink to this headline">¶</a></h2> 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 <code class="docutils literal notranslate">pk</code> to <code class="docutils literal notranslate">None</code>. Using our blog example: <div class="highlight-default notranslate"><div class="highlight"><pre>blog = Blog(name='My blog', tagline='Blogging is easy') blog.save() # blog.pk == 1 blog.pk = None blog.save() # blog.pk == 2 </pre></div> </div> Things get more complicated if you use inheritance. Consider a subclass of <code class="docutils literal notranslate">Blog</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>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 </pre></div> </div> Due to how inheritance works, you have to set both <code class="docutils literal notranslate">pk</code> and <code class="docutils literal notranslate">id</code> to None: <div class="highlight-default notranslate"><div class="highlight"><pre>django_blog.pk = None django_blog.id = None django_blog.save() # django_blog.pk == 4 </pre></div> </div> This process doesn’t copy relations that aren’t part of the model’s database table. For example, <code class="docutils literal notranslate">Entry</code> has a <code class="docutils literal notranslate">ManyToManyField</code> to <code class="docutils literal notranslate">Author</code>. After duplicating an entry, you must set the many-to-many relations for the new entry: <div class="highlight-default notranslate"><div class="highlight"><pre>entry = Entry.objects.all()[0] # some previous entry old_authors = entry.authors.all() entry.pk = None entry.save() entry.authors.set(old_authors) </pre></div> </div> For a <code class="docutils literal notranslate">OneToOneField</code>, you must duplicate the related object and assign it to the new object’s field to avoid violating the one-to-one unique constraint. For example, assuming <code class="docutils literal notranslate">entry</code> is already duplicated as above: <div class="highlight-default notranslate"><div class="highlight"><pre>detail = EntryDetail.objects.all()[0] detail.pk = None detail.entry = entry detail.save() </pre></div> </div> </div> <div class="section" id="s-updating-multiple-objects-at-once"> <h2>Updating multiple objects at once<a class="headerlink" href="#updating-multiple-objects-at-once" title="Permalink to this headline">¶</a></h2> Sometimes you want to set a field to a particular value for all the objects in a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a>. You can do this with the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.update" title="django.db.models.query.QuerySet.update"><code class="xref py py-meth docutils literal notranslate">update()</code></a> method. For example: <div class="highlight-default notranslate"><div class="highlight"><pre># Update all the headlines with pub_date in 2007. Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same') </pre></div> </div> You can only set non-relation fields and <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> fields using this method. To update a non-relation field, provide the new value as a constant. To update <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> fields, set the new value to be the new model instance you want to point to. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> b = Blog.objects.get(pk=1) # Change every Entry so that it belongs to this Blog. >>> Entry.objects.all().update(blog=b) </pre></div> </div> The <code class="docutils literal notranslate">update()</code> 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 <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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') </pre></div> </div> Be aware that the <code class="docutils literal notranslate">update()</code> method is converted directly to an SQL statement. It is a bulk operation for direct updates. It doesn’t run any <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> methods on your models, or emit the <code class="docutils literal notranslate">pre_save</code> or <code class="docutils literal notranslate">post_save</code> signals (which are a consequence of calling <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>), or honor the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.DateField.auto_now" title="django.db.models.DateField.auto_now"><code class="xref py py-attr docutils literal notranslate">auto_now</code></a> field option. If you want to save every item in a <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> and make sure that the <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a> method is called on each instance, you don’t need any special function to handle that. Just loop over them and call <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>: <div class="highlight-default notranslate"><div class="highlight"><pre>for item in my_queryset: item.save() </pre></div> </div> Calls to update can also use <a class="reference internal" href="../../../ref/models/expressions/#django.db.models.F" title="django.db.models.F"><code class="xref py py-class docutils literal notranslate">F expressions</code></a> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> Entry.objects.all().update(n_pingbacks=F('n_pingbacks') + 1) </pre></div> </div> However, unlike <code class="docutils literal notranslate">F()</code> objects in filter and exclude clauses, you can’t introduce joins when you use <code class="docutils literal notranslate">F()</code> objects in an update – you can only reference fields local to the model being updated. If you attempt to introduce a join with an <code class="docutils literal notranslate">F()</code> object, a <code class="docutils literal notranslate">FieldError</code> will be raised: <div class="highlight-default notranslate"><div class="highlight"><pre># This will raise a FieldError >>> Entry.objects.update(headline=F('blog__name')) </pre></div> </div> </div> <div class="section" id="s-related-objects"> <h2>Related objects<a class="headerlink" href="#related-objects" title="Permalink to this headline">¶</a></h2> When you define a relationship in a model (i.e., a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>, <a class="reference internal" href="../../../ref/models/fields/#django.db.models.OneToOneField" title="django.db.models.OneToOneField"><code class="xref py py-class docutils literal notranslate">OneToOneField</code></a>, or <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a>), instances of that model will have a convenient API to access the related object(s). Using the models at the top of this page, for example, an <code class="docutils literal notranslate">Entry</code> object <code class="docutils literal notranslate">e</code> can get its associated <code class="docutils literal notranslate">Blog</code> object by accessing the <code class="docutils literal notranslate">blog</code> attribute: <code class="docutils literal notranslate">e.blog</code>. (Behind the scenes, this functionality is implemented by Python <a class="reference external" href="http://users.rcn.com/python/download/Descriptor.htm">descriptors</a>. 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 <code class="docutils literal notranslate">Blog</code> object <code class="docutils literal notranslate">b</code> has access to a list of all related <code class="docutils literal notranslate">Entry</code> objects via the <code class="docutils literal notranslate">entry_set</code> attribute: <code class="docutils literal notranslate">b.entry_set.all()</code>. All examples in this section use the sample <code class="docutils literal notranslate">Blog</code>, <code class="docutils literal notranslate">Author</code> and <code class="docutils literal notranslate">Entry</code> models defined at the top of this page. <div class="section" id="s-one-to-many-relationships"> <h3>One-to-many relationships<a class="headerlink" href="#one-to-many-relationships" title="Permalink to this headline">¶</a></h3> <div class="section" id="s-forward"> <h4>Forward<a class="headerlink" href="#forward" title="Permalink to this headline">¶</a></h4> If a model has a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>, instances of that model will have access to the related (foreign) object via a simple attribute of the model. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> e = Entry.objects.get(id=2) >>> e.blog # Returns the related Blog object. </pre></div> </div> 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 <a class="reference internal" href="../../../ref/models/instances/#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal notranslate">save()</code></a>. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> e = Entry.objects.get(id=2) >>> e.blog = some_blog >>> e.save() </pre></div> </div> If a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> field has <code class="docutils literal notranslate">null=True</code> set (i.e., it allows <code class="docutils literal notranslate">NULL</code> values), you can assign <code class="docutils literal notranslate">None</code> to remove the relation. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> e = Entry.objects.get(id=2) >>> e.blog = None >>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;" </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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. </pre></div> </div> Note that the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet.select_related" title="django.db.models.query.QuerySet.select_related"><code class="xref py py-meth docutils literal notranslate">select_related()</code></a> <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> method recursively prepopulates the cache of all one-to-many relationships ahead of time. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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. </pre></div> </div> </div> <div class="section" id="s-following-relationships-backward"> <h4>Following relationships “backward”<a class="headerlink" href="#following-relationships-backward" title="Permalink to this headline">¶</a></h4> If a model has a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>, instances of the foreign-key model will have access to a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> that returns all instances of the first model. By default, this <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> is named <code class="docutils literal notranslate">FOO_set</code>, where <code class="docutils literal notranslate">FOO</code> is the source model name, lowercased. This <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> returns <code class="docutils literal notranslate">QuerySets</code>, which can be filtered and manipulated as described in the “Retrieving objects” section above. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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() </pre></div> </div> You can override the <code class="docutils literal notranslate">FOO_set</code> name by setting the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey.related_name" title="django.db.models.ForeignKey.related_name"><code class="xref py py-attr docutils literal notranslate">related_name</code></a> parameter in the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> definition. For example, if the <code class="docutils literal notranslate">Entry</code> model was altered to <code class="docutils literal notranslate">blog = ForeignKey(Blog, on_delete=models.CASCADE, related_name='entries')</code>, the above example code would look like this: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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() </pre></div> </div> </div> <div class="section" id="s-using-a-custom-reverse-manager"> <h4>Using a custom reverse manager<a class="headerlink" href="#using-a-custom-reverse-manager" title="Permalink to this headline">¶</a></h4> By default the <a class="reference internal" href="../../../ref/models/relations/#django.db.models.fields.related.RelatedManager" title="django.db.models.fields.related.RelatedManager"><code class="xref py py-class docutils literal notranslate">RelatedManager</code></a> used for reverse relations is a subclass of the <a class="reference internal" href="../managers/#manager-names">default manager</a> for that model. If you would like to specify a different manager for a given query you can use the following syntax: <div class="highlight-default notranslate"><div class="highlight"><pre>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() </pre></div> </div> If <code class="docutils literal notranslate">EntryManager</code> performed default filtering in its <code class="docutils literal notranslate">get_queryset()</code> method, that filtering would apply to the <code class="docutils literal notranslate">all()</code> call. Of course, specifying a custom reverse manager also enables you to call its custom methods: <div class="highlight-default notranslate"><div class="highlight"><pre>b.entry_set(manager='entries').is_published() </pre></div> </div> </div> <div class="section" id="s-additional-methods-to-handle-related-objects"> <h4>Additional methods to handle related objects<a class="headerlink" href="#additional-methods-to-handle-related-objects" title="Permalink to this headline">¶</a></h4> In addition to the <a class="reference internal" href="../../../ref/models/querysets/#django.db.models.query.QuerySet" title="django.db.models.query.QuerySet"><code class="xref py py-class docutils literal notranslate">QuerySet</code></a> methods defined in “Retrieving objects” above, the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a> <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> 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 <a class="reference internal" href="../../../ref/models/relations/">related objects reference</a>. <dl class="docutils"> <dt><code class="docutils literal notranslate">add(obj1, obj2, ...)</code></dt> <dd>Adds the specified model objects to the related object set.</dd> <dt><code class="docutils literal notranslate">create(**kwargs)</code></dt> <dd>Creates a new object, saves it and puts it in the related object set. Returns the newly created object.</dd> <dt><code class="docutils literal notranslate">remove(obj1, obj2, ...)</code></dt> <dd>Removes the specified model objects from the related object set.</dd> <dt><code class="docutils literal notranslate">clear()</code></dt> <dd>Removes all objects from the related object set.</dd> <dt><code class="docutils literal notranslate">set(objs)</code></dt> <dd>Replace the set of related objects.</dd> </dl> To assign the members of a related set, use the <code class="docutils literal notranslate">set()</code> method with an iterable of object instances or a list of primary key values. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>b = Blog.objects.get(id=1) b.entry_set.set([e1, e2]) </pre></div> </div> In this example, <code class="docutils literal notranslate">e1</code> and <code class="docutils literal notranslate">e2</code> can be full Entry instances, or integer primary key values. If the <code class="docutils literal notranslate">clear()</code> method is available, any pre-existing objects will be removed from the <code class="docutils literal notranslate">entry_set</code> before all objects in the iterable (in this case, a list) are added to the set. If the <code class="docutils literal notranslate">clear()</code> 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. </div> </div> <div class="section" id="s-many-to-many-relationships"> <h3>Many-to-many relationships<a class="headerlink" href="#many-to-many-relationships" title="Permalink to this headline">¶</a></h3> 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 <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> uses the attribute name of that field itself, whereas the “reverse” model uses the lowercased model name of the original model, plus <code class="docutils literal notranslate">'_set'</code> (just like reverse one-to-many relationships). An example makes this easier to understand: <div class="highlight-default notranslate"><div class="highlight"><pre>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. </pre></div> </div> Like <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><code class="xref py py-class docutils literal notranslate">ForeignKey</code></a>, <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> can specify <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField.related_name" title="django.db.models.ManyToManyField.related_name"><code class="xref py py-attr docutils literal notranslate">related_name</code></a>. In the above example, if the <a class="reference internal" href="../../../ref/models/fields/#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><code class="xref py py-class docutils literal notranslate">ManyToManyField</code></a> in <code class="docutils literal notranslate">Entry</code> had specified <code class="docutils literal notranslate">related_name='entries'</code>, then each <code class="docutils literal notranslate">Author</code> instance would have an <code class="docutils literal notranslate">entries</code> attribute instead of <code class="docutils literal notranslate">entry_set</code>. </div> <div class="section" id="s-one-to-one-relationships"> <h3>One-to-one relationships<a class="headerlink" href="#one-to-one-relationships" title="Permalink to this headline">¶</a></h3> One-to-one relationships are very similar to many-to-one relationships. If you define a <a class="reference internal" href="../../../ref/models/fields/#django.db.models.OneToOneField" title="django.db.models.OneToOneField"><code class="xref py py-class docutils literal notranslate">OneToOneField</code></a> on your model, instances of that model will have access to the related object via a simple attribute of the model. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>class EntryDetail(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. </pre></div> </div> The difference comes in “reverse” queries. The related model in a one-to-one relationship also has access to a <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> object, but that <a class="reference internal" href="../managers/#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal notranslate">Manager</code></a> represents a single object, rather than a collection of objects: <div class="highlight-default notranslate"><div class="highlight"><pre>e = Entry.objects.get(id=2) e.entrydetail # returns the related EntryDetail object </pre></div> </div> If no object has been assigned to this relationship, Django will raise a <code class="docutils literal notranslate">DoesNotExist</code> exception. Instances can be assigned to the reverse relationship in the same way as you would assign the forward relationship: <div class="highlight-default notranslate"><div class="highlight"><pre>e.entrydetail = ed </pre></div> </div> </div> <div class="section" id="s-how-are-the-backward-relationships-possible"> <h3>How are the backward relationships possible?<a class="headerlink" href="#how-are-the-backward-relationships-possible" title="Permalink to this headline">¶</a></h3> 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 <a class="reference internal" href="../../../ref/applications/#django.apps.apps" title="django.apps.apps"><code class="xref py py-data docutils literal notranslate">app registry</code></a>. When Django starts, it imports each application listed in <a class="reference internal" href="../../../ref/settings/#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate">INSTALLED_APPS</code></a>, and then the <code class="docutils literal notranslate">models</code> 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 <a class="reference internal" href="../../../ref/settings/#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate">INSTALLED_APPS</code></a>. Otherwise, backwards relations may not work properly. </div> <div class="section" id="s-queries-over-related-objects"> <h3>Queries over related objects<a class="headerlink" href="#queries-over-related-objects" title="Permalink to this headline">¶</a></h3> 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 <code class="docutils literal notranslate">b</code> with <code class="docutils literal notranslate">id=5</code>, the following three queries would be identical: <div class="highlight-default notranslate"><div class="highlight"><pre>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 </pre></div> </div> </div> </div> <div class="section" id="s-falling-back-to-raw-sql"> <h2>Falling back to raw SQL<a class="headerlink" href="#falling-back-to-raw-sql" title="Permalink to this headline">¶</a></h2> 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 <a class="reference internal" href="../sql/">Performing raw SQL queries</a>. 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. </div> </div> </div> <div class="browse-horizontal"> <div class="left"><a rel="prev" href="../models/"> Models</a></div> <div class="right"><a rel="next" href="../aggregation/">Aggregation </a></div> </div> <a href="#top" class="backtotop"> Back to Top</a> </div> <h1 class="visuallyhidden">Additional Information</h1> <div role="complementary"> <div class="fundraising-sidebar"> <h2>Support Django!</h2> <div class="small-heart"> <img src="https://static.djangoproject.com/img/fundraising-heart.cd6bb84ffd33.svg" alt="Support Django!" /> </div> <div class="small-cta"> <ul class="list-links-small"> <li><a href="https://www.djangoproject.com/fundraising/"> b.lay, the License Management Company donated to the Django Software Foundation to support Django development. Donate today! </a></li> </ul> </div> </div> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#">Making queries</a><ul> <li><a class="reference internal" href="#creating-objects">Creating objects</a></li> <li><a class="reference internal" href="#saving-changes-to-objects">Saving changes to objects</a><ul> <li><a class="reference internal" href="#saving-foreignkey-and-manytomanyfield-fields">Saving <code class="docutils literal notranslate">ForeignKey</code> and <code class="docutils literal notranslate">ManyToManyField</code> fields</a></li> </ul> </li> <li><a class="reference internal" href="#retrieving-objects">Retrieving objects</a><ul> <li><a class="reference internal" href="#retrieving-all-objects">Retrieving all objects</a></li> <li><a class="reference internal" href="#retrieving-specific-objects-with-filters">Retrieving specific objects with filters</a><ul> <li><a class="reference internal" href="#chaining-filters">Chaining filters</a></li> <li><a class="reference internal" href="#filtered-querysets-are-unique">Filtered <code class="docutils literal notranslate">QuerySet</code>s are unique</a></li> <li><a class="reference internal" href="#querysets-are-lazy"><code class="docutils literal notranslate">QuerySet</code>s are lazy</a></li> </ul> </li> <li><a class="reference internal" href="#retrieving-a-single-object-with-get">Retrieving a single object with <code class="docutils literal notranslate">get()</code></a></li> <li><a class="reference internal" href="#other-queryset-methods">Other <code class="docutils literal notranslate">QuerySet</code> methods</a></li> <li><a class="reference internal" href="#limiting-querysets">Limiting <code class="docutils literal notranslate">QuerySet</code>s</a></li> <li><a class="reference internal" href="#field-lookups">Field lookups</a></li> <li><a class="reference internal" href="#lookups-that-span-relationships">Lookups that span relationships</a><ul> <li><a class="reference internal" href="#spanning-multi-valued-relationships">Spanning multi-valued relationships</a></li> </ul> </li> <li><a class="reference internal" href="#filters-can-reference-fields-on-the-model">Filters can reference fields on the model</a></li> <li><a class="reference internal" href="#the-pk-lookup-shortcut">The <code class="docutils literal notranslate">pk</code> lookup shortcut</a></li> <li><a class="reference internal" href="#escaping-percent-signs-and-underscores-in-like-statements">Escaping percent signs and underscores in <code class="docutils literal notranslate">LIKE</code> statements</a></li> <li><a class="reference internal" href="#caching-and-querysets">Caching and <code class="docutils literal notranslate">QuerySet</code>s</a><ul> <li><a class="reference internal" href="#when-querysets-are-not-cached">When <code class="docutils literal notranslate">QuerySet</code>s are not cached</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#complex-lookups-with-q-objects">Complex lookups with <code class="docutils literal notranslate">Q</code> objects</a></li> <li><a class="reference internal" href="#comparing-objects">Comparing objects</a></li> <li><a class="reference internal" href="#deleting-objects">Deleting objects</a></li> <li><a class="reference internal" href="#copying-model-instances">Copying model instances</a></li> <li><a class="reference internal" href="#updating-multiple-objects-at-once">Updating multiple objects at once</a></li> <li><a class="reference internal" href="#related-objects">Related objects</a><ul> <li><a class="reference internal" href="#one-to-many-relationships">One-to-many relationships</a><ul> <li><a class="reference internal" href="#forward">Forward</a></li> <li><a class="reference internal" href="#following-relationships-backward">Following relationships “backward”</a></li> <li><a class="reference internal" href="#using-a-custom-reverse-manager">Using a custom reverse manager</a></li> <li><a class="reference internal" href="#additional-methods-to-handle-related-objects">Additional methods to handle related objects</a></li> </ul> </li> <li><a class="reference internal" href="#many-to-many-relationships">Many-to-many relationships</a></li> <li><a class="reference internal" href="#one-to-one-relationships">One-to-one relationships</a></li> <li><a class="reference internal" href="#how-are-the-backward-relationships-possible">How are the backward relationships possible?</a></li> <li><a class="reference internal" href="#queries-over-related-objects">Queries over related objects</a></li> </ul> </li> <li><a class="reference internal" href="#falling-back-to-raw-sql">Falling back to raw SQL</a></li> </ul> </li> </ul> <h2>Browse</h2> <ul> <li>Prev: <a rel="prev" href="../models/">Models</a></li> <li>Next: <a rel="next" href="../aggregation/">Aggregation</a></li> <li><a href="https://docs.djangoproject.com/en/1.10/contents/">Table of contents</a></li> <li><a href="https://docs.djangoproject.com/en/1.10/genindex/">General Index</a></li> <li><a href="https://docs.djangoproject.com/en/1.10/py-modindex/">Python Module Index</a></li> </ul> <h2>You are here:</h2> <ul> <li> <a href="https://docs.djangoproject.com/en/1.10/">Django 1.10 documentation</a> <ul><li><a href="../../">Using Django</a> <ul><li><a href="../">Models and databases</a> <ul><li>Making queries</li></ul> </li></ul></li></ul> </li> </ul> <h2 id="getting-help-sidebar">Getting help</h2> <dl class="list-links"> <dt><a href="https://docs.djangoproject.com/en/1.10/faq/">FAQ</a></dt> <dd>Try the FAQ — it's got answers to many common questions.</dd> <dt><a href="/en/stable/genindex/">Index</a>, <a href="/en/stable/py-modindex/">Module Index</a>, or <a href="/en/stable/contents/">Table of Contents</a></dt> <dd>Handy when looking for specific information.</dd> <dt><a href="https://chat.djangoproject.com">Django Discord Server</a></dt> <dd>Join the Django Discord Community.</dd> <dt><a href="https://forum.djangoproject.com/">Official Django Forum</a></dt> <dd>Join the community on the Django Forum.</dd> <dt><a href="https://code.djangoproject.com/">Ticket tracker</a></dt> <dd>Report bugs with Django or Django documentation in our ticket tracker.</dd> </dl> <h2>Download:</h2> Offline (Django 1.10): <a href="https://media.djangoproject.com/docs/django-docs-1.10-en.zip">HTML</a> | <a href="https://media.readthedocs.org/pdf/django/1.10.x/django.pdf">PDF</a> | <a href="https://media.readthedocs.org/epub/django/1.10.x/django.epub">ePub</a> Provided by <a href="https://readthedocs.org/">Read the Docs</a>. </div> </div>  <svg xmlns="http://www.w3.org/2000/svg"> <symbol viewBox="0 0 24 24" id="icon-auto"><path d="M0 0h24v24H0z" fill="currentColor"/><path d="M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm0-2V4a8 8 0 1 0 0 16z"/></symbol> <symbol viewBox="0 0 24 24" id="icon-moon"><path d="M0 0h24v24H0z" fill="currentColor"/><path d="M10 7a7 7 0 0 0 12 4.9v.1c0 5.523-4.477 10-10 10S2 17.523 2 12 6.477 2 12 2h.1A6.979 6.979 0 0 0 10 7zm-6 5a8 8 0 0 0 15.062 3.762A9 9 0 0 1 8.238 4.938 7.999 7.999 0 0 0 4 12z"/></symbol> <symbol viewBox="0 0 24 24" id="icon-sun"><path d="M0 0h24v24H0z" fill="currentColor"/><path d="M12 18a6 6 0 1 1 0-12 6 6 0 0 1 0 12zm0-2a4 4 0 1 0 0-8 4 4 0 0 0 0 8zM11 1h2v3h-2V1zm0 19h2v3h-2v-3zM3.515 4.929l1.414-1.414L7.05 5.636 5.636 7.05 3.515 4.93zM16.95 18.364l1.414-1.414 2.121 2.121-1.414 1.414-2.121-2.121zm2.121-14.85l1.414 1.415-2.121 2.121-1.414-1.414 2.121-2.121zM5.636 16.95l1.414 1.414-2.121 2.121-1.414-1.414 2.121-2.121zM23 11v2h-3v-2h3zM4 11v2H1v-2h3z"/></symbol> </svg>  <div role="contentinfo"> <div class="subfooter"> <div class="container"> <h1 class="visuallyhidden">Django Links</h1> <div class="column-container"> <div class="col-learn-more"> <h2>Learn More</h2> <ul> <li><a href="https://www.djangoproject.com/start/overview/">About Django</a></li> <li><a href="https://www.djangoproject.com/start/">Getting Started with Django</a></li> <li><a href="https://docs.djangoproject.com/en/dev/internals/organization/">Team Organization</a></li> <li><a href="https://www.djangoproject.com/foundation/">Django Software Foundation</a></li> <li><a href="https://www.djangoproject.com/conduct/">Code of Conduct</a></li> <li><a href="https://www.djangoproject.com/diversity/">Diversity Statement</a></li> </ul> </div> <div class="col-get-involved"> <h2>Get Involved</h2> <ul> <li><a href="https://www.djangoproject.com/community/">Join a Group</a></li> <li><a href="https://docs.djangoproject.com/en/dev/internals/contributing/">Contribute to Django</a></li> <li><a href="https://docs.djangoproject.com/en/dev/internals/contributing/bugs-and-features/">Submit a Bug</a></li> <li><a href="https://docs.djangoproject.com/en/dev/internals/security/#reporting-security-issues">Report a Security Issue</a></li> <li><a href="https://www.djangoproject.com/foundation/individual-members/">Individual membership</a></li> </ul> </div> <div class="col-get-help"> <h2>Get Help</h2> <ul> <li><a href="https://docs.djangoproject.com/en/stable/faq/">Getting Help FAQ</a> </li> <li><a href="https://chat.djangoproject.com" target="_blank">Django Discord</a></li> <li><a href="https://forum.djangoproject.com/" target="_blank">Official Django Forum</a></li> </ul> </div> <div class="col-follow-us"> <h2>Follow Us</h2> <ul> <li><a href="https://github.com/django">GitHub</a></li> <li><a href="https://twitter.com/djangoproject">Twitter</a></li> <li><a href="https://fosstodon.org/@django" rel="me">Fediverse (Mastodon)</a></li> <li><a href="https://www.djangoproject.com/rss/weblog/">News RSS</a></li> </ul> </div> <div class="col-support-us"> <h2>Support Us</h2> <ul> <li><a href="https://www.djangoproject.com/fundraising/">Sponsor Django</a></li> <li><a href="/foundation/corporate-membership/">Corporate membership</a></li> <li><a href="https://django.threadless.com/" target="_blank">Official merchandise store</a></li> <li><a href="/foundation/donate/#benevity-giving">Benevity Workplace Giving Program</a></li> </ul> </div> </div> </div> </div> <div class="footer"> <div class="container"> <div class="footer-logo"> <a class="logo" href="https://www.djangoproject.com/">Django</a> </div> <ul class="thanks"> <li> Hosting by <a class="in-kind-donors" href="https://www.djangoproject.com/fundraising/#in-kind-donors">In-kind donors</a> </li> <li class="design">Design by <a class="threespot" href="https://www.threespot.com">Threespot</a> & <a class="andrevv" href="http://andrevv.com/">andrevv</a></li> </ul> © 2005-2025 <a href="https://www.djangoproject.com/foundation/"> Django Software Foundation</a> and individual contributors. Django is a <a href="https://www.djangoproject.com/trademarks/">registered trademark</a> of the Django Software Foundation. </div> </div> </div> <script> function extless(input) { return input.replace(/(.*)\.[^.]+$/, '$1'); } var require = { shim: { 'jquery': [], 'jquery.flot': ["jquery"], 'stripe': { exports: 'Stripe' } }, paths: { "jquery": extless("https://static.djangoproject.com/js/lib/jquery.min.5790ead7ad3b.js"), "jquery.flot": extless("https://static.djangoproject.com/js/lib/jquery.flot.min.9964206e9d7f.js"), "mod/floating-warning": extless("https://static.djangoproject.com/js/mod/floating-warning.582d02dcf0d7.js"), "mod/list-collapsing": extless("https://static.djangoproject.com/js/mod/list-collapsing.2d844151b2ec.js"), "mod/search-key": extless("https://static.djangoproject.com/js/mod/search-key.313dfd2cafb2.js"), "mod/stripe-change-card": extless("https://static.djangoproject.com/js/mod/stripe-change-card.eaa0afc324e9.js"), "mod/switch-dark-mode": extless("https://static.djangoproject.com/js/mod/switch-dark-mode.bd4be131d69b.js"), "stripe-checkout": "https://checkout.stripe.com/checkout", "stripe": "https://js.stripe.com/v3/?" // ? needed due to require.js } }; </script> <script data-main="https://static.djangoproject.com/js/main.1ba5fb2aea58.js" src="https://static.djangoproject.com/js/lib/require.177879fbe7dd.js"></script> <script src="https://static.djangoproject.com/js/djangoproject.0234dabdac11.js"></script> <div id="outdated-warning" class="doc-floating-warning"> This document is for an insecure version of Django that is no longer supported. Please upgrade to a newer release! </div> </body> </html>