Docs Developer Site
DeveloperDocsXpStableStorageHighlighting

Highlighting

Contents

Highligting was first introduced in version 7.1

Introduction

Highlighters enable you to get highlighted snippets from one or more properties in your search results so you can show users where the query matches are. When you request highlights, the response contains an additional highlight element for each search hit that includes the highlighted properties and the highlighted fragments.

Highlighting options

encoder (string)

Indicates if the snippet should be HTML encoded: default (no encoding) or html.

fragmenter (string)

Specifies how text should be broken up in highlight snippets: simple or span (default).

fragmentSize (number)

The size of the highlighted fragment in characters. Defaults to 100.

numberOfFragments (number)

The maximum number of fragments to return. If numberOfFragments is 0, no fragments will be returned and fragmentSize will be ignored. Defaults to 5.

noMatchSize (number)

The amount of characters you want to return from the beginning of the property if there are no matching fragments to highlight. Defaults to 0 (nothing is returned).

order (string)

Sorts highlighted fragments by score when set to score. Defaults to none - will be displayed in the same order in which fragments appear in the property.

preTag (string)

Use in conjunction with postTag to define the HTML tags to wrap the highlighted text. <em> by default.

postTag (string)

Use in conjunction with preTag to define the HTML tags to wrap the highlighted text. </em> by default.

requireFieldMatch (boolean)

Set to false if you want to highlight result in every listed property, regardless it was used in the query or not. Default is true.

tagsSchema (string)

Set to styled to use the built-in tag schema.

Highlighting settings can be set on a global level and then overridden on the property level (except tagsSchema and encoder, these two can be set only on the global layer).

Highlighting Tags

By default, the highlighting will wrap highlighted text inside <em></em> tag. This can be controlled by setting prePag and postTag, for example:

Sample with custom tags

Request:

{
  "query": "fulltext('description', 'house garden')",
  "highlight": {
    "preTag": "<tag1>",
    "postTag": "</tag1>",
    "properties": {
      "description": {}
    }
  }
}

Response:

{
   ...
  "highlight": {
    "c4bb11f1-c6e2-4849-a665-28f612213984": {
      "description": [
        "Traditional <tag1>house</tag1> with big and well maintained <tag1>garden</tag1>."
      ]
    }
  }
}

Encoder

Parameter encoder can be used to define how highlighted text will be encoded. html value will force escaping html, if you use html highlighting tags.

Highlighted Fragments

Each highlighted property can control the size of the highlighted fragment in characters, and the maximum number of fragments to return. On top of this it is possible to specify that highlighted fragments need to be sorted by score. For example:

Sample fragmentSize reducing

Request:

{
  query: "fulltext('description', 'house garden big')",
  highlight: {
    properties: {
      "description": {
        fragmentSize: 15,
        numberOfFragments: 2
      }
    }
  }
}

Response:

{
    ...
  "highlight": {
    "c4bb11f1-c6e2-4849-a665-28f612213984": {
      "description": [
        " <em>house</em> with <em>big</em>",
        " maintained <em>garden</em>."
      ]
    }
  }
}

If number_of_fragments is set to 0 then no fragments are produced, instead the entire content of the property is returned, and of course it is highlighted.

Fragmenter

You can choose between simple (default) and span fragmenters:

Simple Fragmenter

Request:

{
  query: "fulltext('description', 'house garden')",
  highlight: {
    fragmentSize : 15,
    fragmenter: "simple",
    properties: {
      "description": {}
    }
  }
}

Response:

{
    ...
  "highlight": {
    "9922a270-f881-4bf8-be35-189e9a72a4f1": {
      "description": [
        "Traditional <em>house</em> with big and well maintained <em>garden</em>."
      ]
    }
  }
}
Span Fragmenter

Request:

{
  query: "fulltext('description', 'house garden')",
  highlight: {
    fragmentSize : 15,
    fragmenter: "span",
    properties: {
      "description": {}
    }
  }
}

Response:

{
    ...
  "highlight": {
    "9922a270-f881-4bf8-be35-189e9a72a4f1": {
      "description": [
        " maintained <em>garden</em>.",
        " <em>house</em> with big"
      ]
    }
  }
}

Tag Schema

There are also built in "tag" schemas, currently with one single schema called styled with the following tags:

<em class="hlt1">, <em class="hlt2">, <em class="hlt3">,
<em class="hlt4">, <em class="hlt5">, <em class="hlt6">,
<em class="hlt7">, <em class="hlt8">, <em class="hlt9">,
<em class="hlt10">

Require Field Match

requireFieldMatch can be set to false which will cause any property to be highlighted regardless of whether its value matches the query. The default behaviour is true, meaning that only properties that match the query will be highlighted.

Sample with disabled requireFieldMatch property

Request:

{
  query: "fulltext('anyOtherProperty', 'house')",
  highlight: {
    requireFieldMatch: false,
    properties: {
      "description": {}
    }
  }
}

Response:

{
    ...
  "highlight": {
    "c4bb11f1-c6e2-4849-a665-28f612213984": {
      "description": [
        "Traditional <em>house</em> with big and well maintained garden."
      ]
    }
  }
}

Global Settings

Highlighting settings can be set on a global level and then overridden on the property level.

Sample global properties overridden for each property 
{
    "query" : {...},
    "highlight" : {
        "numberOfFragments" : 3,
        "fragmentSize" : 150,
        "order": "none",
        "properties" : {
            "displayName" : { "numberOfFragments" : 0 },
            "description" : { "preTags" : ["<tag1>"], "postTags" : ["</tag1>"] },
            "data.address" : { "numberOfFragments" : 5, "order" : "score" }
        }
    }
}

Contents

Contents