The Highlight stage is used to get highlighted snippets from one or more fields in your search results so you can show users where the query matches are.

The results of the searches are highlighted with tags before and after each piece of matched text and are returned as a result of this stage to be used on further stages or to show it on the UI.

Properties

Property	Description	Default	Type	Required
name	Name for this specific stage. Used on the intermediate and final parameters.	"highlight"	string	Yes
engine_name	Name of the engine to use of this query. If none is provided, the default engine will be used.	None	string	No
pre_tags	Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags. Specify as an array of strings.	['<strong>']	array of strings	Yes
pos_tags	Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags. Specify as an array of strings.	['<strong>']	array of strings	Yes
tags_schema	Set to styled to use the built-in tag schema.	None	string	No
force_source (DEPRECATED)	Forces the highlighting to highlight fields based on the source even if fields are stored separately.	False	boolean	Yes
require_field_match	By default, only fields that contains a query match are highlighted. Set require_field_match to false to highlight all fields.	True	boolean	Yes
number_of_fragments	The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.	5	integer	Yes
fragment_size	The size of the highlighted fragment in characters.	100	integer	Yes
order	Sorts highlighted fragments by score when set to score. By default, fragments will be output in the order they appear in the field (order: none)	None	string	No
fields	Specifies the fields to retrieve highlights for.	None	array of HighlightField	No

Intermediate Parameters

This stage does not require any specific intermediate parameters, nevertheless, you can use any value in the intermediate or final objects as long as it matches the jsonpath pattern provided.

Remember that the intermediate can be fill with either other stages or the original request body that trigger the pipeline, making this essentially REST API parameters.

Additional Classes for Configuration

HighlightField

The HighlightField is a configuration object that provides specific settings for the HighlightStage.

field: str
fragment_size: Optional[int] = Field(default=None)
number_of_fragments: Optional[int] = Field(default=None)
highlight_query: Optional[dict] = Field(default=None,
                                        description='Highlight matches for a query other than the search query.')
type: Optional[str] = Field(default=None)
force_source: bool = Field(default=False,
                           description='Forces the highlighting to highlight fields based on the source even if '
                                       'fields are stored separately')

HighlightField Properties

Property	Description	Default	Type	Required
field	Name of the field to be highlighted.	-	string	Yes
fragment_size	Same as above. The size of the highlighted fragment in characters for this specific field (overrides the global configuration if set).	None	integer	No
number_of_fragments	Same as above. The maximum number of fragments to return for this specific field (overrides the global configuration if set).	None	integer	No
highlight_query	Highlight matches for a query other than the search query.	None	object	No
type	Name of the field type.	None	string	No
force_source (DEPRECATED)	Same as above. Forces the highlighting to highlight fields based on the source even if fields are stored separately for this specific field. (overrides the global configuration if set).	False	boolean	Yes

Example Configuration

_highlight_stage = HighlightStage(
    enable=True,
    type='HighlightStage',
    name='highlight',
    engine_name=DEFAULT_ENGINE_NAME,
    pre_tags=['<strong>'],
    pos_tags=['</strong>'],
    tags_schema=None,
    force_source=False,
    require_field_match=True,
    number_of_fragments=3,
    fragment_size=100,
    order=None,
    fields=[
        HighlightField(field='title', number_of_fragments=1),
        HighlightField(field='overview', number_of_fragments=5),
        HighlightField(field='url', number_of_fragments=1),
    ]
)

Space shortcuts

Page tree