Fixed #24767 -- Added Greatest and Least expressions

Greatest and Least are row-level Function versions of Min and Max.

2 files changed, 71 insertions, 0 deletions

diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index b797e5f1df..8d44d5eaa6 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -82,6 +82,74 @@ Usage example::
     >>> print(author.screen_name)
     Margaret Smith (Maggie)
 
+Greatest
+--------
+
+.. versionadded:: 1.9
+
+.. class:: Greatest(*expressions, **extra)
+
+Accepts a list of at least two field names or expressions and returns the
+greatest value. Each argument must be of a similar type, so mixing text and numbers
+will result in a database error.
+
+Usage example::
+
+    class Blog(models.Model):
+        body = models.TextField()
+        modified = models.DateTimeField(auto_now=True)
+
+    class Comment(models.Model):
+        body = models.TextField()
+        modified = models.DateTimeField(auto_now=True)
+        blog = models.ForeignKey(Blog)
+
+    >>> from django.db.models.functions import Greatest
+    >>> blog = Blog.objects.create(body='Greatest is the best.')
+    >>> comment = Comment.objects.create(body='No, Least is better.', blog=blog)
+    >>> comments = Comment.objects.annotate(last_updated=Greatest('modified', 'blog__modified'))
+    >>> annotated_comment = comments.get()
+
+``annotated_comment.last_updated`` will be the most recent of 
+``blog.modified`` and ``comment.modified``.
+
+.. warning::
+
+    The behavior of ``Greatest`` when one or more expression may be ``null``
+    varies between databases:
+
+    - PostgreSQL: ``Greatest`` will return the largest non-null expression,
+      or ``null`` if all expressions are ``null``.
+    - SQLite, Oracle and MySQL: If any expression is ``null``, ``Greatest``
+      will return ``null``.
+
+    The PostgreSQL behavior can be emulated using ``Coalesce`` if you know
+    a sensible minimum value to provide as a default.
+
+Least
+--------
+
+.. versionadded:: 1.9
+
+.. class:: Least(*expressions, **extra)
+
+Accepts a list of at least two field names or expressions and returns the
+least value. Each argument must be of a similar type, so mixing text and numbers
+will result in a database error.
+
+.. warning::
+
+    The behavior of ``Least`` when one or more expression may be ``null``
+    varies between databases:
+
+    - PostgreSQL: ``Least`` will return the smallest non-null expression,
+      or ``null`` if all expressions are ``null``.
+    - SQLite, Oracle and MySQL: If any expression is ``null``, ``Least``
+      will return ``null``.
+
+    The PostgreSQL behavior can be emulated using ``Coalesce`` if you know
+    a sensible maximum value to provide as a default.
+
 Length
 ------
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index f43fe07f08..b101738d78 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -256,6 +256,9 @@ Models
 * Added the :lookup:`date` lookup to :class:`~django.db.models.DateTimeField`
   to allow querying the field by only the date portion.
 
+* Added the :class:`~django.db.models.functions.Greatest` and
+  :class:`~django.db.models.functions.Least` database functions.
+
 * Added the :class:`~django.db.models.functions.Now` database function, which
   returns the current date and time.