Fixed #14030 -- Allowed annotations to accept all expressions

4 files changed, 599 insertions, 134 deletions

diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
new file mode 100644
index 0000000000..5dadf35873
--- /dev/null
+++ b/docs/ref/models/expressions.txt
@@ -0,0 +1,522 @@
+=================
+Query Expressions
+=================
+
+.. currentmodule:: django.db.models
+
+Query expressions describe a value or a computation that can be used as part of
+a filter, an annotation, or an aggregation. There are a number of built-in
+expressions (documented below) that can be used to help you write queries.
+Expressions can be combined, or in some cases nested, to form more complex
+computations.
+
+Supported arithmetic
+====================
+
+Django supports addition, subtraction, multiplication, division, modulo
+arithmetic, and the power operator on query expressions, using Python constants,
+variables, and even other expressions.
+
+.. versionadded:: 1.7
+
+    Support for the power operator ``**`` was added.
+
+Some examples
+=============
+
+.. versionchanged:: 1.8
+
+    Some of the examples rely on functionality that is new in Django 1.8.
+
+.. code-block:: python
+
+    # Find companies that have more employees than chairs.
+    Company.objects.filter(num_employees__gt=F('num_chairs'))
+
+    # Find companies that have at least twice as many employees
+    # as chairs. Both the querysets below are equivalent.
+    Company.objects.filter(num_employees__gt=F('num_chairs') * 2)
+    Company.objects.filter(
+        num_employees__gt=F('num_chairs') + F('num_chairs'))
+
+    # How many chairs are needed for each company to seat all employees?
+    >>> company = Company.objects.filter(
+    ...    num_employees__gt=F('num_chairs')).annotate(
+    ...    chairs_needed=F('num_employees') - F('num_chairs')).first()
+    >>> company.num_employees
+    120
+    >>> company.num_chairs
+    50
+    >>> company.chairs_needed
+    70
+
+    # Annotate models with an aggregated value. Both forms
+    # below are equivalent.
+    Company.objects.annotate(num_products=Count('products'))
+    Company.objects.annotate(num_products=Count(F('products')))
+
+    # Aggregates can contain complex computations also
+    Company.objects.annotate(num_offerings=Count(F('products') + F('services')))
+
+
+Built-in Expressions
+====================
+
+``F()`` expressions
+-------------------
+
+.. class:: F
+
+An ``F()`` object represents the value of a model field or annotated column. It
+makes it possible to refer to model field values and perform  database
+operations using them without actually having to pull them out of the  database
+into Python memory.
+
+Instead, Django uses the ``F()`` object to generate a SQL expression that
+describes the required operation at the database level.
+
+This is easiest to understand through an example. Normally, one might do
+something like this::
+
+    # Tintin filed a news story!
+    reporter = Reporters.objects.get(name='Tintin')
+    reporter.stories_filed += 1
+    reporter.save()
+
+Here, we have pulled the value of ``reporter.stories_filed`` from the database
+into memory and manipulated it using familiar Python operators, and then saved
+the object back to the database. But instead we could also have done::
+
+    from django.db.models import F
+    reporter = Reporters.objects.get(name='Tintin')
+    reporter.stories_filed = F('stories_filed') + 1
+    reporter.save()
+
+Although ``reporter.stories_filed = F('stories_filed') + 1`` looks like a
+normal Python assignment of value to an instance attribute, in fact it's an SQL
+construct describing an operation on the database.
+
+When Django encounters an instance of ``F()``, it overrides the standard Python
+operators to create an encapsulated SQL expression; in this case, one which
+instructs the database to increment the database field represented by
+``reporter.stories_filed``.
+
+Whatever value is or was on ``reporter.stories_filed``, Python never gets to
+know about it - it is dealt with entirely by the database. All Python does,
+through Django's ``F()`` class, is create the SQL syntax to refer to the field
+and describe the operation.
+
+.. note::
+
+   In order to access the new value that has been saved in this way, the object
+   will need to be reloaded::
+
+       reporter = Reporters.objects.get(pk=reporter.pk)
+
+As well as being used in operations on single instances as above, ``F()`` can
+be used on ``QuerySets`` of object instances, with ``update()``. This reduces
+the two queries we were using above - the ``get()`` and the
+:meth:`~Model.save()` - to just one::
+
+    reporter = Reporters.objects.filter(name='Tintin')
+    reporter.update(stories_filed=F('stories_filed') + 1)
+
+We can also use :meth:`~django.db.models.query.QuerySet.update()` to increment
+the field value on multiple objects - which could be very much faster than
+pulling them all into Python from the database, looping over them, incrementing
+the field value of each one, and saving each one back to the database::
+
+    Reporter.objects.all().update(stories_filed=F('stories_filed) + 1)
+
+``F()`` therefore can offer performance advantages by:
+
+* getting the database, rather than Python, to do work
+* reducing the number of queries some operations require
+
+.. _avoiding-race-conditions-using-f:
+
+Avoiding race conditions using ``F()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Another useful benefit of ``F()`` is that having the database - rather than
+Python - update a field's value avoids a *race condition*.
+
+If two Python threads execute the code in the first example above, one thread
+could retrieve, increment, and save a field's value after the other has
+retrieved it from the database. The value that the second thread saves will be
+based on the original value; the work of the first thread will simply be lost.
+
+If the database is responsible for updating the field, the process is more
+robust: it will only ever update the field based on the value of the field in
+the database when the :meth:`~Model.save()` or ``update()`` is executed, rather
+than based on its value when the instance was retrieved.
+
+Using ``F()`` in filters
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``F()`` is also very useful in ``QuerySet`` filters, where they make it
+possible to filter a set of objects against criteria based on their field
+values, rather than on Python values.
+
+This is documented in :ref:`using F() expressions in queries
+<using-f-expressions-in-filters>`.
+
+
+.. _func-expressions:
+
+``Func()`` expressions
+----------------------
+
+.. versionadded:: 1.8
+
+``Func()`` expressions are the base type of all expressions that involve
+database functions like ``COALESCE`` and ``LOWER``, or aggregates like ``SUM``.
+They can be used directly::
+
+    queryset.annotate(field_lower=Func(F('field'), function='LOWER'))
+
+or they can be used to build a library of database functions::
+
+    class Lower(Func):
+        function = 'LOWER'
+
+    queryset.annotate(field_lower=Lower(F('field')))
+
+But both cases will result in a queryset where each model is annotated with an
+extra attribute ``field_lower`` produced, roughly, from the following SQL::
+
+    SELECT
+        ...
+        LOWER("app_label"."field") as "field_lower"
+
+The ``Func`` API is as follows:
+
+.. class:: Func(*expressions, **extra)
+
+    .. attribute:: function
+
+        A class attribute describing the function that will be generated.
+        Specifically, the ``function`` will be interpolated as the ``function``
+        placeholder within :attr:`template`. Defaults to ``None``.
+
+    .. attribute:: template
+
+        A class attribute, as a format string, that describes the SQL that is
+        generated for this function. Defaults to
+        ``'%(function)s(%(expressions)s)'``.
+
+    .. attribute:: arg_joiner
+
+        A class attribute that denotes the character used to join the list of
+        ``expressions`` together. Defaults to ``', '``.
+
+The ``*expressions`` argument is a list of positional expressions that the
+function will be applied to. The expressions will be converted to strings,
+joined together with ``arg_joiner``, and then interpolated into the ``template``
+as the ``expressions`` placeholder.
+
+The ``**extra`` kwargs are ``key=value`` pairs that can be interpolated
+into the ``template`` attribute. Note that the keywords ``function`` and
+``template`` can be used to replace the ``function`` and ``template``
+attributes respectively, without having to define your own class.
+``output_field`` can be used to define the expected return type.
+
+``Aggregate()`` expressions
+---------------------------
+
+An aggregate expression is a special case of a :ref:`Func() expression
+<func-expressions>` that informs the query that a ``GROUP BY`` clause
+is required. All of the :ref:`aggregate functions <aggregation-functions>`,
+like ``Sum()`` and ``Count()``, inherit from ``Aggregate()``.
+
+Since ``Aggregate``\s are expressions and wrap expressions, you can represent
+some complex computations::
+
+    Company.objects.annotate(
+        managers_required=(Count('num_employees') / 4) + Count('num_managers'))
+
+The ``Aggregate`` API is as follows:
+
+.. class:: Aggregate(expression, output_field=None, **extra)
+
+    .. attribute:: template
+
+        A class attribute, as a format string, that describes the SQL that is
+        generated for this aggregate. Defaults to
+        ``'%(function)s( %(expressions)s )'``.
+
+    .. attribute:: function
+
+        A class attribute describing the aggregate function that will be
+        generated. Specifically, the ``function`` will be interpolated as the
+        ``function`` placeholder within :attr:`template`. Defaults to ``None``.
+
+The ``expression`` argument can be the name of a field on the model, or another
+expression. It will be converted to a string and used as the ``expressions``
+placeholder within the ``template``.
+
+The ``output_field`` argument requires a model field instance, like
+``IntegerField()`` or ``BooleanField()``, into which Django will load the value
+after it's retrieved from the database.
+
+Note that ``output_field`` is only required when Django is unable to determine
+what field type the result should be. Complex expressions that mix field types
+should define the desired ``output_field``. For example, adding an
+``IntegerField()`` and a ``FloatField()`` together should probably have
+``output_field=FloatField()`` defined.
+
+.. versionchanged:: 1.8
+
+    ``output_field`` is a new parameter.
+
+The ``**extra`` kwargs are ``key=value`` pairs that can be interpolated
+into the ``template`` attribute.
+
+.. versionadded:: 1.8
+
+    Aggregate functions can now use arithmetic and reference multiple
+    model fields in a single function.
+
+Creating your own Aggregate Functions
+-------------------------------------
+
+Creating your own aggregate is extremely easy. At a minimum, you need
+to define ``function``, but you can also completely customize the
+SQL that is generated. Here's a brief example::
+
+    class Count(Aggregate):
+        # supports COUNT(distinct field)
+        function = 'COUNT'
+        template = '%(function)s(%(distinct)s%(expressions)s)'
+
+        def __init__(self, expression, distinct=False, **extra):
+            super(Count, self).__init__(
+                expression,
+                distinct='DISTINCT ' if distinct else '',
+                output_field=IntegerField(),
+                **extra)
+
+
+``Value()`` expressions
+-----------------------
+
+.. class:: Value(value, output_field=None)
+
+
+A ``Value()`` object represents the smallest possible component of an
+expression: a simple value. When you need to represent the value of an integer,
+boolean, or string within an expression, you can wrap that value within a
+``Value()``.
+
+You will rarely need to use ``Value()`` directly. When you write the expression
+``F('field') + 1``, Django implicitly wraps the ``1`` in a ``Value()``,
+allowing simple values to be used in more complex expressions.
+
+The ``value`` argument describes the value to be included in the expression,
+such as ``1``, ``True``, or ``None``. Django knows how to convert these Python
+values into their corresponding database type.
+
+The ``output_field`` argument should be a model field instance, like
+``IntegerField()`` or ``BooleanField()``, into which Django will load the value
+after it's retrieved from the database.
+
+
+Technical Information
+=====================
+
+Below you'll find technical implementation details that may be useful to
+library authors. The technical API and examples below will help with
+creating generic query expressions that can extend the built-in functionality
+that Django provides.
+
+Expression API
+--------------
+
+Query expressions implement the :ref:`query expression API <query-expression>`,
+but also expose a number of extra methods and attributes listed below. All
+query expressions must inherit from ``ExpressionNode()`` or a relevant
+subclass.
+
+When a query expression wraps another expression, it is responsible for
+calling the appropriate methods on the wrapped expression.
+
+.. class:: ExpressionNode
+
+    .. attribute:: contains_aggregate
+
+        Tells Django that this expression contains an aggregate and that a
+        ``GROUP BY`` clause needs to be added to the query.
+
+    .. method:: resolve_expression(query=None, allow_joins=True, reuse=None, summarize=False)
+
+        Provides the chance to do any pre-processing or validation of
+        the expression before it's added to the query. ``resolve_expression()``
+        must also be called on any nested expressions. A ``copy()`` of ``self``
+        should be returned with any necessary transformations.
+
+        ``query`` is the backend query implementation.
+
+        ``allow_joins`` is a boolean that allows or denies the use of
+        joins in the query.
+
+        ``reuse`` is a set of reusable joins for multi-join scenarios.
+
+        ``summarize`` is a boolean that, when ``True``, signals that the
+        query being computed is a terminal aggregate query.
+
+    .. method:: get_source_expressions()
+
+        Returns an ordered list of inner expressions. For example::
+
+          >>> Sum(F('foo')).get_source_expressions()
+          [F('foo')]
+
+    .. method:: set_source_expressions(expressions)
+
+        Takes a list of expressions and stores them such that
+        ``get_source_expressions()`` can return them.
+
+    .. method:: relabeled_clone(change_map)
+
+        Returns a clone (copy) of ``self``, with any column aliases relabeled.
+        Column aliases are renamed when subqueries are created.
+        ``relabeled_clone()`` should also be called on any nested expressions
+        and assigned to the clone.
+
+        ``change_map`` is a dictionary mapping old aliases to new aliases.
+
+        Example::
+
+          def relabeled_clone(self, change_map):
+              clone = copy.copy(self)
+              clone.expression = self.expression.relabeled_clone(change_map)
+              return clone
+
+    .. method:: convert_value(self, value, connection)
+
+        A hook allowing the expression to coerce ``value`` into a more
+        appropriate type.
+
+    .. method:: refs_aggregate(existing_aggregates)
+
+        Returns a tuple containing the ``(aggregate, lookup_path)`` of the
+        first aggregate that this expression (or any nested expression)
+        references, or ``(False, ())`` if no aggregate is referenced.
+        For example::
+
+            queryset.filter(num_chairs__gt=F('sum__employees'))
+
+        The ``F()`` expression here references a previous ``Sum()``
+        computation which means that this filter expression should be
+        added to the ``HAVING`` clause rather than the ``WHERE`` clause.
+
+        In the majority of cases, returning the result of ``refs_aggregate``
+        on any nested expression should be appropriate, as the necessary
+        built-in expressions will return the correct values.
+
+    .. method:: get_group_by_cols()
+
+        Responsible for returning the list of columns references by
+        this expression. ``get_group_by_cols()`` should be called on any
+        nested expressions. ``F()`` objects, in particular, hold a reference
+        to a column.
+
+Writing your own Query Expressions
+----------------------------------
+
+You can write your own query expression classes that use, and can integrate
+with, other query expressions. Let's step through an example by writing an
+implementation of the ``COALESCE`` SQL function, without using the built-in
+:ref:`Func() expressions <func-expressions>`.
+
+The ``COALESCE`` SQL function is defined as taking a list of columns or
+values. 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
+an ``__init__()`` method to set some attributes::
+
+  import copy
+  from django.db.models import ExpressionNode
+
+  class Coalesce(ExpressionNode):
+      template = 'COALESCE( %(expressions)s )'
+
+      def __init__(self, expressions, output_field, **extra):
+        super(Coalesce, self).__init__(output_field=output_field)
+        if len(expressions) < 2:
+            raise ValueError('expressions must have at least 2 elements')
+        for expression in expressions:
+            if not hasattr(expression, 'resolve_expression'):
+                raise TypeError('%r is not an Expression' % expression)
+        self.expressions = expressions
+        self.extra = extra
+
+We do some basic validation on the parameters, including requiring at least
+2 columns or values, and ensuring they are expressions. We are requiring
+``output_field`` here so that Django knows what kind of model field to assign
+the eventual result to.
+
+Now we implement the pre-processing and validation. Since we do not have
+any of our own validation at this point, we just delegate to the nested
+expressions::
+
+    def resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False):
+        c = self.copy()
+        c.is_summary = summarize
+        for pos, expression in enumerate(self.expressions):
+            c.expressions[pos] = expression.resolve_expression(query, allow_joins, reuse, summarize)
+        return c
+
+Next, we write the method responsible for generating the SQL::
+
+    def as_sql(self, compiler, connection):
+        sql_expressions, sql_params = [], []
+        for expression in self.expressions:
+            sql, params = compiler.compile(expression)
+            sql_expressions.append(sql)
+            sql_params.extend(params)
+        self.extra['expressions'] = ','.join(sql_expressions)
+        return self.template % self.extra, sql_params
+
+    def as_oracle(self, compiler, connection):
+        """
+        Example of vendor specific handling (Oracle in this case).
+        Let's make the function name lowercase.
+        """
+        self.template = 'coalesce( %(expressions)s )'
+        return self.as_sql(compiler, connection)
+
+We generate the SQL for each of the ``expressions`` by using the
+``compiler.compile()`` method, and join the result together with commas.
+Then the template is filled out with our data and the SQL and parameters
+are returned.
+
+We've also defined a custom implementation that is specific to the Oracle
+backend. The ``as_oracle()`` function will be called instead of ``as_sql()``
+if the Oracle backend is in use.
+
+Finally, we implement the rest of the methods that allow our query expression
+to play nice with other query expressions::
+
+    def get_source_expressions(self):
+        return self.expressions
+
+    def set_source_expressions(expressions):
+        self.expressions = expressions
+
+Let's see how it works::
+
+    >>> qs = Company.objects.annotate(
+    ...    tagline=Coalesce([
+    ...        F('motto'),
+    ...        F('ticker_name'),
+    ...        F('description'),
+    ...        Value('No Tagline')
+    ...        ], output_field=CharField()))
+    >>> for c in qs:
+    ...     print("%s: %s" % (c.name, c.tagline))
+    ...
+    Google: Do No Evil
+    Apple: AAPL
+    Yahoo: Internet Company
+    Django Software Foundation: No Tagline
diff --git a/docs/ref/models/index.txt b/docs/ref/models/index.txt
index 57385b200d..b7f5ab6635 100644
--- a/docs/ref/models/index.txt
+++ b/docs/ref/models/index.txt
@@ -15,3 +15,4 @@ Model API reference. For introductory material, see :doc:`/topics/db/models`.
    querysets
    queries
    lookups
+   expressions
diff --git a/docs/ref/models/queries.txt b/docs/ref/models/queries.txt
index 1eab21c528..283983aef3 100644
--- a/docs/ref/models/queries.txt
+++ b/docs/ref/models/queries.txt
@@ -7,115 +7,6 @@ Query-related classes
 This document provides reference material for query-related tools not
 documented elsewhere.
 
-``F()`` expressions
-===================
-
-.. class:: F
-
-An ``F()`` object represents the value of a model field. It makes it possible
-to refer to model field values and perform database operations using them
-without actually having to pull them out of the database into Python memory.
-
-Instead, Django uses the ``F()`` object to generate a SQL expression that
-describes the required operation at the database level.
-
-This is easiest to understand through an example. Normally, one might do
-something like this::
-
-    # Tintin filed a news story!
-    reporter = Reporters.objects.get(name='Tintin')
-    reporter.stories_filed += 1
-    reporter.save()
-
-Here, we have pulled the value of ``reporter.stories_filed`` from the database
-into memory and manipulated it using familiar Python operators, and then saved
-the object back to the database. But instead we could also have done::
-
-    from django.db.models import F
-    reporter = Reporters.objects.get(name='Tintin')
-    reporter.stories_filed = F('stories_filed') + 1
-    reporter.save()
-
-Although ``reporter.stories_filed = F('stories_filed') + 1`` looks like a
-normal Python assignment of value to an instance attribute, in fact it's an SQL
-construct describing an operation on the database.
-
-When Django encounters an instance of ``F()``, it overrides the standard Python
-operators to create an encapsulated SQL expression; in this case, one which
-instructs the database to increment the database field represented by
-``reporter.stories_filed``.
-
-Whatever value is or was on ``reporter.stories_filed``, Python never gets to
-know about it - it is dealt with entirely by the database. All Python does,
-through Django's ``F()`` class, is create the SQL syntax to refer to the field
-and describe the operation.
-
-.. note::
-
-   In order to access the new value that has been saved in this way, the object
-   will need to be reloaded::
-
-       reporter = Reporters.objects.get(pk=reporter.pk)
-
-As well as being used in operations on single instances as above, ``F()`` can
-be used on ``QuerySets`` of object instances, with ``update()``. This reduces
-the two queries we were using above - the ``get()`` and the
-:meth:`~Model.save()` - to just one::
-
-    reporter = Reporters.objects.filter(name='Tintin')
-    reporter.update(stories_filed=F('stories_filed') + 1)
-
-We can also use :meth:`~django.db.models.query.QuerySet.update()` to increment
-the field value on multiple objects - which could be very much faster than
-pulling them all into Python from the database, looping over them, incrementing
-the field value of each one, and saving each one back to the database::
-
-    Reporter.objects.all().update(stories_filed=F('stories_filed') + 1)
-
-``F()`` therefore can offer performance advantages by:
-
-* getting the database, rather than Python, to do work
-* reducing the number of queries some operations require
-
-.. _avoiding-race-conditions-using-f:
-
-Avoiding race conditions using ``F()``
---------------------------------------
-
-Another useful benefit of ``F()`` is that having the database - rather than
-Python - update a field's value avoids a *race condition*.
-
-If two Python threads execute the code in the first example above, one thread
-could retrieve, increment, and save a field's value after the other has
-retrieved it from the database. The value that the second thread saves will be
-based on the original value; the work of the first thread will simply be lost.
-
-If the database is responsible for updating the field, the process is more
-robust: it will only ever update the field based on the value of the field in
-the database when the :meth:`~Model.save()` or ``update()`` is executed, rather
-than based on its value when the instance was retrieved.
-
-Using ``F()`` in filters
-------------------------
-
-``F()`` is also very useful in ``QuerySet`` filters, where they make it
-possible to filter a set of objects against criteria based on their field
-values, rather than on Python values.
-
-This is documented in :ref:`using F() expressions in queries
-<using-f-expressions-in-filters>`
-
-Supported operations with ``F()``
----------------------------------
-
-As well as addition, Django supports subtraction, multiplication, division,
-and modulo arithmetic with ``F()`` objects, using Python constants,
-variables, and even other ``F()`` objects.
-
-.. versionadded:: 1.7
-
-    The power operator ``**`` is also supported.
-
 ``Q()`` objects
 ===============
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 218a4ff35f..1cf215bc46 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -220,9 +220,18 @@ annotate
 
 .. method:: annotate(*args, **kwargs)
 
-Annotates each object in the ``QuerySet`` with the provided list of
-aggregate values (averages, sums, etc) that have been computed over
-the objects that are related to the objects in the ``QuerySet``.
+Annotates each object in the ``QuerySet`` with the provided list of :doc:`query
+expressions </ref/models/expressions>`. An expression may be a simple value, a
+reference to a field on the model (or any related models), or an aggregate
+expression (averages, sums, etc) that has been computed over the objects that
+are related to the objects in the ``QuerySet``.
+
+.. versionadded:: 1.8
+
+    Previous versions of Django only allowed aggregate functions to be used as
+    annotations. It is now possible to annotate a model with all kinds of
+    expressions.
+
 Each argument to ``annotate()`` is an annotation that will be added
 to each object in the ``QuerySet`` that is returned.
 
@@ -232,7 +241,9 @@ in `Aggregation Functions`_ below.
 Annotations specified using keyword arguments will use the keyword as
 the alias for the annotation. Anonymous arguments will have an alias
 generated for them based upon the name of the aggregate function and
-the model field that is being aggregated.
+the model field that is being aggregated. Only aggregate expressions
+that reference a single field can be anonymous arguments. Everything
+else must be a keyword argument.
 
 For example, if you were manipulating a list of blogs, you may want
 to determine how many entries have been made in each blog::
@@ -1886,12 +1897,15 @@ the ``QuerySet``. Each argument to ``aggregate()`` specifies a value that will
 be included in the dictionary that is returned.
 
 The aggregation functions that are provided by Django are described in
-`Aggregation Functions`_ below.
+`Aggregation Functions`_ below. Since aggregates are also :doc:`query
+expressions </ref/models/expressions>`, you may combine aggregates with other
+aggregates or values to create complex aggregates.
 
 Aggregates specified using keyword arguments will use the keyword as the name
 for the annotation. Anonymous arguments will have a name generated for them
 based upon the name of the aggregate function and the model field that is being
-aggregated.
+aggregated. Complex aggregates cannot use anonymous arguments and must specify
+a keyword argument as an alias.
 
 For example, when you are working with blog entries, you may want to know the
 number of authors that have contributed blog entries::
@@ -2667,8 +2681,9 @@ Aggregation functions
 
 Django provides the following aggregation functions in the
 ``django.db.models`` module. For details on how to use these
-aggregate functions, see
-:doc:`the topic guide on aggregation </topics/db/aggregation>`.
+aggregate functions, see :doc:`the topic guide on aggregation
+</topics/db/aggregation>`. See the :class:`~django.db.models.Aggregate`
+documentation to learn how to create your aggregates.
 
 .. warning::
 
@@ -2685,12 +2700,47 @@ aggregate functions, see
     instead of ``0`` if the ``QuerySet`` contains no entries. An exception is
     ``Count``, which does return ``0`` if the ``QuerySet`` is empty.
 
+All aggregates have the following parameters in common:
+
+``expression``
+~~~~~~~~~~~~~~
+
+A string that references a field on the model, or a :doc:`query expression
+</ref/models/expressions>`.
+
+.. versionadded:: 1.8
+
+    Aggregate functions are now able to reference multiple fields in complex
+    computations.
+
+``output_field``
+~~~~~~~~~~~~~~~~
+
+An optional argument that represents the :doc:`model field </ref/models/fields>`
+of the return value
+
+.. versionadded:: 1.8
+
+    The ``output_field`` argument was added.
+
+.. note::
+
+    When combining multiple field types, Django can only determine the
+    ``output_field`` if all fields are of the same type. Otherwise, you
+    must provide the ``output_field`` yourself.
+
+``**extra``
+~~~~~~~~~~~
+
+Keyword arguments that can provide extra context for the SQL generated
+by the aggregate.
+
 Avg
 ~~~
 
-.. class:: Avg(field)
+.. class:: Avg(expression, output_field=None, **extra)
 
-    Returns the mean value of the given field, which must be numeric.
+    Returns the mean value of the given expression, which must be numeric.
 
     * Default alias: ``<field>__avg``
     * Return type: ``float``
@@ -2698,9 +2748,10 @@ Avg
 Count
 ~~~~~
 
-.. class:: Count(field, distinct=False)
+.. class:: Count(expression, distinct=False, **extra)
 
-    Returns the number of objects that are related through the provided field.
+    Returns the number of objects that are related through the provided
+    expression.
 
     * Default alias: ``<field>__count``
     * Return type: ``int``
@@ -2716,29 +2767,29 @@ Count
 Max
 ~~~
 
-.. class:: Max(field)
+.. class:: Max(expression, output_field=None, **extra)
 
-    Returns the maximum value of the given field.
+    Returns the maximum value of the given expression.
 
     * Default alias: ``<field>__max``
-    * Return type: same as input field
+    * Return type: same as input field, or ``output_field`` if supplied
 
 Min
 ~~~
 
-.. class:: Min(field)
+.. class:: Min(expression, output_field=None, **extra)
 
-    Returns the minimum value of the given field.
+    Returns the minimum value of the given expression.
 
     * Default alias: ``<field>__min``
-    * Return type: same as input field
+    * Return type: same as input field, or ``output_field`` if supplied
 
 StdDev
 ~~~~~~
 
-.. class:: StdDev(field, sample=False)
+.. class:: StdDev(expression, sample=False, **extra)
 
-    Returns the standard deviation of the data in the provided field.
+    Returns the standard deviation of the data in the provided expression.
 
     * Default alias: ``<field>__stddev``
     * Return type: ``float``
@@ -2760,19 +2811,19 @@ StdDev
 Sum
 ~~~
 
-.. class:: Sum(field)
+.. class:: Sum(expression, output_field=None, **extra)
 
-    Computes the sum of all values of the given field.
+    Computes the sum of all values of the given expression.
 
     * Default alias: ``<field>__sum``
-    * Return type: same as input field
+    * Return type: same as input field, or ``output_field`` if supplied
 
 Variance
 ~~~~~~~~
 
-.. class:: Variance(field, sample=False)
+.. class:: Variance(expression, sample=False, **extra)
 
-    Returns the variance of the data in the provided field.
+    Returns the variance of the data in the provided expression.
 
     * Default alias: ``<field>__variance``
     * Return type: ``float``