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.
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 |
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.
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')
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 |
_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), ] )