order_by(*fields)
By default, results returned by a QuerySet
are ordered by the ordering tuple given by the ordering
option in the model’s Meta
. You can override this on a per-QuerySet
basis by using the order_by
method.
Example:
Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')
The result above will be ordered by pub_date
descending, then by headline
ascending. The negative sign in front of "-pub_date"
indicates descending order. Ascending order is implied. To order randomly, use "?"
, like so:
Entry.objects.order_by('?')
Note: order_by('?')
queries may be expensive and slow, depending on the database backend you’re using.
To order by a field in a different model, use the same syntax as when you are querying across model relations. That is, the name of the field, followed by a double underscore (__
), followed by the name of the field in the new model, and so on for as many models as you want to join. For example:
Entry.objects.order_by('blog__name', 'headline')
If you try to order by a field that is a relation to another model, Django will use the default ordering on the related model, or order by the related model’s primary key if there is no Meta.ordering
specified. For example, since the Blog
model has no default ordering specified:
Entry.objects.order_by('blog')
...is identical to:
Entry.objects.order_by('blog__id')
If Blog
had ordering = ['name']
, then the first queryset would be 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')
You can also order by query expressions by calling asc()
or desc()
on the expression:
Entry.objects.order_by(Coalesce('summary', 'headline').desc())
Be cautious when ordering by fields in related models if you are also using distinct()
. See the note in distinct()
for an explanation of how related model ordering can change the expected results.
Note
It is permissible to specify a multi-valued field to order the results by (for example, a ManyToManyField
field, or the reverse relation of a ForeignKey
field).
Consider this case:
class Event(Model): parent = models.ForeignKey( 'self', on_delete=models.CASCADE, related_name='children', ) date = models.DateField() Event.objects.order_by('children__date')
Here, there could potentially be multiple ordering data for each Event
; each Event
with multiple children
will be returned multiple times into the new QuerySet
that order_by()
creates. In other words, using order_by()
on the QuerySet
could return more items than you were working on to begin with - which is probably neither expected nor useful.
Thus, take care when using multi-valued field to order the results. If you can be sure that there will only be one ordering piece of data for each of the items you’re ordering, this approach should not present problems. If not, make sure the results are what you expect.
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 Lower
which will achieve case-consistent ordering:
Entry.objects.order_by(Lower('headline').desc())
If you don’t want any ordering to be applied to a query, not even the default ordering, call order_by()
with no parameters.
You can tell if a query is ordered or not by checking the QuerySet.ordered
attribute, which will be True
if the QuerySet
has been ordered in any way.
Each order_by()
call will clear any previous ordering. For example, this query will be ordered by pub_date
and not headline
:
Entry.objects.order_by('headline').order_by('pub_date')
Warning
Ordering is not a free operation. Each field you add to the ordering incurs a cost to your database. Each foreign key you add will implicitly include all of its default orderings as well.
If a query doesn’t have an ordering specified, results are returned from the database in an unspecified order. A particular ordering is guaranteed only when ordering by a set of fields that uniquely identify each object in the results. For example, if a name
field isn’t unique, ordering by it won’t guarantee objects with the same name always appear in the same order.
Please login to continue.