Changeset 8694

Timestamp:

08/29/08 00:04:26 (3 months ago)

Author:

mtredinnick

Message:

Revived a bunch of missing documentation that got lost in the docs-refactor.
This describes values_list(), the new cross-model order_by() syntax and the
effects of distinct(), values() and order_by() on each other.

Fixed #8634.

Files:

• django/trunk/docs/ref/models/querysets.txt (modified) (4 diffs)

django/trunk/docs/ref/models/querysets.txt

@@ -146 +146 @@
-database backend you're using.
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-There's no way to specify whether ordering should be case sensitive. With
@@ -172 +207 @@
-By default, a ``QuerySet`` will not eliminate duplicate rows. In practice, this
-is rarely a problem, because simple queries such as ``Blog.objects.all()``
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-``values(*fields)``
@@ -210 +264 @@
-    [{'id': 1, 'name': 'Beatles Blog'}]
-
+A couple of subtleties that are worth mentioning:
+
+    * The ``values()`` method does not return anything for
+      :class:`~django.db.models.ManyToManyField` attributes and will raise an
+      error if you try to pass in this type of field to it.
+    * If you have a field called ``foo`` that is a
+      :class:`~django.db.models.ForeignKey`, the default ``values()`` call
+      will return a dictionary key called ``foo_id``, since this is the name
+      of the hidden model attribute that stores the actual value (the ``foo``
+      attribute refers to the related model). When you are calling
+      ``values()`` and passing in field names, you can pass in either ``foo``
+      or ``foo_id`` and you will get back the same thing (the dictionary key
+      will match the field name you passed in).
+
+      For example::
+
+        >>> Entry.objects.values()
+        [{'blog_id: 1, 'headline': u'First Entry', ...}, ...]
+
+        >>> Entry.objects.values('blog')
+        [{'blog': 1}, ...]
+
+        >>> Entry.objects.values('blog_id')
+        [{'blog_id': 1}, ...]
+    * When using ``values()`` together with ``distinct()``, be aware that
+      ordering can affect the results. See the note in the `distinct()`_
+      section, above, for details.
+
+**New in Django development version:** Previously, it was not possible to pass
+``blog_id`` to ``values()`` in the above example, only ``blog``.
+
-A ``ValuesQuerySet`` is useful when you know you're only going to need values
-from a small number of the available fields and you won't need the
@@ -226 +311 @@
-but it doesn't really matter. This is your chance to really flaunt your
-individualism.
+
+``values_list(*fields)``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+This is similar to ``values()`` except that instead of returning a list of
+dictionaries, it returns a list of tuples. 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::
+
+    >>> Entry.objects.values_list('id', 'headline')
+    [(1, u'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,
+rather than one-tuples. An example should make the difference clearer::
+
+    >>> Entry.objects.values_list('id').order_by('id')
+    [(1,), (2,), (3,), ...]
+
+    >>> Entry.objects.values_list('id', flat=True).order_by('id')
+    [1, 2, 3, ...]
+
+It is an error to pass in ``flat`` when there is more than one field.
+
+If you don't pass any values to ``values_list()``, it will return all the
+fields in the model, in the order they were declared.
-
-``dates(field, kind, order='ASC')``