diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index c0ea1133bc..a4035b2d87 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -312,10 +312,14 @@ identical to:: Entry.objects.order_by('blog__name') You can also order by :doc:`query expressions ` by -calling ``asc()`` or ``desc()`` on the expression:: +calling :meth:`~.Expression.asc` or :meth:`~.Expression.desc` on the +expression:: Entry.objects.order_by(Coalesce('summary', 'headline').desc()) +:meth:`~.Expression.asc` and :meth:`~.Expression.desc` have arguments +(``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 :meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how related model ordering can change the expected results.