Changeset 6513

Timestamp:

10/14/07 19:30:05 (11 months ago)

Author:

mtredinnick

Message:

queryset-refactor: Updated documentation to describe the new order_by() and
extra(order_by=...) behaviour.

Files:

• django/branches/queryset-refactor/docs/db-api.txt (modified) (3 diffs)

django/branches/queryset-refactor/docs/db-api.txt

@@ -515 +515 @@
-database backend you're using.
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-There's no way to specify whether ordering should be case sensitive. With
@@ -706 +720 @@
-The ``depth`` argument is new in the Django development version.
-
-
-
+, order_by=None
+~~~~~~~~~~~~~~~
-
-Sometimes, the Django query syntax by itself can't easily express a complex
@@ -779 +793 @@
-
-        SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20);
+
+``order_by``
+    If you need to order the resulting queryset using some of the new fields
+    or tables you have included via ``extra()`` use the ``order_by`` parameter
+    to ``extra()`` and pass in a sequence of strings. These strings should
+    either be model fields (as in the normal ``order_by()`` method on
+    querysets), of the form ``table_name.column_name`` or an alias for a column
+    that you specified in the ``select`` parameter to ``extra()``.
+
+    For example::
+
+        q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
+        q = q.extra(order_by = ['-is_recent'])
+
+    This would sort all the items for which ``is_recent`` is true to the front
+    of the result set (``True`` sorts before ``False`` in a descending
+    ordering).
+
+    This shows, by the way, that you can make multiple calls to
+    ``extra()`` and it will behave as you expect (adding new constraints each
+    time).
-
-``params``