From f3e1e6d601c4107dbfb00c15ecf0ce51e2b6cf10 Mon Sep 17 00:00:00 2001 From: drd0013 Date: Thu, 19 Apr 2018 17:07:40 -0700 Subject: [PATCH] [2.0.x] Fixed #29313 -- Doc'd how to use F() to sort null values. Backport of 5d923f2d8cadb06497d255097caa4583d66b697a from master --- docs/ref/models/expressions.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 5e230bb918..26ce4bd07a 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -220,6 +220,21 @@ primary key value rather than a model instance:: >> car.built_by 3 +.. _using-f-to-sort-null-values: + +Using ``F()`` to sort null values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use ``F()`` and the ``nulls_first`` or ``nulls_last`` keyword argument to +:meth:`.Expression.asc` or :meth:`~.Expression.desc` to control the ordering of +a field's null values. By default, the ordering depends on your database. + +For example, to sort companies that haven't been contacted (``last_contacted`` +is null) after companies that have been contacted:: + + from django.db.models import F + Company.object.order_by(F('last_contacted').desc(nulls_last=True)) + .. _func-expressions: ``Func()`` expressions @@ -969,6 +984,7 @@ calling the appropriate methods on the wrapped expression. Returns the expression ready to be sorted in ascending order. ``nulls_first`` and ``nulls_last`` define how null values are sorted. + See :ref:`using-f-to-sort-null-values` for example usage. .. versionchanged:: 1.11 @@ -979,6 +995,7 @@ calling the appropriate methods on the wrapped expression. Returns the expression ready to be sorted in descending order. ``nulls_first`` and ``nulls_last`` define how null values are sorted. + See :ref:`using-f-to-sort-null-values` for example usage. .. versionchanged:: 1.11