diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/models/expressions.txt | 24 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 35 |
2 files changed, 51 insertions, 8 deletions
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 126455aba4..b36afe5633 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -5,7 +5,7 @@ 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 +a filter, order by, annotation, or aggregate. 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. @@ -58,6 +58,10 @@ Some examples # Aggregates can contain complex computations also Company.objects.annotate(num_offerings=Count(F('products') + F('services'))) + # Expressions can also be used in order_by() + Company.objects.order_by(Length('name').asc()) + Company.objects.order_by(Length('name').desc()) + Built-in Expressions ==================== @@ -428,6 +432,24 @@ calling the appropriate methods on the wrapped expression. nested expressions. ``F()`` objects, in particular, hold a reference to a column. + .. method:: asc() + + Returns the expression ready to be sorted in ascending order. + + .. method:: desc() + + Returns the expression ready to be sorted in descending order. + + .. method:: reverse_ordering() + + Returns ``self`` with any modifications required to reverse the sort + order within an ``order_by`` call. As an example, an expression + implementing ``NULLS LAST`` would change its value to be + ``NULLS FIRST``. Modifications are only required for expressions that + implement sort order like ``OrderBy``. This method is called when + :meth:`~django.db.models.query.QuerySet.reverse()` is called on a + queryset. + Writing your own Query Expressions ---------------------------------- diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 397eea0782..e7d293fc89 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -322,17 +322,28 @@ identical to:: Entry.objects.order_by('blog__name') +It is also possible to order a queryset by a related field, without incurring +the cost of a JOIN, by referring to the ``_id`` of the related field:: + + # No Join + Entry.objects.order_by('blog_id') + + # Join + Entry.objects.order_by('blog__id') + .. versionadded:: 1.7 - Note that it is also possible to order a queryset by a related field, - without incurring the cost of a JOIN, by referring to the ``_id`` of the - related field:: + The ability to order a queryset by a related field, without incurring + the cost of a JOIN was added. + +You can also order by :doc:`query expressions </ref/models/expressions>` by +calling ``asc()`` or ``desc()`` on the expression:: + + Entry.objects.order_by(Coalesce('summary', 'headline').desc()) - # No Join - Entry.objects.order_by('blog_id') +.. versionadded:: 1.8 - # Join - Entry.objects.order_by('blog__id') + Ordering by query expressions was added. Be cautious when ordering by fields in related models if you are also using :meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how @@ -367,6 +378,16 @@ There's no way to specify whether ordering should be case sensitive. With respect to case-sensitivity, Django will order results however your database backend normally orders them. +You can order by a field converted to lowercase with +:class:`~django.db.models.functions.Lower` which will achieve case-consistent +ordering:: + + Entry.objects.order_by(Lower('headline').desc()) + +.. versionadded:: 1.8 + + The ability to order by expressions like ``Lower`` was added. + If you don't want any ordering to be applied to a query, not even the default ordering, call :meth:`order_by()` with no parameters. |