Query expressions describe a value or a computation that can be used as part of\nan update, create, filter, order by, annotation, or aggregate. There are a\nnumber of built-in expressions (documented below) that can be used to help you\nwrite queries. Expressions can be combined, or in some cases nested, to form\nmore complex computations.
\n\nDjango supports addition, subtraction, multiplication, division, modulo\narithmetic, and the power operator on query expressions, using Python constants,\nvariables, and even other expressions.
\nfrom django.db.models import F, Count, Value\nfrom django.db.models.functions import Length, Upper\n\n# Find companies that have more employees than chairs.\nCompany.objects.filter(num_employees__gt=F('num_chairs'))\n\n# Find companies that have at least twice as many employees\n# as chairs. Both the querysets below are equivalent.\nCompany.objects.filter(num_employees__gt=F('num_chairs') * 2)\nCompany.objects.filter(\n num_employees__gt=F('num_chairs') + F('num_chairs'))\n\n# How many chairs are needed for each company to seat all employees?\n>>> company = Company.objects.filter(\n... num_employees__gt=F('num_chairs')).annotate(\n... chairs_needed=F('num_employees') - F('num_chairs')).first()\n>>> company.num_employees\n120\n>>> company.num_chairs\n50\n>>> company.chairs_needed\n70\n\n# Create a new company using expressions.\n>>> company = Company.objects.create(name='Google', ticker=Upper(Value('goog')))\n# Be sure to refresh it if you need to access the field.\n>>> company.refresh_from_db()\n>>> company.ticker\n'GOOG'\n\n# Annotate models with an aggregated value. Both forms\n# below are equivalent.\nCompany.objects.annotate(num_products=Count('products'))\nCompany.objects.annotate(num_products=Count(F('products')))\n\n# Aggregates can contain complex computations also\nCompany.objects.annotate(num_offerings=Count(F('products') + F('services')))\n\n# Expressions can also be used in order_by()\nCompany.objects.order_by(Length('name').asc())\nCompany.objects.order_by(Length('name').desc())\nF() expressionsLink to this heading#An F() object represents the value of a model field or annotated column. It\nmakes it possible to refer to model field values and perform database\noperations using them without actually having to pull them out of the database\ninto Python memory.
Instead, Django uses the F() object to generate an SQL expression that\ndescribes the required operation at the database level.
This is easiest to understand through an example. Normally, one might do\nsomething like this:
\n# Tintin filed a news story!\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed += 1\nreporter.save()\nHere, we have pulled the value of reporter.stories_filed from the database\ninto memory and manipulated it using familiar Python operators, and then saved\nthe object back to the database. But instead we could also have done:
from django.db.models import F\n\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\nAlthough reporter.stories_filed = F('stories_filed') + 1 looks like a\nnormal Python assignment of value to an instance attribute, in fact it's an SQL\nconstruct describing an operation on the database.
When Django encounters an instance of F(), it overrides the standard Python\noperators to create an encapsulated SQL expression; in this case, one which\ninstructs the database to increment the database field represented by\nreporter.stories_filed.
Whatever value is or was on reporter.stories_filed, Python never gets to\nknow about it - it is dealt with entirely by the database. All Python does,\nthrough Django's F() class, is create the SQL syntax to refer to the field\nand describe the operation.
To access the new value saved this way, the object must be reloaded:
\nreporter = Reporters.objects.get(pk=reporter.pk)\n# Or, more succinctly:\nreporter.refresh_from_db()\nAs well as being used in operations on single instances as above, F() can\nbe used on QuerySets of object instances, with update(). This reduces\nthe two queries we were using above - the get() and the\nsave() - to just one:
reporter = Reporters.objects.filter(name='Tintin')\nreporter.update(stories_filed=F('stories_filed') + 1)\nWe can also use update() to increment\nthe field value on multiple objects - which could be very much faster than\npulling them all into Python from the database, looping over them, incrementing\nthe field value of each one, and saving each one back to the database:
Reporter.objects.all().update(stories_filed=F('stories_filed') + 1)\nF() therefore can offer performance advantages by:
getting the database, rather than Python, to do work
reducing the number of queries some operations require
F()Link to this heading#Another useful benefit of F() is that having the database - rather than\nPython - update a field's value avoids a race condition.
If two Python threads execute the code in the first example above, one thread\ncould retrieve, increment, and save a field's value after the other has\nretrieved it from the database. The value that the second thread saves will be\nbased on the original value; the work of the first thread will simply be lost.
\nIf the database is responsible for updating the field, the process is more\nrobust: it will only ever update the field based on the value of the field in\nthe database when the save() or update() is executed, rather\nthan based on its value when the instance was retrieved.
F() assignments persist after Model.save()Link to this heading#F() objects assigned to model fields persist after saving the model\ninstance and will be applied on each save(). For example:
reporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\n\nreporter.name = 'Tintin Jr.'\nreporter.save()\nstories_filed will be updated twice in this case. If it's initially 1,\nthe final value will be 3.
F() in filtersLink to this heading#F() is also very useful in QuerySet filters, where they make it\npossible to filter a set of objects against criteria based on their field\nvalues, rather than on Python values.
This is documented in using F() expressions in queries.
\nF() with annotationsLink to this heading#F() can be used to create dynamic fields on your models by combining\ndifferent fields with arithmetic:
company = Company.objects.annotate(\n chairs_needed=F('num_employees') - F('num_chairs'))\nIf the fields that you're combining are of different types you'll need\nto tell Django what kind of field will be returned. Since F() does not\ndirectly support output_field you will need to wrap the expression with\nExpressionWrapper:
from django.db.models import DateTimeField, ExpressionWrapper, F\n\nTicket.objects.annotate(\n expires=ExpressionWrapper(\n F('active_at') + F('duration'), output_field=DateTimeField()))\nWhen referencing relational fields such as ForeignKey, F() returns the\nprimary key value rather than a model instance:
>> car = Company.objects.annotate(built_by=F('manufacturer'))[0]\n>> car.manufacturer\n<Manufacturer: Toyota>\n>> car.built_by\n3\nFunc() expressionsLink to this heading#Func() expressions are the base type of all expressions that involve\ndatabase functions like COALESCE and LOWER, or aggregates like SUM.\nThey can be used directly:
from django.db.models import Func, F\n\nqueryset.annotate(field_lower=Func(F('field'), function='LOWER'))\nor they can be used to build a library of database functions:
\nclass Lower(Func):\n function = 'LOWER'\n\nqueryset.annotate(field_lower=Lower('field'))\nBut both cases will result in a queryset where each model is annotated with an\nextra attribute field_lower produced, roughly, from the following SQL:
SELECT\n ...\n LOWER("db_table"."field") as "field_lower"\nSee Database Functions for a list of built-in database functions.
\nThe Func API is as follows:
A class attribute describing the function that will be generated.\nSpecifically, the function will be interpolated as the function\nplaceholder within template. Defaults to None.
A class attribute, as a format string, that describes the SQL that is\ngenerated for this function. Defaults to\n'%(function)s(%(expressions)s)'.
If you're constructing SQL like strftime('%W', 'date') and need a\nliteral % character in the query, quadruple it (%%%%) in the\ntemplate attribute because the string is interpolated twice: once\nduring the template interpolation in as_sql() and once in the SQL\ninterpolation with the query parameters in the database cursor.
A class attribute that denotes the character used to join the list of\nexpressions together. Defaults to ', '.
A class attribute that denotes the number of arguments the function\naccepts. If this attribute is set and the function is called with a\ndifferent number of expressions, TypeError will be raised. Defaults\nto None.
Generates the SQL for the database function.
\nThe as_vendor() methods should use the function, template,\narg_joiner, and any other **extra_context parameters to\ncustomize the SQL as needed. For example:
django/db/models/functions.pyclass ConcatPair(Func):\n ...\n function = 'CONCAT'\n ...\n\n def as_mysql(self, compiler, connection):\n return super(ConcatPair, self).as_sql(\n compiler, connection,\n function='CONCAT_WS',\n template="%(function)s('', %(expressions)s)",\n )\nThe *expressions argument is a list of positional expressions that the\nfunction will be applied to. The expressions will be converted to strings,\njoined together with arg_joiner, and then interpolated into the template\nas the expressions placeholder.
Positional arguments can be expressions or Python values. Strings are\nassumed to be column references and will be wrapped in F() expressions\nwhile other values will be wrapped in Value() expressions.
The **extra kwargs are key=value pairs that can be interpolated\ninto the template attribute. The function, template, and\narg_joiner keywords can be used to replace the attributes of the same name\nwithout having to define your own class. output_field can be used to define\nthe expected return type.
Aggregate() expressionsLink to this heading#An aggregate expression is a special case of a Func() expression that informs the query that a GROUP BY clause\nis required. All of the aggregate functions,\nlike Sum() and Count(), inherit from Aggregate().
Since Aggregates are expressions and wrap expressions, you can represent\nsome complex computations:
from django.db.models import Count\n\nCompany.objects.annotate(\n managers_required=(Count('num_employees') / 4) + Count('num_managers'))\nThe Aggregate API is as follows:
A class attribute, as a format string, that describes the SQL that is\ngenerated for this aggregate. Defaults to\n'%(function)s( %(expressions)s )'.
A class attribute describing the aggregate function that will be\ngenerated. Specifically, the function will be interpolated as the\nfunction placeholder within template. Defaults to None.
The expression argument can be the name of a field on the model, or another\nexpression. It will be converted to a string and used as the expressions\nplaceholder within the template.
The output_field argument requires a model field instance, like\nIntegerField() or BooleanField(), into which Django will load the value\nafter it's retrieved from the database. Usually no arguments are needed when\ninstantiating the model field as any arguments relating to data validation\n(max_length, max_digits, etc.) will not be enforced on the expression's\noutput value.
Note that output_field is only required when Django is unable to determine\nwhat field type the result should be. Complex expressions that mix field types\nshould define the desired output_field. For example, adding an\nIntegerField() and a FloatField() together should probably have\noutput_field=FloatField() defined.
The **extra kwargs are key=value pairs that can be interpolated\ninto the template attribute.
Creating your own aggregate is extremely easy. At a minimum, you need\nto define function, but you can also completely customize the\nSQL that is generated. Here's a brief example:
from django.db.models import Aggregate\n\nclass Count(Aggregate):\n # supports COUNT(distinct field)\n function = 'COUNT'\n template = '%(function)s(%(distinct)s%(expressions)s)'\n\n def __init__(self, expression, distinct=False, **extra):\n super(Count, self).__init__(\n expression,\n distinct='DISTINCT ' if distinct else '',\n output_field=IntegerField(),\n **extra\n )\nValue() expressionsLink to this heading#A Value() object represents the smallest possible component of an\nexpression: a simple value. When you need to represent the value of an integer,\nboolean, or string within an expression, you can wrap that value within a\nValue().
You will rarely need to use Value() directly. When you write the expression\nF('field') + 1, Django implicitly wraps the 1 in a Value(),\nallowing simple values to be used in more complex expressions. You will need to\nuse Value() when you want to pass a string to an expression. Most\nexpressions interpret a string argument as the name of a field, like\nLower('name').
The value argument describes the value to be included in the expression,\nsuch as 1, True, or None. Django knows how to convert these Python\nvalues into their corresponding database type.
The output_field argument should be a model field instance, like\nIntegerField() or BooleanField(), into which Django will load the value\nafter it's retrieved from the database. Usually no arguments are needed when\ninstantiating the model field as any arguments relating to data validation\n(max_length, max_digits, etc.) will not be enforced on the expression's\noutput value.
ExpressionWrapper() expressionsLink to this heading#ExpressionWrapper simply surrounds another expression and provides access\nto properties, such as output_field, that may not be available on other\nexpressions. ExpressionWrapper is necessary when using arithmetic on\nF() expressions with different types as described in\nUsing F() with annotations.
Conditional expressions allow you to use if ... elif ...\nelse logic in queries. Django natively supports SQL CASE\nexpressions. For more details see Conditional Expressions.
Sometimes database expressions can't easily express a complex WHERE clause.\nIn these edge cases, use the RawSQL expression. For example:
>>> from django.db.models.expressions import RawSQL\n>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))\nThese extra lookups may not be portable to different database engines (because\nyou're explicitly writing SQL code) and violate the DRY principle, so you\nshould avoid them if possible.
\n\nBelow you'll find technical implementation details that may be useful to\nlibrary authors. The technical API and examples below will help with\ncreating generic query expressions that can extend the built-in functionality\nthat Django provides.
\nQuery expressions implement the query expression API,\nbut also expose a number of extra methods and attributes listed below. All\nquery expressions must inherit from Expression() or a relevant\nsubclass.
When a query expression wraps another expression, it is responsible for\ncalling the appropriate methods on the wrapped expression.
\nTells Django that this expression contains an aggregate and that a\nGROUP BY clause needs to be added to the query.
Provides the chance to do any pre-processing or validation of\nthe expression before it's added to the query. resolve_expression()\nmust also be called on any nested expressions. A copy() of self\nshould be returned with any necessary transformations.
query is the backend query implementation.
allow_joins is a boolean that allows or denies the use of\njoins in the query.
reuse is a set of reusable joins for multi-join scenarios.
summarize is a boolean that, when True, signals that the\nquery being computed is a terminal aggregate query.
Returns an ordered list of inner expressions. For example:
\n>>> Sum(F('foo')).get_source_expressions()\n[F('foo')]\nTakes a list of expressions and stores them such that\nget_source_expressions() can return them.
Returns a clone (copy) of self, with any column aliases relabeled.\nColumn aliases are renamed when subqueries are created.\nrelabeled_clone() should also be called on any nested expressions\nand assigned to the clone.
change_map is a dictionary mapping old aliases to new aliases.
実装例:
\ndef relabeled_clone(self, change_map):\n clone = copy.copy(self)\n clone.expression = self.expression.relabeled_clone(change_map)\n return clone\nA hook allowing the expression to coerce value into a more\nappropriate type.
Responsible for returning the list of columns references by\nthis expression. get_group_by_cols() should be called on any\nnested expressions. F() objects, in particular, hold a reference\nto a column.
Returns the expression ready to be sorted in ascending order.
\nReturns the expression ready to be sorted in descending order.
\nReturns self with any modifications required to reverse the sort\norder within an order_by call. As an example, an expression\nimplementing NULLS LAST would change its value to be\nNULLS FIRST. Modifications are only required for expressions that\nimplement sort order like OrderBy. This method is called when\nreverse() is called on a\nqueryset.
You can write your own query expression classes that use, and can integrate\nwith, other query expressions. Let's step through an example by writing an\nimplementation of the COALESCE SQL function, without using the built-in\nFunc() expressions.
The COALESCE SQL function is defined as taking a list of columns or\nvalues. It will return the first column or value that isn't NULL.
We'll start by defining the template to be used for SQL generation and\nan __init__() method to set some attributes:
import copy\nfrom django.db.models import Expression\n\nclass Coalesce(Expression):\n template = 'COALESCE( %(expressions)s )'\n\n def __init__(self, expressions, output_field):\n super(Coalesce, self).__init__(output_field=output_field)\n if len(expressions) < 2:\n raise ValueError('expressions must have at least 2 elements')\n for expression in expressions:\n if not hasattr(expression, 'resolve_expression'):\n raise TypeError('%r is not an Expression' % expression)\n self.expressions = expressions\nWe do some basic validation on the parameters, including requiring at least\n2 columns or values, and ensuring they are expressions. We are requiring\noutput_field here so that Django knows what kind of model field to assign\nthe eventual result to.
Now we implement the pre-processing and validation. Since we do not have\nany of our own validation at this point, we just delegate to the nested\nexpressions:
\ndef resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False):\n c = self.copy()\n c.is_summary = summarize\n for pos, expression in enumerate(self.expressions):\n c.expressions[pos] = expression.resolve_expression(query, allow_joins, reuse, summarize, for_save)\n return c\nNext, we write the method responsible for generating the SQL:
\ndef as_sql(self, compiler, connection, template=None):\n sql_expressions, sql_params = [], []\n for expression in self.expressions:\n sql, params = compiler.compile(expression)\n sql_expressions.append(sql)\n sql_params.extend(params)\n template = template or self.template\n data = {'expressions': ','.join(sql_expressions)}\n return template % data, params\n\ndef as_oracle(self, compiler, connection):\n """\n Example of vendor specific handling (Oracle in this case).\n Let's make the function name lowercase.\n """\n return self.as_sql(compiler, connection, template='coalesce( %(expressions)s )')\nas_sql() methods can support custom keyword arguments, allowing\nas_vendorname() methods to override data used to generate the SQL string.\nUsing as_sql() keyword arguments for customization is preferable to\nmutating self within as_vendorname() methods as the latter can lead to\nerrors when running on different database backends. If your class relies on\nclass attributes to define data, consider allowing overrides in your\nas_sql() method.
We generate the SQL for each of the expressions by using the\ncompiler.compile() method, and join the result together with commas.\nThen the template is filled out with our data and the SQL and parameters\nare returned.
We've also defined a custom implementation that is specific to the Oracle\nbackend. The as_oracle() function will be called instead of as_sql()\nif the Oracle backend is in use.
Finally, we implement the rest of the methods that allow our query expression\nto play nice with other query expressions:
\ndef get_source_expressions(self):\n return self.expressions\n\ndef set_source_expressions(self, expressions):\n self.expressions = expressions\nLet's see how it works:
\n>>> from django.db.models import F, Value, CharField\n>>> qs = Company.objects.annotate(\n... tagline=Coalesce([\n... F('motto'),\n... F('ticker_name'),\n... F('description'),\n... Value('No Tagline')\n... ], output_field=CharField()))\n>>> for c in qs:\n... print("%s: %s" % (c.name, c.tagline))\n...\nGoogle: Do No Evil\nApple: AAPL\nYahoo: Internet Company\nDjango Software Foundation: No Tagline\nIf you're using a database backend that uses a different SQL syntax for a\ncertain function, you can add support for it by monkey patching a new method\nonto the function's class.
\nLet's say we're writing a backend for Microsoft's SQL Server which uses the SQL\nLEN instead of LENGTH for the Length function.\nWe'll monkey patch a new method called as_sqlserver() onto the Length\nclass:
from django.db.models.functions import Length\n\ndef sqlserver_length(self, compiler, connection):\n return self.as_sql(compiler, connection, function='LEN')\n\nLength.as_sqlserver = sqlserver_length\nYou can also customize the SQL using the template parameter of as_sql().
We use as_sqlserver() because django.db.connection.vendor returns\nsqlserver for the backend.
Third-party backends can register their functions in the top level\n__init__.py file of the backend package or in a top level expressions.py\nfile (or package) that is imported from the top level __init__.py.
For user projects wishing to patch the backend that they're using, this code\nshould live in an AppConfig.ready() method.