Fixed #32492 -- Added TrigramWordSimilarity() and TrigramWordDistance() on PostgreSQL.

2 files changed, 72 insertions, 5 deletions

diff --git a/docs/ref/contrib/postgres/lookups.txt b/docs/ref/contrib/postgres/lookups.txt
index ab7a954bf2..d9f76318cc 100644
--- a/docs/ref/contrib/postgres/lookups.txt
+++ b/docs/ref/contrib/postgres/lookups.txt
@@ -14,9 +14,8 @@ returns results that have a similarity measurement greater than the current
 similarity threshold.
 
 To use it, add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`
-and activate the `pg_trgm extension
-<https://www.postgresql.org/docs/current/pgtrgm.html>`_ on PostgreSQL. You can
-install the extension using the
+and activate the `pg_trgm extension`_ on PostgreSQL. You can install the
+extension using the
 :class:`~django.contrib.postgres.operations.TrigramExtension` migration
 operation.
 
@@ -26,6 +25,31 @@ The ``trigram_similar`` lookup can be used on
     >>> City.objects.filter(name__trigram_similar="Middlesborough")
     ['<City: Middlesbrough>']
 
+.. fieldlookup:: trigram_word_similar
+
+.. versionadded:: 4.0
+
+The ``trigram_word_similar`` lookup allows you to perform trigram word
+similarity lookups using a dedicated PostgreSQL extension. It can be
+approximately understood as measuring the greatest number of trigrams shared
+between the parameter and any substring of the field. A trigram word lookup is
+given an expression and returns results that have a word similarity measurement
+greater than the current similarity threshold.
+
+To use it, add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`
+and activate the `pg_trgm extension`_ on PostgreSQL. You can install the
+extension using the
+:class:`~django.contrib.postgres.operations.TrigramExtension` migration
+operation.
+
+The ``trigram_word_similar`` lookup can be used on
+:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`::
+
+    >>> Sentence.objects.filter(name__trigram_word_similar='Middlesborough')
+    ['<Sentence: Gumby rides on the path of Middlesbrough>']
+
+.. _`pg_trgm extension`: https://www.postgresql.org/docs/current/pgtrgm.html
+
 ``Unaccent``
 ============
 
diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt
index fe4e86f05e..cfed877d9c 100644
--- a/docs/ref/contrib/postgres/search.txt
+++ b/docs/ref/contrib/postgres/search.txt
@@ -280,8 +280,9 @@ Trigram similarity
 ==================
 
 Another approach to searching is trigram similarity. A trigram is a group of
-three consecutive characters. In addition to the :lookup:`trigram_similar`
-lookup, you can use a couple of other expressions.
+three consecutive characters. In addition to the :lookup:`trigram_similar` and
+:lookup:`trigram_word_similar` lookups, you can use a couple of other
+expressions.
 
 To use them, you need to activate the `pg_trgm extension
 <https://www.postgresql.org/docs/current/pgtrgm.html>`_ on PostgreSQL. You can
@@ -308,6 +309,27 @@ Usage example::
     ... ).filter(similarity__gt=0.3).order_by('-similarity')
     [<Author: Katy Stevens>, <Author: Stephen Keats>]
 
+``TrigramWordSimilarity``
+-------------------------
+
+.. versionadded:: 4.0
+
+.. class:: TrigramWordSimilarity(string, expression, **extra)
+
+Accepts a string or expression, and a field name or expression. Returns the
+trigram word similarity between the two arguments.
+
+Usage example::
+
+    >>> from django.contrib.postgres.search import TrigramWordSimilarity
+    >>> Author.objects.create(name='Katy Stevens')
+    >>> Author.objects.create(name='Stephen Keats')
+    >>> test = 'Kat'
+    >>> Author.objects.annotate(
+    ...     similarity=TrigramWordSimilarity(test, 'name'),
+    ... ).filter(similarity__gt=0.3).order_by('-similarity')
+    [<Author: Katy Stevens>]
+
 ``TrigramDistance``
 -------------------
 
@@ -326,3 +348,24 @@ Usage example::
     ...     distance=TrigramDistance('name', test),
     ... ).filter(distance__lte=0.7).order_by('distance')
     [<Author: Katy Stevens>, <Author: Stephen Keats>]
+
+``TrigramWordDistance``
+-----------------------
+
+.. versionadded:: 4.0
+
+.. class:: TrigramWordDistance(string, expression, **extra)
+
+Accepts a string or expression, and a field name or expression. Returns the
+trigram word distance between the two arguments.
+
+Usage example::
+
+    >>> from django.contrib.postgres.search import TrigramWordDistance
+    >>> Author.objects.create(name='Katy Stevens')
+    >>> Author.objects.create(name='Stephen Keats')
+    >>> test = 'Kat'
+    >>> Author.objects.annotate(
+    ...     distance=TrigramWordDistance(test, 'name'),
+    ... ).filter(distance__lte=0.7).order_by('distance')
+    [<Author: Katy Stevens>]