diff --git a/django/contrib/postgres/search.py b/django/contrib/postgres/search.py
index 484d4315b9..761ce3c70a 100644
--- a/django/contrib/postgres/search.py
+++ b/django/contrib/postgres/search.py
@@ -1,3 +1,5 @@
+import psycopg2
+
from django.db.models import (
CharField, Expression, Field, FloatField, Func, Lookup, TextField, Value,
)
@@ -230,6 +232,57 @@ class SearchRank(Func):
super().__init__(*expressions)
+class SearchHeadline(Func):
+ function = 'ts_headline'
+ template = '%(function)s(%(expressions)s%(options)s)'
+ output_field = TextField()
+
+ def __init__(
+ self, expression, query, *, config=None, start_sel=None, stop_sel=None,
+ max_words=None, min_words=None, short_word=None, highlight_all=None,
+ max_fragments=None, fragment_delimiter=None,
+ ):
+ if not hasattr(query, 'resolve_expression'):
+ query = SearchQuery(query)
+ options = {
+ 'StartSel': start_sel,
+ 'StopSel': stop_sel,
+ 'MaxWords': max_words,
+ 'MinWords': min_words,
+ 'ShortWord': short_word,
+ 'HighlightAll': highlight_all,
+ 'MaxFragments': max_fragments,
+ 'FragmentDelimiter': fragment_delimiter,
+ }
+ self.options = {
+ option: value
+ for option, value in options.items() if value is not None
+ }
+ expressions = (expression, query)
+ if config is not None:
+ config = SearchConfig.from_parameter(config)
+ expressions = (config,) + expressions
+ super().__init__(*expressions)
+
+ def as_sql(self, compiler, connection, function=None, template=None):
+ options_sql = ''
+ options_params = []
+ if self.options:
+ # getquoted() returns a quoted bytestring of the adapted value.
+ options_params.append(', '.join(
+ '%s=%s' % (
+ option,
+ psycopg2.extensions.adapt(value).getquoted().decode(),
+ ) for option, value in self.options.items()
+ ))
+ options_sql = ', %s'
+ sql, params = super().as_sql(
+ compiler, connection, function=function, template=template,
+ options=options_sql,
+ )
+ return sql, params + options_params
+
+
SearchVectorField.register_lookup(SearchVectorExact)
diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt
index 813a3db57a..949d95929e 100644
--- a/docs/ref/contrib/postgres/search.txt
+++ b/docs/ref/contrib/postgres/search.txt
@@ -132,6 +132,60 @@ order by relevancy::
See :ref:`postgresql-fts-weighting-queries` for an explanation of the
``weights`` parameter.
+``SearchHeadline``
+==================
+
+.. versionadded:: 3.1
+
+.. class:: SearchHeadline(expression, query, config=None, start_sel=None, stop_sel=None, max_words=None, min_words=None, short_word=None, highlight_all=None, max_fragments=None, fragment_delimiter=None)
+
+Accepts a single text field or an expression, a query, a config, and a set of
+options. Returns highlighted search results.
+
+Set the ``start_sel`` and ``stop_sel`` parameters to the string values to be
+used to wrap highlighted query terms in the document. PostgreSQL's defaults are
+```` and ````.
+
+Provide integer values to the ``max_words`` and ``min_words`` parameters to
+determine the longest and shortest headlines. PostgreSQL's defaults are 35 and
+15.
+
+Provide an integer value to the ``short_word`` parameter to discard words of
+this length or less in each headline. PostgreSQL's default is 3.
+
+Set the ``highlight_all`` parameter to ``True`` to use the whole document in
+place of a fragment and ignore ``max_words``, ``min_words``, and ``short_word``
+parameters. That's disabled by default in PostgreSQL.
+
+Provide a non-zero integer value to the ``max_fragments`` to set the maximum
+number of fragments to display. That's disabled by default in PostgreSQL.
+
+Set the ``fragment_delimiter`` string parameter to configure the delimiter
+between fragments. PostgreSQL's default is ``" ... "``.
+
+The PostgreSQL documentation has more details on `highlighting search
+results`_.
+
+Usage example::
+
+ >>> from django.contrib.postgres.search import SearchHeadline, SearchQuery
+ >>> query = SearchQuery('red tomato')
+ >>> entry = Entry.objects.annotate(
+ ... headline=SearchHeadline(
+ ... 'body_text',
+ ... query,
+ ... start_sel='',
+ ... stop_sel='',
+ ... ),
+ ... ).get()
+ >>> print(entry.headline)
+ Sandwich with tomato and red cheese.
+
+See :ref:`postgresql-fts-search-configuration` for an explanation of the
+``config`` parameter.
+
+.. _highlighting search results: https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE
+
.. _postgresql-fts-search-configuration:
Changing the search configuration
diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt
index 669f2ca01e..b1ae1134cb 100644
--- a/docs/releases/3.1.txt
+++ b/docs/releases/3.1.txt
@@ -108,6 +108,9 @@ Minor features
* :class:`~django.contrib.postgres.search.SearchQuery` now supports
``'websearch'`` search type on PostgreSQL 11+.
+* The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows
+ highlighting search results.
+
:mod:`django.contrib.redirects`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/tests/postgres_tests/test_search.py b/tests/postgres_tests/test_search.py
index 765b846fb3..298932ba2e 100644
--- a/tests/postgres_tests/test_search.py
+++ b/tests/postgres_tests/test_search.py
@@ -5,16 +5,20 @@ These tests use dialogue from the 1975 film Monty Python and the Holy Grail.
All text copyright Python (Monty) Pictures. Thanks to sacred-texts.com for the
transcript.
"""
-from django.contrib.postgres.search import (
- SearchConfig, SearchQuery, SearchRank, SearchVector,
-)
from django.db import connection
from django.db.models import F
-from django.test import SimpleTestCase, modify_settings, skipUnlessDBFeature
+from django.test import modify_settings, skipUnlessDBFeature
from . import PostgreSQLSimpleTestCase, PostgreSQLTestCase
from .models import Character, Line, Scene
+try:
+ from django.contrib.postgres.search import (
+ SearchConfig, SearchHeadline, SearchQuery, SearchRank, SearchVector,
+ )
+except ImportError:
+ pass
+
class GrailTestData:
@@ -436,7 +440,7 @@ class SearchVectorIndexTests(PostgreSQLTestCase):
)
-class SearchQueryTests(SimpleTestCase):
+class SearchQueryTests(PostgreSQLSimpleTestCase):
def test_str(self):
tests = (
(~SearchQuery('a'), '~SearchQuery(a)'),
@@ -460,3 +464,118 @@ class SearchQueryTests(SimpleTestCase):
for query, expected_str in tests:
with self.subTest(query=query):
self.assertEqual(str(query), expected_str)
+
+
+@modify_settings(INSTALLED_APPS={'append': 'django.contrib.postgres'})
+class SearchHeadlineTests(GrailTestData, PostgreSQLTestCase):
+ def test_headline(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ F('dialogue'),
+ SearchQuery('brave sir robin'),
+ config=SearchConfig('english'),
+ ),
+ ).get(pk=self.verse0.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Robin. He was not at all afraid to be killed in nasty '
+ 'ways. Brave, brave, brave, brave '
+ 'Sir Robin',
+ )
+
+ def test_headline_untyped_args(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline('dialogue', 'killed', config='english'),
+ ).get(pk=self.verse0.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Robin. He was not at all afraid to be killed in nasty '
+ 'ways. Brave, brave, brave, brave Sir Robin!',
+ )
+
+ def test_headline_with_config(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ SearchQuery('cadeaux', config='french'),
+ config='french',
+ ),
+ ).get(pk=self.french.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Oh. Un beau cadeau. Oui oui.',
+ )
+
+ def test_headline_with_config_from_field(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ SearchQuery('cadeaux', config=F('dialogue_config')),
+ config=F('dialogue_config'),
+ ),
+ ).get(pk=self.french.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Oh. Un beau cadeau. Oui oui.',
+ )
+
+ def test_headline_separator_options(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ 'brave sir robin',
+ start_sel='',
+ stop_sel='',
+ ),
+ ).get(pk=self.verse0.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Robin. He was not at all afraid to be killed in '
+ 'nasty ways. Brave, brave, brave'
+ ', brave Sir Robin',
+ )
+
+ def test_headline_highlight_all_option(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ SearchQuery('brave sir robin', config='english'),
+ highlight_all=True,
+ ),
+ ).get(pk=self.verse0.pk)
+ self.assertIn(
+ 'Bravely bold Sir Robin, rode forth from '
+ 'Camelot. He was not afraid to die, o ',
+ searched.headline,
+ )
+
+ def test_headline_short_word_option(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ SearchQuery('brave sir robin', config='english'),
+ short_word=6,
+ ),
+ ).get(pk=self.verse0.pk)
+ self.assertIs(searched.headline.endswith(
+ 'Brave, brave, brave, brave Sir'
+ ), True)
+
+ def test_headline_fragments_words_options(self):
+ searched = Line.objects.annotate(
+ headline=SearchHeadline(
+ 'dialogue',
+ SearchQuery('brave sir robin', config='english'),
+ fragment_delimiter='...
',
+ max_fragments=4,
+ max_words=3,
+ min_words=1,
+ ),
+ ).get(pk=self.verse0.pk)
+ self.assertEqual(
+ searched.headline,
+ 'Sir Robin, rode...
'
+ 'Brave Sir Robin...
'
+ 'Brave, brave, brave...
'
+ 'brave Sir Robin',
+ )
diff --git a/tests/postgres_tests/test_trigram.py b/tests/postgres_tests/test_trigram.py
index 2a123faa5e..19ac4cee31 100644
--- a/tests/postgres_tests/test_trigram.py
+++ b/tests/postgres_tests/test_trigram.py
@@ -1,9 +1,13 @@
-from django.contrib.postgres.search import TrigramDistance, TrigramSimilarity
from django.test import modify_settings
from . import PostgreSQLTestCase
from .models import CharFieldModel, TextFieldModel
+try:
+ from django.contrib.postgres.search import TrigramDistance, TrigramSimilarity
+except ImportError:
+ pass
+
@modify_settings(INSTALLED_APPS={'append': 'django.contrib.postgres'})
class TrigramTest(PostgreSQLTestCase):