QuerySet API referenceLink to this heading#This document describes the details of the QuerySet API. It builds on the\nmaterial presented in the model and database\nquery guides, so you’ll probably want to read and\nunderstand those documents before reading this one.
Throughout this reference we’ll use the example Weblog models presented in the database query guide.
\nQuerySets are evaluatedLink to this heading#Internally, a QuerySet can be constructed, filtered, sliced, and generally\npassed around without actually hitting the database. No database activity\nactually occurs until you do something to evaluate the queryset.
You can evaluate a QuerySet in the following ways:
Iteration. A QuerySet is iterable, and it executes its database\nquery the first time you iterate over it. For example, this will print\nthe headline of all entries in the database:
for e in Entry.objects.all():\n print(e.headline)\nNote: Don’t use this if all you want to do is determine if at least one\nresult exists. It’s more efficient to use exists().
Slicing. As explained in Limiting QuerySets, a QuerySet can\nbe sliced, using Python’s array-slicing syntax. Slicing an unevaluated\nQuerySet usually returns another unevaluated QuerySet, but Django\nwill execute the database query if you use the «step» parameter of slice\nsyntax, and will return a list. Slicing a QuerySet that has been\nevaluated also returns a list.
Also note that even though slicing an unevaluated QuerySet returns\nanother unevaluated QuerySet, modifying it further (e.g., adding\nmore filters, or modifying ordering) is not allowed, since that does not\ntranslate well into SQL and it would not have a clear meaning either.
Pickling/Caching. See the following section for details of what\nis involved when pickling QuerySets. The important thing for the\npurposes of this section is that the results are read from the database.
repr(). A QuerySet is evaluated when you call repr() on it.\nThis is for convenience in the Python interactive interpreter, so you can\nimmediately see your results when using the API interactively.
len(). A QuerySet is evaluated when you call len() on it.\nThis, as you might expect, returns the length of the result list.
Note: If you only need to determine the number of records in the set (and\ndon’t need the actual objects), it’s much more efficient to handle a count\nat the database level using SQL’s SELECT COUNT(*). Django provides a\ncount() method for precisely this reason.
list(). Force evaluation of a QuerySet by calling list() on\nit. For example:
entry_list = list(Entry.objects.all())\nbool(). Testing a QuerySet in a boolean context, such as using\nbool(), or, and or an if statement, will cause the query\nto be executed. If there is at least one result, the QuerySet is\nTrue, otherwise False. For example:
if Entry.objects.filter(headline="Test"):\n print("There is at least one Entry with the headline Test")\nNote: If you only want to determine if at least one result exists (and don’t\nneed the actual objects), it’s more efficient to use exists().
QuerySetsLink to this heading#If you pickle a QuerySet, this will force all the results to be loaded\ninto memory prior to pickling. Pickling is usually used as a precursor to\ncaching and when the cached queryset is reloaded, you want the results to\nalready be present and ready for use (reading from the database can take some\ntime, defeating the purpose of caching). This means that when you unpickle a\nQuerySet, it contains the results at the moment it was pickled, rather\nthan the results that are currently in the database.
If you only want to pickle the necessary information to recreate the\nQuerySet from the database at a later time, pickle the query attribute\nof the QuerySet. You can then recreate the original QuerySet (without\nany results loaded) using some code like this:
>>> import pickle\n>>> query = pickle.loads(s) # Assuming 's' is the pickled string.\n>>> qs = MyModel.objects.all()\n>>> qs.query = query # Restore the original 'query'.\nThe query attribute is an opaque object. It represents the internals of\nthe query construction and is not part of the public API. However, it is safe\n(and fully supported) to pickle and unpickle the attribute’s contents as\ndescribed here.
QuerySet APILink to this heading#Here’s the formal declaration of a QuerySet:
Usually when you’ll interact with a QuerySet you’ll use it by\nchaining filters. To make this work, most\nQuerySet methods return new querysets. These methods are covered in\ndetail later in this section.
The QuerySet class has two public attributes you can use for\nintrospection:
True if the QuerySet is ordered — i.e. has an\norder_by() clause or a default ordering on the model.\nFalse otherwise.
The database that will be used if this query is executed now.
\nQuerySetsLink to this heading#Django provides a range of QuerySet refinement methods that modify either\nthe types of results returned by the QuerySet or the way its SQL query is\nexecuted.
filter()Link to this heading#Returns a new QuerySet containing objects that match the given lookup\nparameters.
The lookup parameters (**kwargs) should be in the format described in\nField lookups below. Multiple parameters are joined via AND in the\nunderlying SQL statement.
If you need to execute more complex queries (for example, queries with OR statements),\nyou can use Q objects.
exclude()Link to this heading#Returns a new QuerySet containing objects that do not match the given\nlookup parameters.
The lookup parameters (**kwargs) should be in the format described in\nField lookups below. Multiple parameters are joined via AND in the\nunderlying SQL statement, and the whole thing is enclosed in a NOT().
This example excludes all entries whose pub_date is later than 2005-1-3\nAND whose headline is «Hello»:
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')\nIn SQL terms, that evaluates to:
\nSELECT ...\nWHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')\nThis example excludes all entries whose pub_date is later than 2005-1-3\nOR whose headline is «Hello»:
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello')\nIn SQL terms, that evaluates to:
\nSELECT ...\nWHERE NOT pub_date > '2005-1-3'\nAND NOT headline = 'Hello'\nNote the second example is more restrictive.
\nIf you need to execute more complex queries (for example, queries with OR statements),\nyou can use Q objects.
annotate()Link to this heading#Annotates each object in the QuerySet with the provided list of query\nexpressions. An expression may be a simple value, a\nreference to a field on the model (or any related models), or an aggregate\nexpression (averages, sums, etc.) that has been computed over the objects that\nare related to the objects in the QuerySet.
Each argument to annotate() is an annotation that will be added\nto each object in the QuerySet that is returned.
The aggregation functions that are provided by Django are described\nin Aggregation Functions below.
\nAnnotations specified using keyword arguments will use the keyword as\nthe alias for the annotation. Anonymous arguments will have an alias\ngenerated for them based upon the name of the aggregate function and\nthe model field that is being aggregated. Only aggregate expressions\nthat reference a single field can be anonymous arguments. Everything\nelse must be a keyword argument.
\nFor example, if you were manipulating a list of blogs, you may want\nto determine how many entries have been made in each blog:
\n>>> from django.db.models import Count\n>>> q = Blog.objects.annotate(Count('entry'))\n# The name of the first blog\n>>> q[0].name\n'Blogasaurus'\n# The number of entries on the first blog\n>>> q[0].entry__count\n42\nThe Blog model doesn’t define an entry__count attribute by itself,\nbut by using a keyword argument to specify the aggregate function, you can\ncontrol the name of the annotation:
>>> q = Blog.objects.annotate(number_of_entries=Count('entry'))\n# The number of entries on the first blog, using the name provided\n>>> q[0].number_of_entries\n42\nFor an in-depth discussion of aggregation, see the topic guide on\nAggregation.
\norder_by()Link to this heading#By default, results returned by a QuerySet are ordered by the ordering\ntuple given by the ordering option in the model’s Meta. You can\noverride this on a per-QuerySet basis by using the order_by method.
Example:
\nEntry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')\nThe result above will be ordered by pub_date descending, then by\nheadline ascending. The negative sign in front of "-pub_date" indicates\ndescending order. Ascending order is implied. To order randomly, use "?",\nlike so:
Entry.objects.order_by('?')\nNote: order_by('?') queries may be expensive and slow, depending on the\ndatabase backend you’re using.
To order by a field in a different model, use the same syntax as when you are\nquerying across model relations. That is, the name of the field, followed by a\ndouble underscore (__), followed by the name of the field in the new model,\nand so on for as many models as you want to join. For example:
Entry.objects.order_by('blog__name', 'headline')\nIf you try to order by a field that is a relation to another model, Django will\nuse the default ordering on the related model, or order by the related model’s\nprimary key if there is no Meta.ordering specified. For example, since the Blog\nmodel has no default ordering specified:
Entry.objects.order_by('blog')\n…is identical to:
\nEntry.objects.order_by('blog__id')\nIf Blog had ordering = ['name'], then the first queryset would be\nidentical to:
Entry.objects.order_by('blog__name')\nYou can also order by query expressions by\ncalling asc() or desc() on the\nexpression:
Entry.objects.order_by(Coalesce('summary', 'headline').desc())\nasc() and desc() have arguments\n(nulls_first and nulls_last) that control how null values are sorted.
Be cautious when ordering by fields in related models if you are also using\ndistinct(). See the note in distinct() for an explanation of how\nrelated model ordering can change the expected results.
There’s no way to specify whether ordering should be case sensitive. With\nrespect to case-sensitivity, Django will order results however your database\nbackend normally orders them.
\nYou can order by a field converted to lowercase with\nLower which will achieve case-consistent\nordering:
Entry.objects.order_by(Lower('headline').desc())\nIf you don’t want any ordering to be applied to a query, not even the default\nordering, call order_by() with no parameters.
You can tell if a query is ordered or not by checking the\nQuerySet.ordered attribute, which will be True if the\nQuerySet has been ordered in any way.
Each order_by() call will clear any previous ordering. For example, this\nquery will be ordered by pub_date and not headline:
Entry.objects.order_by('headline').order_by('pub_date')\nreverse()Link to this heading#Use the reverse() method to reverse the order in which a queryset’s\nelements are returned. Calling reverse() a second time restores the\nordering back to the normal direction.
To retrieve the «last» five items in a queryset, you could do this:
\nmy_queryset.reverse()[:5]\nNote that this is not quite the same as slicing from the end of a sequence in\nPython. The above example will return the last item first, then the\npenultimate item and so on. If we had a Python sequence and looked at\nseq[-5:], we would see the fifth-last item first. Django doesn’t support\nthat mode of access (slicing from the end), because it’s not possible to do it\nefficiently in SQL.
Also, note that reverse() should generally only be called on a QuerySet\nwhich has a defined ordering (e.g., when querying against a model which defines\na default ordering, or when using order_by()). If no such ordering is\ndefined for a given QuerySet, calling reverse() on it has no real\neffect (the ordering was undefined prior to calling reverse(), and will\nremain undefined afterward).
distinct()Link to this heading#Returns a new QuerySet that uses SELECT DISTINCT in its SQL query. This\neliminates duplicate rows from the query results.
By default, a QuerySet will not eliminate duplicate rows. In practice, this\nis rarely a problem, because simple queries such as Blog.objects.all()\ndon’t introduce the possibility of duplicate result rows. However, if your\nquery spans multiple tables, it’s possible to get duplicate results when a\nQuerySet is evaluated. That’s when you’d use distinct().
On PostgreSQL only, you can pass positional arguments (*fields) in order to\nspecify the names of fields to which the DISTINCT should apply. This\ntranslates to a SELECT DISTINCT ON SQL query. Here’s the difference. For a\nnormal distinct() call, the database compares each field in each row when\ndetermining which rows are distinct. For a distinct() call with specified\nfield names, the database will only compare the specified field names.
Examples (those after the first will only work on PostgreSQL):
\n>>> Author.objects.distinct()\n[...]\n\n>>> Entry.objects.order_by('pub_date').distinct('pub_date')\n[...]\n\n>>> Entry.objects.order_by('blog').distinct('blog')\n[...]\n\n>>> Entry.objects.order_by('author', 'pub_date').distinct('author', 'pub_date')\n[...]\n\n>>> Entry.objects.order_by('blog__name', 'mod_date').distinct('blog__name', 'mod_date')\n[...]\n\n>>> Entry.objects.order_by('author', 'pub_date').distinct('author')\n[...]\nvalues()Link to this heading#Returns a QuerySet that returns dictionaries, rather than model instances,\nwhen used as an iterable.
Each of those dictionaries represents an object, with the keys corresponding to\nthe attribute names of model objects.
\nThis example compares the dictionaries of values() with the normal model\nobjects:
# This list contains a Blog object.\n>>> Blog.objects.filter(name__startswith='Beatles')\n<QuerySet [<Blog: Beatles Blog>]>\n\n# This list contains a dictionary.\n>>> Blog.objects.filter(name__startswith='Beatles').values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\nThe values() method takes optional positional arguments, *fields, which\nspecify field names to which the SELECT should be limited. If you specify\nthe fields, each dictionary will contain only the field keys/values for the\nfields you specify. If you don’t specify the fields, each dictionary will\ncontain a key and value for every field in the database table.
Example:
\n>>> Blog.objects.values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\n>>> Blog.objects.values('id', 'name')\n<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>\nThe values() method also takes optional keyword arguments,\n**expressions, which are passed through to annotate():
>>> from django.db.models.functions import Lower\n>>> Blog.objects.values(lower_name=Lower('name'))\n<QuerySet [{'lower_name': 'beatles blog'}]>\nYou can use built-in and custom lookups in\nordering. For example:
\n>>> from django.db.models import CharField\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values('name__lower')\n<QuerySet [{'name__lower': 'beatles blog'}]>\nAn aggregate within a values() clause is applied before other arguments\nwithin the same values() clause. If you need to group by another value,\nadd it to an earlier values() clause instead. For example:
>>> from django.db.models import Count\n>>> Blog.objects.values('entry__authors', entries=Count('entry'))\n<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>\n>>> Blog.objects.values('entry__authors').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors': 1, 'entries': 33}]>\nA few subtleties that are worth mentioning:
\nIf you have a field called foo that is a\nForeignKey, the default values() call\nwill return a dictionary key called foo_id, since this is the name\nof the hidden model attribute that stores the actual value (the foo\nattribute refers to the related model). When you are calling\nvalues() and passing in field names, you can pass in either foo\nor foo_id and you will get back the same thing (the dictionary key\nwill match the field name you passed in).
For example:
\n>>> Entry.objects.values()\n<QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>\n\n>>> Entry.objects.values('blog')\n<QuerySet [{'blog': 1}, ...]>\n\n>>> Entry.objects.values('blog_id')\n<QuerySet [{'blog_id': 1}, ...]>\nWhen using values() together with distinct(), be aware that\nordering can affect the results. See the note in distinct() for\ndetails.
If you use a values() clause after an extra() call,\nany fields defined by a select argument in the extra() must\nbe explicitly included in the values() call. Any extra() call\nmade after a values() call will have its extra selected fields\nignored.
Calling only() and defer() after values() doesn’t make\nsense, so doing so will raise a NotImplementedError.
Combining transforms and aggregates requires the use of two annotate()\ncalls, either explicitly or as keyword arguments to values(). As above,\nif the transform has been registered on the relevant field type the first\nannotate() can be omitted, thus the following examples are equivalent:
>>> from django.db.models import CharField, Count\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values('entry__authors__name__lower').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.values(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.annotate(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).values('entry__authors__name__lower').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\nIt is useful when you know you’re only going to need values from a small number\nof the available fields and you won’t need the functionality of a model\ninstance object. It’s more efficient to select only the fields you need to use.
\nFinally, note that you can call filter(), order_by(), etc. after the\nvalues() call, that means that these two calls are identical:
Blog.objects.values().order_by('id')\nBlog.objects.order_by('id').values()\nThe people who made Django prefer to put all the SQL-affecting methods first,\nfollowed (optionally) by any output-affecting methods (such as values()),\nbut it doesn’t really matter. This is your chance to really flaunt your\nindividualism.
You can also refer to fields on related models with reverse relations through\nOneToOneField, ForeignKey and ManyToManyField attributes:
>>> Blog.objects.values('name', 'entry__headline')\n<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},\n {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>\nvalues_list()Link to this heading#This is similar to values() except that instead of returning dictionaries,\nit returns tuples when iterated over. Each tuple contains the value from the\nrespective field or expression passed into the values_list() call — so the\nfirst item is the first field, etc. For example:
>>> Entry.objects.values_list('id', 'headline')\n<QuerySet [(1, 'First entry'), ...]>\n>>> from django.db.models.functions import Lower\n>>> Entry.objects.values_list('id', Lower('headline'))\n<QuerySet [(1, 'first entry'), ...]>\nIf you only pass in a single field, you can also pass in the flat\nparameter. If True, this will mean the returned results are single values,\nrather than one-tuples. An example should make the difference clearer:
>>> Entry.objects.values_list('id').order_by('id')\n<QuerySet[(1,), (2,), (3,), ...]>\n\n>>> Entry.objects.values_list('id', flat=True).order_by('id')\n<QuerySet [1, 2, 3, ...]>\nIt is an error to pass in flat when there is more than one field.
You can pass named=True to get results as a\nnamedtuple():
>>> Entry.objects.values_list('id', 'headline', named=True)\n<QuerySet [Row(id=1, headline='First entry'), ...]>\nUsing a named tuple may make use of the results more readable, at the expense\nof a small performance penalty for transforming the results into a named tuple.
\nIf you don’t pass any values to values_list(), it will return all the\nfields in the model, in the order they were declared.
A common need is to get a specific field value of a certain model instance. To\nachieve that, use values_list() followed by a get() call:
>>> Entry.objects.values_list('headline', flat=True).get(pk=1)\n'First entry'\nvalues() and values_list() are both intended as optimizations for a\nspecific use case: retrieving a subset of data without the overhead of creating\na model instance. This metaphor falls apart when dealing with many-to-many and\nother multivalued relations (such as the one-to-many relation of a reverse\nforeign key) because the «one row, one object» assumption doesn’t hold.
For example, notice the behavior when querying across a\nManyToManyField:
>>> Author.objects.values_list('name', 'entry__headline')\n<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),\n ('George Orwell', 'Why Socialists Do Not Believe in Fun'),\n ('George Orwell', 'In Defence of English Cooking'),\n ('Don Quixote', None)]>\nAuthors with multiple entries appear multiple times and authors without any\nentries have None for the entry headline.
Similarly, when querying a reverse foreign key, None appears for entries\nnot having any author:
>>> Entry.objects.values_list('authors')\n<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>\ndates()Link to this heading#Returns a QuerySet that evaluates to a list of datetime.date\nobjects representing all available dates of a particular kind within the\ncontents of the QuerySet.
field should be the name of a DateField of your model.\nkind should be either "year", "month", "week", or "day".\nEach datetime.date object in the result list is «truncated» to the\ngiven type.
"year" returns a list of all distinct year values for the field.
"month" returns a list of all distinct year/month values for the\nfield.
"week" returns a list of all distinct year/week values for the field. All\ndates will be a Monday.
"day" returns a list of all distinct year/month/day values for the\nfield.
order, which defaults to 'ASC', should be either 'ASC' or\n'DESC'. This specifies how to order the results.
Examples:
\n>>> Entry.objects.dates('pub_date', 'year')\n[datetime.date(2005, 1, 1)]\n>>> Entry.objects.dates('pub_date', 'month')\n[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]\n>>> Entry.objects.dates('pub_date', 'week')\n[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]\n>>> Entry.objects.dates('pub_date', 'day')\n[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]\n>>> Entry.objects.dates('pub_date', 'day', order='DESC')\n[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]\n>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')\n[datetime.date(2005, 3, 20)]\ndatetimes()Link to this heading#Returns a QuerySet that evaluates to a list of datetime.datetime\nobjects representing all available dates of a particular kind within the\ncontents of the QuerySet.
field_name should be the name of a DateTimeField of your model.
kind should be either "year", "month", "week", "day",\n"hour", "minute", or "second". Each datetime.datetime\nobject in the result list is «truncated» to the given type.
order, which defaults to 'ASC', should be either 'ASC' or\n'DESC'. This specifies how to order the results.
tzinfo defines the time zone to which datetimes are converted prior to\ntruncation. Indeed, a given datetime has different representations depending\non the time zone in use. This parameter must be a datetime.tzinfo\nobject. If it’s None, Django uses the current time zone. It has no effect when USE_TZ is\nFalse.
none()Link to this heading#Calling none() will create a queryset that never returns any objects and no\nquery will be executed when accessing the results. A qs.none() queryset\nis an instance of EmptyQuerySet.
Examples:
\n>>> Entry.objects.none()\n<QuerySet []>\n>>> from django.db.models.query import EmptyQuerySet\n>>> isinstance(Entry.objects.none(), EmptyQuerySet)\nTrue\nall()Link to this heading#Returns a copy of the current QuerySet (or QuerySet subclass). This\ncan be useful in situations where you might want to pass in either a model\nmanager or a QuerySet and do further filtering on the result. After calling\nall() on either object, you’ll definitely have a QuerySet to work with.
When a QuerySet is evaluated, it\ntypically caches its results. If the data in the database might have changed\nsince a QuerySet was evaluated, you can get updated results for the same\nquery by calling all() on a previously evaluated QuerySet.
union()Link to this heading#Uses SQL’s UNION operator to combine the results of two or more\nQuerySets. For example:
>>> qs1.union(qs2, qs3)\nThe UNION operator selects only distinct values by default. To allow\nduplicate values, use the all=True argument.
union(), intersection(), and difference() return model instances\nof the type of the first QuerySet even if the arguments are QuerySets\nof other models. Passing different models works as long as the SELECT list\nis the same in all QuerySets (at least the types, the names don’t matter\nas long as the types in the same order). In such cases, you must use the column\nnames from the first QuerySet in QuerySet methods applied to the\nresulting QuerySet. For example:
>>> qs1 = Author.objects.values_list('name')\n>>> qs2 = Entry.objects.values_list('headline')\n>>> qs1.union(qs2).order_by('name')\nIn addition, only LIMIT, OFFSET, COUNT(*), ORDER BY, and\nspecifying columns (i.e. slicing, count(), order_by(), and\nvalues()/values_list()) are allowed on the resulting\nQuerySet. Further, databases place restrictions on what operations are\nallowed in the combined queries. For example, most databases don’t allow\nLIMIT or OFFSET in the combined queries.
intersection()Link to this heading#Uses SQL’s INTERSECT operator to return the shared elements of two or more\nQuerySets. For example:
>>> qs1.intersection(qs2, qs3)\nSee union() for some restrictions.
difference()Link to this heading#Uses SQL’s EXCEPT operator to keep only elements present in the\nQuerySet but not in some other QuerySets. For example:
>>> qs1.difference(qs2, qs3)\nSee union() for some restrictions.
extra()Link to this heading#Sometimes, the Django query syntax by itself can’t easily express a complex\nWHERE clause. For these edge cases, Django provides the extra()\nQuerySet modifier — a hook for injecting specific clauses into the SQL\ngenerated by a QuerySet.
By definition, these extra lookups may not be portable to different database\nengines (because you’re explicitly writing SQL code) and violate the DRY\nprinciple, so you should avoid them if possible.
\nSpecify one or more of params, select, where or tables. None\nof the arguments is required, but you should use at least one of them.
select
The select argument lets you put extra fields in the SELECT\nclause. It should be a dictionary mapping attribute names to SQL\nclauses to use to calculate that attribute.
Example:
\nEntry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nAs a result, each Entry object will have an extra attribute,\nis_recent, a boolean representing whether the entry’s pub_date\nis greater than Jan. 1, 2006.
Django inserts the given SQL snippet directly into the SELECT\nstatement, so the resulting SQL of the above example would be something\nlike:
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent\nFROM blog_entry;\nThe next example is more advanced; it does a subquery to give each\nresulting Blog object an entry_count attribute, an integer count\nof associated Entry objects:
Blog.objects.extra(\n select={\n 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'\n },\n)\nIn this particular case, we’re exploiting the fact that the query will\nalready contain the blog_blog table in its FROM clause.
The resulting SQL of the above example would be:
\nSELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count\nFROM blog_blog;\nNote that the parentheses required by most database engines around\nsubqueries are not required in Django’s select clauses. Also note\nthat some database backends, such as some MySQL versions, don’t support\nsubqueries.
In some rare cases, you might wish to pass parameters to the SQL\nfragments in extra(select=...). For this purpose, use the\nselect_params parameter. Since select_params is a sequence and\nthe select attribute is a dictionary, some care is required so that\nthe parameters are matched up correctly with the extra select pieces.\nIn this situation, you should use a collections.OrderedDict for\nthe select value, not just a normal Python dictionary.
This will work, for example:
\nBlog.objects.extra(\n select=OrderedDict([('a', '%s'), ('b', '%s')]),\n select_params=('one', 'two'))\nIf you need to use a literal %s inside your select string, use\nthe sequence %%s.
where / tables
You can define explicit SQL WHERE clauses — perhaps to perform\nnon-explicit joins — by using where. You can manually add tables to\nthe SQL FROM clause by using tables.
where and tables both take a list of strings. All where\nparameters are «AND»ed to any other search criteria.
Example:
\nEntry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])\n…translates (roughly) into the following SQL:
\nSELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')\nBe careful when using the tables parameter if you’re specifying\ntables that are already used in the query. When you add extra tables\nvia the tables parameter, Django assumes you want that table\nincluded an extra time, if it is already included. That creates a\nproblem, since the table name will then be given an alias. If a table\nappears multiple times in an SQL statement, the second and subsequent\noccurrences must use aliases so the database can tell them apart. If\nyou’re referring to the extra table you added in the extra where\nparameter this is going to cause errors.
Normally you’ll only be adding extra tables that don’t already appear\nin the query. However, if the case outlined above does occur, there are\na few solutions. First, see if you can get by without including the\nextra table and use the one already in the query. If that isn’t\npossible, put your extra() call at the front of the queryset\nconstruction so that your table is the first use of that table.\nFinally, if all else fails, look at the query produced and rewrite your\nwhere addition to use the alias given to your extra table. The\nalias will be the same each time you construct the queryset in the same\nway, so you can rely upon the alias name to not change.
order_by
If you need to order the resulting queryset using some of the new\nfields or tables you have included via extra() use the order_by\nparameter to extra() and pass in a sequence of strings. These\nstrings should either be model fields (as in the normal\norder_by() method on querysets), of the form\ntable_name.column_name or an alias for a column that you specified\nin the select parameter to extra().
For example:
\nq = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nq = q.extra(order_by = ['-is_recent'])\nThis would sort all the items for which is_recent is true to the\nfront of the result set (True sorts before False in a\ndescending ordering).
This shows, by the way, that you can make multiple calls to extra()\nand it will behave as you expect (adding new constraints each time).
params
The where parameter described above may use standard Python\ndatabase string placeholders — '%s' to indicate parameters the\ndatabase engine should automatically quote. The params argument is\na list of any extra parameters to be substituted.
Example:
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\nAlways use params instead of embedding values directly into\nwhere because params will ensure values are quoted correctly\naccording to your particular backend. For example, quotes will be\nescaped correctly.
Bad:
\nEntry.objects.extra(where=["headline='Lennon'"])\nGood:
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\ndefer()Link to this heading#In some complex data-modeling situations, your models might contain a lot of\nfields, some of which could contain a lot of data (for example, text fields),\nor require expensive processing to convert them to Python objects. If you are\nusing the results of a queryset in some situation where you don’t know\nif you need those particular fields when you initially fetch the data, you can\ntell Django not to retrieve them from the database.
\nThis is done by passing the names of the fields to not load to defer():
Entry.objects.defer("headline", "body")\nA queryset that has deferred fields will still return model instances. Each\ndeferred field will be retrieved from the database if you access that field\n(one at a time, not all the deferred fields at once).
\nYou can make multiple calls to defer(). Each call adds new fields to the\ndeferred set:
# Defers both the body and headline fields.\nEntry.objects.defer("body").filter(rating=5).defer("headline")\nThe order in which fields are added to the deferred set does not matter.\nCalling defer() with a field name that has already been deferred is\nharmless (the field will still be deferred).
You can defer loading of fields in related models (if the related models are\nloading via select_related()) by using the standard double-underscore\nnotation to separate related fields:
Blog.objects.select_related().defer("entry__headline", "entry__body")\nIf you want to clear the set of deferred fields, pass None as a parameter\nto defer():
# Load all fields immediately.\nmy_queryset.defer(None)\nSome fields in a model won’t be deferred, even if you ask for them. You can\nnever defer the loading of the primary key. If you are using\nselect_related() to retrieve related models, you shouldn’t defer the\nloading of the field that connects from the primary model to the related\none, doing so will result in an error.
only()Link to this heading#The only() method is more or less the opposite of defer(). You call\nit with the fields that should not be deferred when retrieving a model. If\nyou have a model where almost all the fields need to be deferred, using\nonly() to specify the complementary set of fields can result in simpler\ncode.
Suppose you have a model with fields name, age and biography. The\nfollowing two querysets are the same, in terms of deferred fields:
Person.objects.defer("age", "biography")\nPerson.objects.only("name")\nWhenever you call only() it replaces the set of fields to load\nimmediately. The method’s name is mnemonic: only those fields are loaded\nimmediately; the remainder are deferred. Thus, successive calls to only()\nresult in only the final fields being considered:
# This will defer all fields except the headline.\nEntry.objects.only("body", "rating").only("headline")\nSince defer() acts incrementally (adding fields to the deferred list), you\ncan combine calls to only() and defer() and things will behave\nlogically:
# Final result is that everything except "headline" is deferred.\nEntry.objects.only("headline", "body").defer("body")\n\n# Final result loads headline and body immediately (only() replaces any\n# existing set of fields).\nEntry.objects.defer("body").only("headline", "body")\nAll of the cautions in the note for the defer() documentation apply to\nonly() as well. Use it cautiously and only after exhausting your other\noptions.
Using only() and omitting a field requested using select_related()\nis an error as well.
using()Link to this heading#This method is for controlling which database the QuerySet will be\nevaluated against if you are using more than one database. The only argument\nthis method takes is the alias of a database, as defined in\nDATABASES.
For example:
\n# queries the database with the 'default' alias.\n>>> Entry.objects.all()\n\n# queries the database with the 'backup' alias\n>>> Entry.objects.using('backup')\nselect_for_update()Link to this heading#Returns a queryset that will lock rows until the end of the transaction,\ngenerating a SELECT ... FOR UPDATE SQL statement on supported databases.
For example:
\nfrom django.db import transaction\n\nentries = Entry.objects.select_for_update().filter(author=request.user)\nwith transaction.atomic():\n for entry in entries:\n ...\nWhen the queryset is evaluated (for entry in entries in this case), all\nmatched entries will be locked until the end of the transaction block, meaning\nthat other transactions will be prevented from changing or acquiring locks on\nthem.
Usually, if another transaction has already acquired a lock on one of the\nselected rows, the query will block until the lock is released. If this is\nnot the behavior you want, call select_for_update(nowait=True). This will\nmake the call non-blocking. If a conflicting lock is already acquired by\nanother transaction, DatabaseError will be raised when the\nqueryset is evaluated. You can also ignore locked rows by using\nselect_for_update(skip_locked=True) instead. The nowait and\nskip_locked are mutually exclusive and attempts to call\nselect_for_update() with both options enabled will result in a\nValueError.
By default, select_for_update() locks all rows that are selected by the\nquery. For example, rows of related objects specified in select_related()\nare locked in addition to rows of the queryset’s model. If this isn’t desired,\nspecify the related objects you want to lock in select_for_update(of=(...))\nusing the same fields syntax as select_related(). Use the value 'self'\nto refer to the queryset’s model.
You can’t use select_for_update() on nullable relations:
>>> Person.objects.select_related('hometown').select_for_update()\nTraceback (most recent call last):\n...\ndjango.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join\nTo avoid that restriction, you can exclude null objects if you don’t care about\nthem:
\n>>> Person.objects.select_related('hometown').select_for_update().exclude(hometown=None)\n<QuerySet [<Person: ...)>, ...]>\nCurrently, the postgresql, oracle, and mysql database\nbackends support select_for_update(). However, MySQL doesn’t support the\nof argument and the nowait and skip_locked arguments are supported\nonly on MySQL 8.0.1+.
Passing nowait=True, skip_locked=True, or of to\nselect_for_update() using database backends that do not support these\noptions, such as MySQL, raises a NotSupportedError. This\nprevents code from unexpectedly blocking.
Evaluating a queryset with select_for_update() in autocommit mode on\nbackends which support SELECT ... FOR UPDATE is a\nTransactionManagementError error because the\nrows are not locked in that case. If allowed, this would facilitate data\ncorruption and could easily be caused by calling code that expects to be run in\na transaction outside of one.
Using select_for_update() on backends which do not support\nSELECT ... FOR UPDATE (such as SQLite) will have no effect.\nSELECT ... FOR UPDATE will not be added to the query, and an error isn’t\nraised if select_for_update() is used in autocommit mode.
raw()Link to this heading#Takes a raw SQL query, executes it, and returns a\ndjango.db.models.query.RawQuerySet instance. This RawQuerySet instance\ncan be iterated over just like an normal QuerySet to provide object instances.
See the Performing raw SQL queries for more information.
\n\nQuerySetsLink to this heading#Combined querysets must use the same model.
\n&)Link to this heading#Combines two QuerySets using the SQL AND operator.
The following are equivalent:
\nModel.objects.filter(x=1) & Model.objects.filter(y=2)\nModel.objects.filter(x=1, y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) & Q(y=2))\nSQL equivalent:
\nSELECT ... WHERE x=1 AND y=2\n|)Link to this heading#Combines two QuerySets using the SQL OR operator.
The following are equivalent:
\nModel.objects.filter(x=1) | Model.objects.filter(y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) | Q(y=2))\nSQL equivalent:
\nSELECT ... WHERE x=1 OR y=2\nQuerySetsLink to this heading#The following QuerySet methods evaluate the QuerySet and return\nsomething other than a QuerySet.
These methods do not use a cache (see Caching and QuerySets). Rather,\nthey query the database each time they’re called.
\nget()Link to this heading#Returns the object matching the given lookup parameters, which should be in\nthe format described in Field lookups.
\nget() raises MultipleObjectsReturned if more\nthan one object was found. The\nMultipleObjectsReturned exception is an\nattribute of the model class.
get() raises a DoesNotExist exception if an\nobject wasn’t found for the given parameters. This exception is an attribute\nof the model class. Example:
Entry.objects.get(id='foo') # raises Entry.DoesNotExist\nThe DoesNotExist exception inherits from\ndjango.core.exceptions.ObjectDoesNotExist, so you can target multiple\nDoesNotExist exceptions. Example:
from django.core.exceptions import ObjectDoesNotExist\ntry:\n e = Entry.objects.get(id=3)\n b = Blog.objects.get(id=1)\nexcept ObjectDoesNotExist:\n print("Either the entry or blog doesn't exist.")\nIf you expect a queryset to return one row, you can use get() without any\narguments to return the object for that row:
entry = Entry.objects.filter(...).exclude(...).get()\ncreate()Link to this heading#A convenience method for creating an object and saving it all in one step. Thus:
\np = Person.objects.create(first_name="Bruce", last_name="Springsteen")\nand:
\np = Person(first_name="Bruce", last_name="Springsteen")\np.save(force_insert=True)\nare equivalent.
\nThe force_insert parameter is documented\nelsewhere, but all it means is that a new object will always be created.\nNormally you won’t need to worry about this. However, if your model contains a\nmanual primary key value that you set and if that value already exists in the\ndatabase, a call to create() will fail with an\nIntegrityError since primary keys must be unique. Be\nprepared to handle the exception if you are using manual primary keys.
get_or_create()Link to this heading#A convenience method for looking up an object with the given kwargs (may be\nempty if your model has defaults for all fields), creating one if necessary.
Returns a tuple of (object, created), where object is the retrieved or\ncreated object and created is a boolean specifying whether a new object was\ncreated.
This is meant to prevent duplicate objects from being created when requests are\nmade in parallel, and as a shortcut to boilerplatish code. For example:
\ntry:\n obj = Person.objects.get(first_name='John', last_name='Lennon')\nexcept Person.DoesNotExist:\n obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))\n obj.save()\nHere, with concurrent requests, multiple attempts to save a Person with\nthe same parameters may be made. To avoid this race condition, the above\nexample can be rewritten using get_or_create() like so:
obj, created = Person.objects.get_or_create(\n first_name='John',\n last_name='Lennon',\n defaults={'birthday': date(1940, 10, 9)},\n)\nAny keyword arguments passed to get_or_create() — except an optional one\ncalled defaults — will be used in a get() call. If an object is\nfound, get_or_create() returns a tuple of that object and False.
You can specify more complex conditions for the retrieved object by chaining\nget_or_create() with filter() and using Q objects. For example, to retrieve Robert or Bob Marley if either\nexists, and create the latter otherwise:
from django.db.models import Q\n\nobj, created = Person.objects.filter(\n Q(first_name='Bob') | Q(first_name='Robert'),\n).get_or_create(last_name='Marley', defaults={'first_name': 'Bob'})\nIf multiple objects are found, get_or_create() raises\nMultipleObjectsReturned. If an object is not\nfound, get_or_create() will instantiate and save a new object, returning a\ntuple of the new object and True. The new object will be created roughly\naccording to this algorithm:
params = {k: v for k, v in kwargs.items() if '__' not in k}\nparams.update({k: v() if callable(v) else v for k, v in defaults.items()})\nobj = self.model(**params)\nobj.save()\nIn English, that means start with any non-'defaults' keyword argument that\ndoesn’t contain a double underscore (which would indicate a non-exact lookup).\nThen add the contents of defaults, overriding any keys if necessary, and\nuse the result as the keyword arguments to the model class. If there are any\ncallables in defaults, evaluate them. As hinted at above, this is a\nsimplification of the algorithm that is used, but it contains all the pertinent\ndetails. The internal implementation has some more error-checking than this and\nhandles some extra edge-conditions; if you’re interested, read the code.
If you have a field named defaults and want to use it as an exact lookup in\nget_or_create(), just use 'defaults__exact', like so:
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})\nThe get_or_create() method has similar error behavior to create()\nwhen you’re using manually specified primary keys. If an object needs to be\ncreated and the key already exists in the database, an\nIntegrityError will be raised.
Finally, a word on using get_or_create() in Django views. Please make sure\nto use it only in POST requests unless you have a good reason not to.\nGET requests shouldn’t have any effect on data. Instead, use POST\nwhenever a request to a page has a side effect on your data. For more, see\nSafe methods in the HTTP spec.
update_or_create()Link to this heading#A convenience method for updating an object with the given kwargs, creating\na new one if necessary. The defaults is a dictionary of (field, value)\npairs used to update the object. The values in defaults can be callables.
Returns a tuple of (object, created), where object is the created or\nupdated object and created is a boolean specifying whether a new object was\ncreated.
The update_or_create method tries to fetch an object from database based on\nthe given kwargs. If a match is found, it updates the fields passed in the\ndefaults dictionary.
This is meant as a shortcut to boilerplatish code. For example:
\ndefaults = {'first_name': 'Bob'}\ntry:\n obj = Person.objects.get(first_name='John', last_name='Lennon')\n for key, value in defaults.items():\n setattr(obj, key, value)\n obj.save()\nexcept Person.DoesNotExist:\n new_values = {'first_name': 'John', 'last_name': 'Lennon'}\n new_values.update(defaults)\n obj = Person(**new_values)\n obj.save()\nThis pattern gets quite unwieldy as the number of fields in a model goes up.\nThe above example can be rewritten using update_or_create() like so:
obj, created = Person.objects.update_or_create(\n first_name='John', last_name='Lennon',\n defaults={'first_name': 'Bob'},\n)\nFor detailed description how names passed in kwargs are resolved see\nget_or_create().
As described above in get_or_create(), this method is prone to a\nrace-condition which can result in multiple rows being inserted simultaneously\nif uniqueness is not enforced at the database level.
Like get_or_create() and create(), if you’re using manually\nspecified primary keys and an object needs to be created but the key already\nexists in the database, an IntegrityError is raised.
bulk_create()Link to this heading#This method inserts the provided list of objects into the database in an\nefficient manner (generally only 1 query, no matter how many objects there\nare):
\n>>> Entry.objects.bulk_create([\n... Entry(headline='This is a test'),\n... Entry(headline='This is only a test'),\n... ])\nThis has a number of caveats though:
\nThe model’s save() method will not be called, and the pre_save and\npost_save signals will not be sent.
It does not work with child models in a multi-table inheritance scenario.
If the model’s primary key is an AutoField it\ndoes not retrieve and set the primary key attribute, as save() does,\nunless the database backend supports it (currently PostgreSQL).
It does not work with many-to-many relationships.
It casts objs to a list, which fully evaluates objs if it’s a\ngenerator. The cast allows inspecting all objects so that any objects with a\nmanually set primary key can be inserted first. If you want to insert objects\nin batches without evaluating the entire generator at once, you can use this\ntechnique as long as the objects don’t have any manually set primary keys:
from itertools import islice\n\nbatch_size = 100\nobjs = (Entry(headline='Test %s' % i) for i in range(1000))\nwhile True:\n batch = list(islice(objs, batch_size))\n if not batch:\n break\n Entry.objects.bulk_create(batch, batch_size)\nThe batch_size parameter controls how many objects are created in a single\nquery. The default is to create all objects in one batch, except for SQLite\nwhere the default is such that at most 999 variables per query are used.
On databases that support it (all except PostgreSQL < 9.5 and Oracle), setting\nthe ignore_conflicts parameter to True tells the database to ignore\nfailure to insert any rows that fail constraints such as duplicate unique\nvalues. Enabling this parameter disables setting the primary key on each model\ninstance (if the database normally supports it).
bulk_update()Link to this heading#This method efficiently updates the given fields on the provided model\ninstances, generally with one query:
\n>>> objs = [\n... Entry.objects.create(headline='Entry 1'),\n... Entry.objects.create(headline='Entry 2'),\n... ]\n>>> objs[0].headline = 'This is entry 1'\n>>> objs[1].headline = 'This is entry 2'\n>>> Entry.objects.bulk_update(objs, ['headline'])\nQuerySet.update() is used to save the changes, so this is more efficient\nthan iterating through the list of models and calling save() on each of\nthem, but it has a few caveats:
You cannot update the model’s primary key.
Each model’s save() method isn’t called, and the\npre_save and\npost_save signals aren’t sent.
If updating a large number of columns in a large number of rows, the SQL\ngenerated can be very large. Avoid this by specifying a suitable\nbatch_size.
Updating fields defined on multi-table inheritance ancestors will incur an\nextra query per ancestor.
If objs contains duplicates, only the first one is updated.
The batch_size parameter controls how many objects are saved in a single\nquery. The default is to update all objects in one batch, except for SQLite\nand Oracle which have restrictions on the number of variables used in a query.
count()Link to this heading#Returns an integer representing the number of objects in the database matching\nthe QuerySet.
Example:
\n# Returns the total number of entries in the database.\nEntry.objects.count()\n\n# Returns the number of entries whose headline contains 'Lennon'\nEntry.objects.filter(headline__contains='Lennon').count()\nA count() call performs a SELECT COUNT(*) behind the scenes, so you\nshould always use count() rather than loading all of the record into Python\nobjects and calling len() on the result (unless you need to load the\nobjects into memory anyway, in which case len() will be faster).
Note that if you want the number of items in a QuerySet and are also\nretrieving model instances from it (for example, by iterating over it), it’s\nprobably more efficient to use len(queryset) which won’t cause an extra\ndatabase query like count() would.
in_bulk()Link to this heading#Takes a list of field values (id_list) and the field_name for those\nvalues, and returns a dictionary mapping each value to an instance of the\nobject with the given field value. If id_list isn’t provided, all objects\nin the queryset are returned. field_name must be a unique field, and it\ndefaults to the primary key.
Example:
\n>>> Blog.objects.in_bulk([1])\n{1: <Blog: Beatles Blog>}\n>>> Blog.objects.in_bulk([1, 2])\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}\n>>> Blog.objects.in_bulk([])\n{}\n>>> Blog.objects.in_bulk()\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}\n>>> Blog.objects.in_bulk(['beatles_blog'], field_name='slug')\n{'beatles_blog': <Blog: Beatles Blog>}\nIf you pass in_bulk() an empty list, you’ll get an empty dictionary.
iterator()Link to this heading#Evaluates the QuerySet (by performing the query) and returns an iterator\n(see PEP 234) over the results. A QuerySet typically caches its results\ninternally so that repeated evaluations do not result in additional queries. In\ncontrast, iterator() will read results directly, without doing any caching\nat the QuerySet level (internally, the default iterator calls iterator()\nand caches the return value). For a QuerySet which returns a large number of\nobjects that you only need to access once, this can result in better\nperformance and a significant reduction in memory.
Note that using iterator() on a QuerySet which has already been\nevaluated will force it to evaluate again, repeating the query.
Also, use of iterator() causes previous prefetch_related() calls to be\nignored since these two optimizations do not make sense together.
Depending on the database backend, query results will either be loaded all at\nonce or streamed from the database using server-side cursors.
\nOracle and PostgreSQL use server-side\ncursors to stream results from the database without loading the entire result\nset into memory.
\nThe Oracle database driver always uses server-side cursors.
\nWith server-side cursors, the chunk_size parameter specifies the number of\nresults to cache at the database driver level. Fetching bigger chunks\ndiminishes the number of round trips between the database driver and the\ndatabase, at the expense of memory.
On PostgreSQL, server-side cursors will only be used when the\nDISABLE_SERVER_SIDE_CURSORS\nsetting is False. Read Transaction pooling and server-side cursors if\nyou’re using a connection pooler configured in transaction pooling mode. When\nserver-side cursors are disabled, the behavior is the same as databases that\ndon’t support server-side cursors.
MySQL doesn’t support streaming results, hence the Python database driver loads\nthe entire result set into memory. The result set is then transformed into\nPython row objects by the database adapter using the fetchmany() method\ndefined in PEP 249.
SQLite can fetch results in batches using fetchmany(), but since SQLite\ndoesn’t provide isolation between queries within a connection, be careful when\nwriting to the table being iterated over. See Isolation when using QuerySet.iterator() for\nmore information.
The chunk_size parameter controls the size of batches Django retrieves from\nthe database driver. Larger batches decrease the overhead of communicating with\nthe database driver at the expense of a slight increase in memory consumption.
The default value of chunk_size, 2000, comes from a calculation on the\npsycopg mailing list:
\n\n\nAssuming rows of 10-20 columns with a mix of textual and numeric data, 2000\nis going to fetch less than 100KB of data, which seems a good compromise\nbetween the number of rows transferred and the data discarded if the loop\nis exited early.
\n
latest()Link to this heading#Returns the latest object in the table based on the given field(s).
\nThis example returns the latest Entry in the table, according to the\npub_date field:
Entry.objects.latest('pub_date')\nYou can also choose the latest based on several fields. For example, to select\nthe Entry with the earliest expire_date when two entries have the same\npub_date:
Entry.objects.latest('pub_date', '-expire_date')\nThe negative sign in '-expire_date' means to sort expire_date in\ndescending order. Since latest() gets the last result, the Entry with\nthe earliest expire_date is selected.
If your model’s Meta specifies\nget_latest_by, you can omit any arguments to\nearliest() or latest(). The fields specified in\nget_latest_by will be used by default.
Like get(), earliest() and latest() raise\nDoesNotExist if there is no object with the\ngiven parameters.
Note that earliest() and latest() exist purely for convenience and\nreadability.
earliest()Link to this heading#Works otherwise like latest() except\nthe direction is changed.
first()Link to this heading#Returns the first object matched by the queryset, or None if there\nis no matching object. If the QuerySet has no ordering defined, then the\nqueryset is automatically ordered by the primary key. This can affect\naggregation results as described in Interaction with default ordering or order_by().
Example:
\np = Article.objects.order_by('title', 'pub_date').first()\nNote that first() is a convenience method, the following code sample is\nequivalent to the above example:
try:\n p = Article.objects.order_by('title', 'pub_date')[0]\nexcept IndexError:\n p = None\nlast()Link to this heading#Works like first(), but returns the last object in the queryset.
aggregate()Link to this heading#Returns a dictionary of aggregate values (averages, sums, etc.) calculated over\nthe QuerySet. Each argument to aggregate() specifies a value that will\nbe included in the dictionary that is returned.
The aggregation functions that are provided by Django are described in\nAggregation Functions below. Since aggregates are also query\nexpressions, you may combine aggregates with other\naggregates or values to create complex aggregates.
\nAggregates specified using keyword arguments will use the keyword as the name\nfor the annotation. Anonymous arguments will have a name generated for them\nbased upon the name of the aggregate function and the model field that is being\naggregated. Complex aggregates cannot use anonymous arguments and must specify\na keyword argument as an alias.
\nFor example, when you are working with blog entries, you may want to know the\nnumber of authors that have contributed blog entries:
\n>>> from django.db.models import Count\n>>> q = Blog.objects.aggregate(Count('entry'))\n{'entry__count': 16}\nBy using a keyword argument to specify the aggregate function, you can\ncontrol the name of the aggregation value that is returned:
\n>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))\n{'number_of_entries': 16}\nFor an in-depth discussion of aggregation, see the topic guide on\nAggregation.
\nexists()Link to this heading#Returns True if the QuerySet contains any results, and False\nif not. This tries to perform the query in the simplest and fastest way\npossible, but it does execute nearly the same query as a normal\nQuerySet query.
exists() is useful for searches relating to both\nobject membership in a QuerySet and to the existence of any objects in\na QuerySet, particularly in the context of a large QuerySet.
The most efficient method of finding whether a model with a unique field\n(e.g. primary_key) is a member of a QuerySet is:
entry = Entry.objects.get(pk=123)\nif some_queryset.filter(pk=entry.pk).exists():\n print("Entry contained in queryset")\nWhich will be faster than the following which requires evaluating and iterating\nthrough the entire queryset:
\nif entry in some_queryset:\n print("Entry contained in QuerySet")\nAnd to find whether a queryset contains any items:
\nif some_queryset.exists():\n print("There is at least one object in some_queryset")\nWhich will be faster than:
\nif some_queryset:\n print("There is at least one object in some_queryset")\n… but not by a large degree (hence needing a large queryset for efficiency\ngains).
\nAdditionally, if a some_queryset has not yet been evaluated, but you know\nthat it will be at some point, then using some_queryset.exists() will do\nmore overall work (one query for the existence check plus an extra one to later\nretrieve the results) than simply using bool(some_queryset), which\nretrieves the results and then checks if any were returned.
update()Link to this heading#Performs an SQL update query for the specified fields, and returns\nthe number of rows matched (which may not be equal to the number of rows\nupdated if some rows already have the new value).
\nFor example, to turn comments off for all blog entries published in 2010,\nyou could do this:
\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n(This assumes your Entry model has fields pub_date and comments_on.)
You can update multiple fields — there’s no limit on how many. For example,\nhere we update the comments_on and headline fields:
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')\nThe update() method is applied instantly, and the only restriction on the\nQuerySet that is updated is that it can only update columns in the\nmodel’s main table, not on related models. You can’t do this, for example:
>>> Entry.objects.update(blog__name='foo') # Won't work!\nFiltering based on related fields is still possible, though:
\n>>> Entry.objects.filter(blog__id=1).update(comments_on=True)\nYou cannot call update() on a QuerySet that has had a slice taken\nor can otherwise no longer be filtered.
The update() method returns the number of affected rows:
>>> Entry.objects.filter(id=64).update(comments_on=True)\n1\n\n>>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)\n0\n\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n132\nIf you’re just updating a record and don’t need to do anything with the model\nobject, the most efficient approach is to call update(), rather than\nloading the model object into memory. For example, instead of doing this:
e = Entry.objects.get(id=10)\ne.comments_on = False\ne.save()\n…do this:
\nEntry.objects.filter(id=10).update(comments_on=False)\nUsing update() also prevents a race condition wherein something might\nchange in your database in the short period of time between loading the object\nand calling save().
Finally, realize that update() does an update at the SQL level and, thus,\ndoes not call any save() methods on your models, nor does it emit the\npre_save or\npost_save signals (which are a consequence of\ncalling Model.save()). If you want to\nupdate a bunch of records for a model that has a custom\nsave() method, loop over them and call\nsave(), like this:
for e in Entry.objects.filter(pub_date__year=2010):\n e.comments_on = False\n e.save()\ndelete()Link to this heading#Performs an SQL delete query on all rows in the QuerySet and\nreturns the number of objects deleted and a dictionary with the number of\ndeletions per object type.
The delete() is applied instantly. You cannot call delete() on a\nQuerySet that has had a slice taken or can otherwise no longer be\nfiltered.
For example, to delete all the entries in a particular blog:
\n>>> b = Blog.objects.get(pk=1)\n\n# Delete all the entries belonging to this Blog.\n>>> Entry.objects.filter(blog=b).delete()\n(4, {'weblog.Entry': 2, 'weblog.Entry_authors': 2})\nBy default, Django’s ForeignKey emulates the SQL\nconstraint ON DELETE CASCADE — in other words, any objects with foreign\nkeys pointing at the objects to be deleted will be deleted along with them.\nFor example:
>>> blogs = Blog.objects.all()\n\n# This will delete all Blogs and all of their Entry objects.\n>>> blogs.delete()\n(5, {'weblog.Blog': 1, 'weblog.Entry': 2, 'weblog.Entry_authors': 2})\nThis cascade behavior is customizable via the\non_delete argument to the\nForeignKey.
The delete() method does a bulk delete and does not call any delete()\nmethods on your models. It does, however, emit the\npre_delete and\npost_delete signals for all deleted objects\n(including cascaded deletions).
Django needs to fetch objects into memory to send signals and handle cascades.\nHowever, if there are no cascades and no signals, then Django may take a\nfast-path and delete objects without fetching into memory. For large\ndeletes this can result in significantly reduced memory usage. The amount of\nexecuted queries can be reduced, too.
\nForeignKeys which are set to on_delete\nDO_NOTHING do not prevent taking the fast-path in deletion.
Note that the queries generated in object deletion is an implementation\ndetail subject to change.
\nas_manager()Link to this heading#Class method that returns an instance of Manager\nwith a copy of the QuerySet’s methods. See\nCreating a manager with QuerySet methods for more details.
explain()Link to this heading#Returns a string of the QuerySet’s execution plan, which details how the\ndatabase would execute the query, including any indexes or joins that would be\nused. Knowing these details may help you improve the performance of slow\nqueries.
For example, when using PostgreSQL:
\n>>> print(Blog.objects.filter(title='My Blog').explain())\nSeq Scan on blog (cost=0.00..35.50 rows=10 width=12)\n Filter: (title = 'My Blog'::bpchar)\nThe output differs significantly between databases.
\nexplain() is supported by all built-in database backends except Oracle\nbecause an implementation there isn’t straightforward.
The format parameter changes the output format from the databases’s default,\nusually text-based. PostgreSQL supports 'TEXT', 'JSON', 'YAML', and\n'XML'. MySQL supports 'TEXT' (also called 'TRADITIONAL') and\n'JSON'.
Some databases accept flags that can return more information about the query.\nPass these flags as keyword arguments. For example, when using PostgreSQL:
\n>>> print(Blog.objects.filter(title='My Blog').explain(verbose=True))\nSeq Scan on public.blog (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1)\n Output: id, title\n Filter: (blog.title = 'My Blog'::bpchar)\nPlanning time: 0.064 ms\nExecution time: 0.058 ms\nOn some databases, flags may cause the query to be executed which could have\nadverse effects on your database. For example, PostgreSQL’s ANALYZE flag\ncould result in changes to data if there are triggers or if a function is\ncalled, even for a SELECT query.
Field lookupsLink to this heading#Field lookups are how you specify the meat of an SQL WHERE clause. They’re\nspecified as keyword arguments to the QuerySet methods filter(),\nexclude() and get().
For an introduction, see models and database queries documentation.
\nDjango’s built-in lookups are listed below. It is also possible to write\ncustom lookups for model fields.
\nAs a convenience when no lookup type is provided (like in\nEntry.objects.get(id=14)) the lookup type is assumed to be exact.
exactLink to this heading#Exact match. If the value provided for comparison is None, it will be\ninterpreted as an SQL NULL (see isnull for more details).
Examples:
\nEntry.objects.get(id__exact=14)\nEntry.objects.get(id__exact=None)\nSQL equivalents:
\nSELECT ... WHERE id = 14;\nSELECT ... WHERE id IS NULL;\niexactLink to this heading#Case-insensitive exact match. If the value provided for comparison is None,\nit will be interpreted as an SQL NULL (see isnull for more\ndetails).
Example:
\nBlog.objects.get(name__iexact='beatles blog')\nBlog.objects.get(name__iexact=None)\nSQL equivalents:
\nSELECT ... WHERE name ILIKE 'beatles blog';\nSELECT ... WHERE name IS NULL;\nNote the first query will match 'Beatles Blog', 'beatles blog',\n'BeAtLes BLoG', etc.
containsLink to this heading#Case-sensitive containment test.
\nExample:
\nEntry.objects.get(headline__contains='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE '%Lennon%';\nNote this will match the headline 'Lennon honored today' but not 'lennon\nhonored today'.
icontainsLink to this heading#Case-insensitive containment test.
\nExample:
\nEntry.objects.get(headline__icontains='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE '%Lennon%';\ninLink to this heading#In a given iterable; often a list, tuple, or queryset. It’s not a common use\ncase, but strings (being iterables) are accepted.
\nExamples:
\nEntry.objects.filter(id__in=[1, 3, 4])\nEntry.objects.filter(headline__in='abc')\nSQL equivalents:
\nSELECT ... WHERE id IN (1, 3, 4);\nSELECT ... WHERE headline IN ('a', 'b', 'c');\nYou can also use a queryset to dynamically evaluate the list of values\ninstead of providing a list of literal values:
\ninner_qs = Blog.objects.filter(name__contains='Cheddar')\nentries = Entry.objects.filter(blog__in=inner_qs)\nThis queryset will be evaluated as subselect statement:
\nSELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')\nIf you pass in a QuerySet resulting from values() or values_list()\nas the value to an __in lookup, you need to ensure you are only extracting\none field in the result. For example, this will work (filtering on the blog\nnames):
inner_qs = Blog.objects.filter(name__contains='Ch').values('name')\nentries = Entry.objects.filter(blog__name__in=inner_qs)\nThis example will raise an exception, since the inner query is trying to\nextract two field values, where only one is expected:
\n# Bad code! Will raise a TypeError.\ninner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')\nentries = Entry.objects.filter(blog__name__in=inner_qs)\ngtLink to this heading#Greater than.
\nExample:
\nEntry.objects.filter(id__gt=4)\nSQL equivalent:
\nSELECT ... WHERE id > 4;\ngteLink to this heading#Greater than or equal to.
\nltLink to this heading#Less than.
\nlteLink to this heading#Less than or equal to.
\nstartswithLink to this heading#Case-sensitive starts-with.
\nExample:
\nEntry.objects.filter(headline__startswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE 'Lennon%';\nSQLite doesn’t support case-sensitive LIKE statements; startswith acts\nlike istartswith for SQLite.
istartswithLink to this heading#Case-insensitive starts-with.
\nExample:
\nEntry.objects.filter(headline__istartswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE 'Lennon%';\nendswithLink to this heading#Case-sensitive ends-with.
\nExample:
\nEntry.objects.filter(headline__endswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE '%Lennon';\niendswithLink to this heading#Case-insensitive ends-with.
\nExample:
\nEntry.objects.filter(headline__iendswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE '%Lennon'\nrangeLink to this heading#Range test (inclusive).
\nExample:
\nimport datetime\nstart_date = datetime.date(2005, 1, 1)\nend_date = datetime.date(2005, 3, 31)\nEntry.objects.filter(pub_date__range=(start_date, end_date))\nSQL equivalent:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';\nYou can use range anywhere you can use BETWEEN in SQL — for dates,\nnumbers and even characters.
dateLink to this heading#For datetime fields, casts the value as date. Allows chaining additional field\nlookups. Takes a date value.
\nExample:
\nEntry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))\nEntry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, fields are converted to the current time\nzone before filtering. This requires time zone definitions in the\ndatabase.
yearLink to this heading#For date and datetime fields, an exact year match. Allows chaining additional\nfield lookups. Takes an integer year.
\nExample:
\nEntry.objects.filter(pub_date__year=2005)\nEntry.objects.filter(pub_date__year__gte=2005)\nSQL equivalent:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';\nSELECT ... WHERE pub_date >= '2005-01-01';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
iso_yearLink to this heading#For date and datetime fields, an exact ISO 8601 week-numbering year match.\nAllows chaining additional field lookups. Takes an integer year.
\nExample:
\nEntry.objects.filter(pub_date__iso_year=2005)\nEntry.objects.filter(pub_date__iso_year__gte=2005)\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
monthLink to this heading#For date and datetime fields, an exact month match. Allows chaining additional\nfield lookups. Takes an integer 1 (January) through 12 (December).
\nExample:
\nEntry.objects.filter(pub_date__month=12)\nEntry.objects.filter(pub_date__month__gte=6)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';\nSELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
dayLink to this heading#For date and datetime fields, an exact day match. Allows chaining additional\nfield lookups. Takes an integer day.
\nExample:
\nEntry.objects.filter(pub_date__day=3)\nEntry.objects.filter(pub_date__day__gte=3)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';\nSELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';\n(The exact SQL syntax varies for each database engine.)
\nNote this will match any record with a pub_date on the third day of the month,\nsuch as January 3, July 3, etc.
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
weekLink to this heading#For date and datetime fields, return the week number (1-52 or 53) according\nto ISO-8601, i.e., weeks start\non a Monday and the first week contains the year’s first Thursday.
\nExample:
\nEntry.objects.filter(pub_date__week=52)\nEntry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
week_dayLink to this heading#For date and datetime fields, a “day of the week” match. Allows chaining\nadditional field lookups.
\nTakes an integer value representing the day of week from 1 (Sunday) to 7\n(Saturday).
\nExample:
\nEntry.objects.filter(pub_date__week_day=2)\nEntry.objects.filter(pub_date__week_day__gte=2)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nNote this will match any record with a pub_date that falls on a Monday (day\n2 of the week), regardless of the month or year in which it occurs. Week days\nare indexed with day 1 being Sunday and day 7 being Saturday.
When USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
quarterLink to this heading#For date and datetime fields, a “quarter of the year” match. Allows chaining\nadditional field lookups. Takes an integer value between 1 and 4 representing\nthe quarter of the year.
\nExample to retrieve entries in the second quarter (April 1 to June 30):
\nEntry.objects.filter(pub_date__quarter=2)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
timeLink to this heading#For datetime fields, casts the value as time. Allows chaining additional field\nlookups. Takes a datetime.time value.
Example:
\nEntry.objects.filter(pub_date__time=datetime.time(14, 30))\nEntry.objects.filter(pub_date__time__range=(datetime.time(8), datetime.time(17)))\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, fields are converted to the current time\nzone before filtering. This requires time zone definitions in the\ndatabase.
hourLink to this heading#For datetime and time fields, an exact hour match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 23.
\nExample:
\nEvent.objects.filter(timestamp__hour=23)\nEvent.objects.filter(time__hour=5)\nEvent.objects.filter(timestamp__hour__gte=12)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';\nSELECT ... WHERE EXTRACT('hour' FROM time) = '5';\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
minuteLink to this heading#For datetime and time fields, an exact minute match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 59.
\nExample:
\nEvent.objects.filter(timestamp__minute=29)\nEvent.objects.filter(time__minute=46)\nEvent.objects.filter(timestamp__minute__gte=29)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';\nSELECT ... WHERE EXTRACT('minute' FROM time) = '46';\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
secondLink to this heading#For datetime and time fields, an exact second match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 59.
\nExample:
\nEvent.objects.filter(timestamp__second=31)\nEvent.objects.filter(time__second=2)\nEvent.objects.filter(timestamp__second__gte=31)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';\nSELECT ... WHERE EXTRACT('second' FROM time) = '2';\nSELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
isnullLink to this heading#Takes either True or False, which correspond to SQL queries of\nIS NULL and IS NOT NULL, respectively.
Example:
\nEntry.objects.filter(pub_date__isnull=True)\nSQL equivalent:
\nSELECT ... WHERE pub_date IS NULL;\nregexLink to this heading#Case-sensitive regular expression match.
\nThe regular expression syntax is that of the database backend in use.\nIn the case of SQLite, which has no built in regular expression support,\nthis feature is provided by a (Python) user-defined REGEXP function, and\nthe regular expression syntax is therefore that of Python’s re module.
Example:
\nEntry.objects.get(title__regex=r'^(An?|The) +')\nSQL equivalents:
\nSELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); -- Oracle\n\nSELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite\nUsing raw strings (e.g., r'foo' instead of 'foo') for passing in the\nregular expression syntax is recommended.
iregexLink to this heading#Case-insensitive regular expression match.
\nExample:
\nEntry.objects.get(title__iregex=r'^(an?|the) +')\nSQL equivalents:
\nSELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle\n\nSELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite\nDjango provides the following aggregation functions in the\ndjango.db.models module. For details on how to use these\naggregate functions, see the topic guide on aggregation. See the Aggregate\ndocumentation to learn how to create your aggregates.
All aggregates have the following parameters in common:
\nexpressionsLink to this heading#Strings that reference fields on the model, or query expressions.
\noutput_fieldLink to this heading#An optional argument that represents the model field\nof the return value
\n\nfilterLink to this heading#An optional Q object that’s used to filter the\nrows that are aggregated.
See Conditional aggregation and Filtering on annotations for\nexample usage.
\n**extraLink to this heading#Keyword arguments that can provide extra context for the SQL generated\nby the aggregate.
\nAvgLink to this heading#Returns the mean value of the given expression, which must be numeric\nunless you specify a different output_field.
Default alias: <field>__avg
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
CountLink to this heading#Returns the number of objects that are related through the provided\nexpression.
\nDefault alias: <field>__count
Return type: int
Has one optional argument:
\nIf distinct=True, the count will only include unique instances.\nThis is the SQL equivalent of COUNT(DISTINCT <field>). The default\nvalue is False.
MaxLink to this heading#Returns the maximum value of the given expression.
\nDefault alias: <field>__max
Return type: same as input field, or output_field if supplied
MinLink to this heading#Returns the minimum value of the given expression.
\nDefault alias: <field>__min
Return type: same as input field, or output_field if supplied
StdDevLink to this heading#Returns the standard deviation of the data in the provided expression.
\nDefault alias: <field>__stddev
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
Has one optional argument:
\nBy default, StdDev returns the population standard deviation. However,\nif sample=True, the return value will be the sample standard deviation.
SumLink to this heading#Computes the sum of all values of the given expression.
\nDefault alias: <field>__sum
Return type: same as input field, or output_field if supplied
VarianceLink to this heading#Returns the variance of the data in the provided expression.
\nDefault alias: <field>__variance
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
Has one optional argument:
\nBy default, Variance returns the population variance. However,\nif sample=True, the return value will be the sample variance.