Fixed #21181 -- Added Collate database function.

Thanks Simon Charette for reviews.

2 files changed, 22 insertions, 0 deletions

diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index da67d9e362..f5efdb7e87 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -87,6 +87,25 @@ Usage examples::
     >>> now = timezone.now()
     >>> Coalesce('updated', Cast(now, DateTimeField()))
 
+``Collate``
+-----------
+
+.. class:: Collate(expression, collation)
+
+.. versionadded:: 3.2
+
+Takes an expression and a collation name to query against.
+
+For example, to filter case-insensitively in SQLite::
+
+    >>> Author.objects.filter(name=Collate(Value('john'), 'nocase'))
+    <QuerySet [<Author: John>, <Author: john>]>
+
+It can also be used when ordering, for example with PostgreSQL::
+
+    >>> Author.objects.order_by(Collate('name', 'et-x-icu'))
+    <QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]>
+
 ``Greatest``
 ------------
 
diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index 23b687f593..41929172c6 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -273,6 +273,9 @@ Models
   expressions that don't need to be selected but are used for filtering,
   ordering, or as a part of complex expressions.
 
+* The new :class:`~django.db.models.functions.Collate` function allows
+  filtering and ordering by specified database collations.
+
 Pagination
 ~~~~~~~~~~