diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/models/querysets.txt | 34 |
1 files changed, 31 insertions, 3 deletions
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 8d2e3ebb3b..f11a09fb96 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -506,7 +506,7 @@ Examples (those after the first will only work on PostgreSQL):: ``values()`` ~~~~~~~~~~~~ -.. method:: values(*fields) +.. method:: values(*fields, **expressions) Returns a ``QuerySet`` that returns dictionaries, rather than model instances, when used as an iterable. @@ -538,6 +538,23 @@ Example:: >>> Blog.objects.values('id', 'name') <QuerySet [{'id': 1, 'name': 'Beatles Blog'}]> +The ``values()`` method also takes optional keyword arguments, +``**expressions``, which are passed through to :meth:`annotate`:: + + >>> from django.db.models.functions import Lower + >>> Blog.objects.values(lower_name=Lower('name')) + <QuerySet [{'lower_name': 'beatles blog'}]> + +An aggregate within a ``values()`` clause is applied before other arguments +within the same ``values()`` clause. If you need to group by another value, +add it to an earlier ``values()`` clause instead. For example:: + + >>> from django.db.models import Count + >>> Blog.objects.values('author', entries=Count('entry')) + <QuerySet [{'author': 1, 'entries': 20}, {'author': 1, 'entries': 13}]> + >>> Blog.objects.values('author').annotate(entries=Count('entry')) + <QuerySet [{'author': 1, 'entries': 33}]> + A few subtleties that are worth mentioning: * If you have a field called ``foo`` that is a @@ -603,6 +620,10 @@ You can also refer to fields on related models with reverse relations through pronounced if you include multiple such fields in your ``values()`` query, in which case all possible combinations will be returned. +.. versionchanged:: 1.11 + + Support for ``**expressions`` was added. + ``values_list()`` ~~~~~~~~~~~~~~~~~ @@ -610,11 +631,14 @@ You can also refer to fields on related models with reverse relations through This is similar to ``values()`` except that instead of returning dictionaries, it returns tuples when iterated over. Each tuple contains the value from the -respective field passed into the ``values_list()`` call — so the first item is -the first field, etc. For example:: +respective field or expression passed into the ``values_list()`` call — so the +first item is the first field, etc. For example:: >>> Entry.objects.values_list('id', 'headline') [(1, 'First entry'), ...] + >>> from django.db.models.functions import Lower + >>> Entry.objects.values_list('id', Lower('headline')) + [(1, 'first entry'), ...] If you only pass in a single field, you can also pass in the ``flat`` parameter. If ``True``, this will mean the returned results are single values, @@ -661,6 +685,10 @@ not having any author:: >>> Entry.objects.values_list('authors') [('Noam Chomsky',), ('George Orwell',), (None,)] +.. versionchanged:: 1.11 + + Support for expressions in ``*fields`` was added. + ``dates()`` ~~~~~~~~~~~ |