diff --git a/django/db/backends/base/features.py b/django/db/backends/base/features.py index e0a7e49512..b7861865ac 100644 --- a/django/db/backends/base/features.py +++ b/django/db/backends/base/features.py @@ -208,6 +208,10 @@ class BaseDatabaseFeatures(object): # Does the backend support "select for update" queries with limit (and offset)? supports_select_for_update_with_limit = True + # Does the backend ignore null expressions in GREATEST and LEAST queries unless + # every expression is null? + greatest_least_ignores_nulls = False + def __init__(self, connection): self.connection = connection diff --git a/django/db/backends/postgresql_psycopg2/features.py b/django/db/backends/postgresql_psycopg2/features.py index 3c5aebfef8..a07700e601 100644 --- a/django/db/backends/postgresql_psycopg2/features.py +++ b/django/db/backends/postgresql_psycopg2/features.py @@ -27,3 +27,4 @@ class DatabaseFeatures(BaseDatabaseFeatures): closed_cursor_error_class = InterfaceError has_case_insensitive_like = False requires_sqlparse_for_splitting = False + greatest_least_ignores_nulls = True diff --git a/django/db/models/functions.py b/django/db/models/functions.py index a39864e4b5..978d2c16bf 100644 --- a/django/db/models/functions.py +++ b/django/db/models/functions.py @@ -83,6 +83,48 @@ class Concat(Func): return ConcatPair(expressions[0], self._paired(expressions[1:])) +class Greatest(Func): + """ + Chooses the maximum expression and returns it. + + If any expression is null the return value is database-specific: + On Postgres, the maximum not-null expression is returned. + On MySQL, Oracle and SQLite, if any expression is null, null is + returned. + """ + function = 'GREATEST' + + def __init__(self, *expressions, **extra): + if len(expressions) < 2: + raise ValueError('Greatest must take at least two expressions') + super(Greatest, self).__init__(*expressions, **extra) + + def as_sqlite(self, compiler, connection): + """Use the MAX function on SQLite.""" + return super(Greatest, self).as_sql(compiler, connection, function='MAX') + + +class Least(Func): + """ + Chooses the minimum expression and returns it. + + If any expression is null the return value is database-specific: + On Postgres, the minimum not-null expression is returned. + On MySQL, Oracle and SQLite, if any expression is null, null is + returned. + """ + function = 'LEAST' + + def __init__(self, *expressions, **extra): + if len(expressions) < 2: + raise ValueError('Least must take at least two expressions') + super(Least, self).__init__(*expressions, **extra) + + def as_sqlite(self, compiler, connection): + """Use the MIN function on SQLite.""" + return super(Least, self).as_sql(compiler, connection, function='MIN') + + class Length(Func): """Returns the number of characters in the expression""" function = 'LENGTH' 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. diff --git a/tests/db_functions/models.py b/tests/db_functions/models.py index 19722aeed2..f100b79ff5 100644 --- a/tests/db_functions/models.py +++ b/tests/db_functions/models.py @@ -12,6 +12,7 @@ class Author(models.Model): name = models.CharField(max_length=50) alias = models.CharField(max_length=50, null=True, blank=True) goes_by = models.CharField(max_length=50, null=True, blank=True) + age = models.PositiveSmallIntegerField(default=30) def __str__(self): return self.name @@ -25,7 +26,18 @@ class Article(models.Model): text = models.TextField() written = models.DateTimeField() published = models.DateTimeField(null=True, blank=True) + updated = models.DateTimeField(null=True, blank=True) views = models.PositiveIntegerField(default=0) def __str__(self): return self.title + + +@python_2_unicode_compatible +class Fan(models.Model): + name = models.CharField(max_length=50) + age = models.PositiveSmallIntegerField(default=30) + author = models.ForeignKey(Author, related_name='fans') + + def __str__(self): + return self.name diff --git a/tests/db_functions/tests.py b/tests/db_functions/tests.py index 1df9800f13..8d465b1bd3 100644 --- a/tests/db_functions/tests.py +++ b/tests/db_functions/tests.py @@ -1,15 +1,18 @@ from __future__ import unicode_literals from datetime import datetime, timedelta +from unittest import skipIf, skipUnless +from django.db import connection from django.db.models import CharField, TextField, Value as V +from django.db.models.expressions import RawSQL from django.db.models.functions import ( - Coalesce, Concat, Length, Lower, Now, Substr, Upper, + Coalesce, Concat, Greatest, Least, Length, Lower, Now, Substr, Upper, ) -from django.test import TestCase +from django.test import TestCase, skipIfDBFeature, skipUnlessDBFeature from django.utils import six, timezone -from .models import Article, Author +from .models import Article, Author, Fan lorem_ipsum = """ @@ -101,6 +104,196 @@ class FunctionTests(TestCase): lambda a: a.name ) + def test_greatest(self): + now = timezone.now() + before = now - timedelta(hours=1) + + Article.objects.create( + title="Testing with Django", + written=before, + published=now, + ) + + articles = Article.objects.annotate( + last_updated=Greatest('written', 'published'), + ) + self.assertEqual(articles.first().last_updated, now) + + @skipUnlessDBFeature('greatest_least_ignores_nulls') + def test_greatest_ignores_null(self): + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + last_updated=Greatest('written', 'published'), + ) + self.assertEqual(articles.first().last_updated, now) + + @skipIfDBFeature('greatest_least_ignores_nulls') + def test_greatest_propogates_null(self): + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + last_updated=Greatest('written', 'published'), + ) + self.assertIsNone(articles.first().last_updated) + + @skipIf(connection.vendor == 'mysql', "This doesn't work on MySQL") + def test_greatest_coalesce_workaround(self): + past = datetime(1900, 1, 1) + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + last_updated=Greatest( + Coalesce('written', past), + Coalesce('published', past), + ), + ) + self.assertEqual(articles.first().last_updated, now) + + @skipUnless(connection.vendor == 'mysql', "MySQL-specific workaround") + def test_greatest_coalesce_workaround_mysql(self): + past = datetime(1900, 1, 1) + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + past_sql = RawSQL("cast(%s as datetime)", (past,)) + articles = Article.objects.annotate( + last_updated=Greatest( + Coalesce('written', past_sql), + Coalesce('published', past_sql), + ), + ) + self.assertEqual(articles.first().last_updated, now) + + def test_greatest_all_null(self): + Article.objects.create(title="Testing with Django", written=timezone.now()) + + articles = Article.objects.annotate(last_updated=Greatest('published', 'updated')) + self.assertIsNone(articles.first().last_updated) + + def test_greatest_one_expressions(self): + with self.assertRaisesMessage(ValueError, 'Greatest must take at least two expressions'): + Greatest('written') + + def test_greatest_related_field(self): + author = Author.objects.create(name='John Smith', age=45) + Fan.objects.create(name='Margaret', age=50, author=author) + + authors = Author.objects.annotate( + highest_age=Greatest('age', 'fans__age'), + ) + self.assertEqual(authors.first().highest_age, 50) + + def test_greatest_update(self): + author = Author.objects.create(name='James Smith', goes_by='Jim') + + Author.objects.update(alias=Greatest('name', 'goes_by')) + + author.refresh_from_db() + self.assertEqual(author.alias, 'Jim') + + def test_least(self): + now = timezone.now() + before = now - timedelta(hours=1) + + Article.objects.create( + title="Testing with Django", + written=before, + published=now, + ) + + articles = Article.objects.annotate( + first_updated=Least('written', 'published'), + ) + self.assertEqual(articles.first().first_updated, before) + + @skipUnlessDBFeature('greatest_least_ignores_nulls') + def test_least_ignores_null(self): + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + first_updated=Least('written', 'published'), + ) + self.assertEqual(articles.first().first_updated, now) + + @skipIfDBFeature('greatest_least_ignores_nulls') + def test_least_propogates_null(self): + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + first_updated=Least('written', 'published'), + ) + self.assertIsNone(articles.first().first_updated) + + @skipIf(connection.vendor == 'mysql', "This doesn't work on MySQL") + def test_least_coalesce_workaround(self): + future = datetime(2100, 1, 1) + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + articles = Article.objects.annotate( + last_updated=Least( + Coalesce('written', future), + Coalesce('published', future), + ), + ) + self.assertEqual(articles.first().last_updated, now) + + @skipUnless(connection.vendor == 'mysql', "MySQL-specific workaround") + def test_least_coalesce_workaround_mysql(self): + future = datetime(2100, 1, 1) + now = timezone.now() + + Article.objects.create(title="Testing with Django", written=now) + + future_sql = RawSQL("cast(%s as datetime)", (future,)) + articles = Article.objects.annotate( + last_updated=Least( + Coalesce('written', future_sql), + Coalesce('published', future_sql), + ), + ) + self.assertEqual(articles.first().last_updated, now) + + def test_least_all_null(self): + Article.objects.create(title="Testing with Django", written=timezone.now()) + + articles = Article.objects.annotate(first_updated=Least('published', 'updated')) + self.assertIsNone(articles.first().first_updated) + + def test_least_one_expressions(self): + with self.assertRaisesMessage(ValueError, 'Least must take at least two expressions'): + Least('written') + + def test_least_related_field(self): + author = Author.objects.create(name='John Smith', age=45) + Fan.objects.create(name='Margaret', age=50, author=author) + + authors = Author.objects.annotate( + lowest_age=Least('age', 'fans__age'), + ) + self.assertEqual(authors.first().lowest_age, 45) + + def test_least_update(self): + author = Author.objects.create(name='James Smith', goes_by='Jim') + + Author.objects.update(alias=Least('name', 'goes_by')) + + author.refresh_from_db() + self.assertEqual(author.alias, 'James Smith') + def test_concat(self): Author.objects.create(name='Jayden') Author.objects.create(name='John Smith', alias='smithj', goes_by='John')