Highlighting

Optimizely Graph lets you display snippets of your content found in a GrapQL query. A snippet is a short text fragment comprising the words you have searched for. It is also called Key Word in Context (KWIC).

Using snippets is especially helpful to:

summarize the context by presenting only the relevant content.
improve the user experience on a page.
display relevant content when shown on small screens (mobile devices) or not presented (such as voice).
increase engagement by presenting highly relevant information.

The snippets will help users discover what they want. This makes it easier for users to interact with your content by reading and eventually clicking on it. This can help to drive conversions with search.

Enable highlighted snippets in Optimizely Graph

Highlighted snippets are useful for fields with a lot of content: paragraphs or pages of text. Optimizely Graph supports retrieving highlighted snippets on searchable string fields that support full-text search. You can enable displaying highlighted snippets instead of content in a field by using the highlight input argument for searchable fields.

📘
Note
When highlight is enabled for _fulltext and if matching in the where function is applied on other search terms in searchable fields except _fulltext, then those search terms will also be highlighted as part of _fulltext. The reason is that _fulltext is a special field that consists of matching on all searchable fields, so the highlighted terms are a union of all searchable fields.
Example:
query MyQuery {
 ProductPage(
 locale: en
 where: {
 MainBody: { match: "aromatic evergreen shrub" }
 _fulltext: { match: "aromatic" }
 }
 ) {
 total
 items {
 MainBody(highlight: { enabled: true })
 _fulltext(highlight: { enabled: true })
 }
 }
}
This will return the following highlighted snippets:
{
 "data": {
 "ProductPage": {
 "total": 1,
 "items": [
 {
 "MainBody": "Rosemary is an aromatic evergreen shrub with leaves similar to hemlock needles.",
 "_fulltext": [
 "Rosemary is an aromatic evergreen shrub with leaves similar to hemlock needles."
 ]
 }
 ]
 }
 }

To get snippets returned, you need to use the where argument to do a full-text search with match or contains as operator. Only fields that have matching items in the where will return highlighted snippets. Returning highlighted snippets is supported for _fulltext field. The snippets returned by Optimizely Graph will remove any HTML tags (and only keep the tags for the highlighted keywords) so that they can be processed easily.

📘
Note
Optimizely Graph does not support highlighting with matches on only semantic search.

If there is a matching because of a semantic match, then Optimizely Graph will return the original value instead.

If there are literal matches with semantic search, then those literal matches are highlighted.

In the following example, a full-text search on the MainBody field is completed by matching on taylor avicii. In the MainBody, you can use the highlight argument and set enabled to true.

{
  BiographyPage(locale: sv, where: { MainBody: { match: "taylor avicii" } }) {
    total
    items {
      MainBody(highlight: { enabled: true })
    }
  }
}

This will return the following example response:

{
  "data": {
    "BiographyPage": {
      "total": 2,
      "items": [
        {
          "MainBody": "<em>Avicii</em>, egentligen Tim Bergling, ursprungligen Lidén, född 8 september 1989 i Oscars församling i ... <em>Avicii</em> hade vid den tiden blivit en internationellt uppmärksammad DJ/musikproducent och som en ... <em>Avicii</em> fick under sitt liv två Grammynomineringar: \"Sunshine\" med David Guetta (2012) samt för \"Levels ... <em>Avicii</em> begick självmord i Muskat i Oman 2018. Han var då 28 år. ... <em>Avicii</em> är gravsatt på Hedvig Eleonora kyrkogård i Stockholm."
        },
        {
          "MainBody": "<em>Taylor</em> Alison Swift, född 13 december 1989 i Reading i Pennsylvania, är en amerikansk popsångare och ... Den var den första av fem singlar från hennes debutalbum <em>Taylor</em> Swift, vilket släpptes i slutet av 2006"
        }
      ]
    }
  },
  "extensions": {
    "correlationId": "7febf5eb-329d-4971-a88d-e1c6495c4bce",
    "cost": 24,
    "costSummary": [
      "BiographyPage(24) = limit(20) + fields(1) + basicFilter(1)*2 + highlight(1)"
    ]
  }
}

Customization of highlighting

You can configure the format of the highlighted terms in the snippets with the arguments startToken and endToken. By default, it is  (startToken) and  (endToken).

📘
Note
When highlight is enabled for search phrases that contain punctuation, then the punctuation characters will not be included within the startToken and endToken.
Example:
query MyQuery {
 SnippetsPage(
 locale: ALL
 where: { p_String: { contains: "One UI 6-1." } }
 ) {
 total
 items {
 p_String (highlight: {enabled: true})
 }
 }
}
Then the snippet is:
{
 "data": {
 "SnippetsPage": {
 "total": 1,
 "items": [
 {
 "p_String": "Samsung Galaxy S24 Ultra: One UI 6-1."
 }
 ]
 }
 }
}

In the the following example, a full-text search is completed on two fields using the Boolean operators: MainBody and Name. Highlighting is enabled on these two fields in the projection in items. For MainBody, it is defined that highlighted keywords should be wrapped in the italic  tags. Name is any matching keyword that should start with **. This lets you define a snippet as a pure text fragment.

{
  BiographyPage(
    locale: sv
    where: {
      _or: [
        { MainBody: { match: "taylor avicii" } }, 
        { Name: { match: "taylor avicii" } }
      ]
    }
  ) {
    total
    items {
      MainBody(highlight: { enabled: true, startToken: "<i>", endToken: "</i>" })
      Name(highlight: { enabled: true, startToken: "**" })
    }
  }
}

The following is an expected example response. Here, the snippets were highlighted with different start and end tokens. In Name, the snippet is **Taylor Swift because the endToken was not defined, so Optimizely Graph will use  by default.

{
  "data": {
    "BiographyPage": {
      "total": 2,
      "items": [
        {
          "MainBody": "<i>Taylor</i> Alison Swift, född 13 december 1989 i Reading i Pennsylvania, är en amerikansk popsångare och ... Den var den första av fem singlar från hennes debutalbum <i>Taylor</i> Swift, vilket släpptes i slutet av 2006",
          "Name": "**Taylor</em> Swift"
        },
        {
          "MainBody": "<i>Avicii</i>, egentligen Tim Bergling, ursprungligen Lidén, född 8 september 1989 i Oscars församling i ... <i>Avicii</i> hade vid den tiden blivit en internationellt uppmärksammad DJ/musikproducent och som en ... <i>Avicii</i> fick under sitt liv två Grammynomineringar: \"Sunshine\" med David Guetta (2012) samt för \"Levels ... <i>Avicii</i> begick självmord i Muskat i Oman 2018. Han var då 28 år. ... <i>Avicii</i> är gravsatt på Hedvig Eleonora kyrkogård i Stockholm.",
          "Name": "Tim Bergling"
        }
      ]
    }
  },
  "extensions": {
    "correlationId": "0d92084d-488b-420d-b37d-11605482a6a2",
    "cost": 28,
    "costSummary": [
      "BiographyPage(28) = limit(20) + fields(2) + basicFilter(2)*2 + highlight(2)"
    ]
  }
}

Synonyms and highlighting

You can use synonyms in combination with highlighting. The actual keyword equivalent to the matching synonym is highlighted if a synonym is used. In the following example, the Swedish content is stored in the following bi-directional synonym: Taylor Swift, Queen. In other words, Taylor Swift and Queen are considered to be equivalent.

{
  BiographyPage(
    locale: sv
    where: { _fulltext: { match: "queen", synonyms: ONE } }
  ) {
    total
    items {
      _fulltext(highlight: { enabled: true })
    }
  }
}

The query will then retrieve the following highlighted snippets:

{
  "data": {
    "BiographyPage": {
      "total": 1,
      "items": [
        {
          "_fulltext": [
            "<em>Taylor</em> <em>Swift</em>",
            "<em>Taylor</em> Alison <em>Swift</em>, född 13 december 1989 i Reading i Pennsylvania, är en amerikansk popsångare och ... Den var den första av fem singlar från hennes debutalbum <em>Taylor</em> <em>Swift</em>, vilket släpptes i slutet av 2006"
          ]
        }
      ]
    }
  },
  "extensions": {
    "correlationId": "9cb8162b-3b57-4984-8dd6-bef62a33a4b1",
    "cost": 26,
    "costSummary": [
      "BiographyPage(26) = limit(20) + fields(1) + basicFilter(2)*2 + highlight(1)"
    ]
  }
}

More examples

Snippets are returned when the where matches the projection in items and highlight is enabled in the projection field. The following query:

{
  BiographyPage(locale: sv, where: { _fulltext: { match: "taylor avicii" } }) {
    total
    items {
      _fulltext(highlight: { enabled: true })
      MainBody
      Name
    }
  }
}

Returns the following response:

{
  "data": {
    "BiographyPage": {
      "total": 2,
      "items": [
        {
          "_fulltext": [
            "<em>Avicii</em>",
            "<em>Avicii</em>, egentligen Tim Bergling, ursprungligen Lidén, född 8 september 1989 i Oscars församling i ... <em>Avicii</em> hade vid den tiden blivit en internationellt uppmärksammad DJ/musikproducent och som en ... <em>Avicii</em> fick under sitt liv två Grammynomineringar: \"Sunshine\" med David Guetta (2012) samt för \"Levels ... <em>Avicii</em> begick självmord i Muskat i Oman 2018. Han var då 28 år. ... <em>Avicii</em> är gravsatt på Hedvig Eleonora kyrkogård i Stockholm.",
            "Tim Bergling"
          ],
          "MainBody": "<p>Avicii, egentligen Tim Bergling, ursprungligen Lidén, född 8 september 1989 i Oscars församling i Stockholm, död 20 april 2018 i Muskat i Oman, var en svensk discjockey, musiker, remixare, låtskrivare samt musikproducent. Flera musikpublikationer anger honom som en av de DJ:ar som populariserade den elektroniska musiken i början av 2010-talet och åren 2011–2015 rankades han följdriktigt kontinuerligt på plats 3–7 på DJ Mag:s lista över världens 100 bästa DJ:ar.</p><p>Han inledde sin karriär vid 16 års ålder genom att lägga upp remixer av elektronisk musik på internetforum, vilket till sist ledde till ett skivkontrakt. Han gick Östra reals gymnasium. Genombrottet kom 2011 med låten \"Levels\", som blev en stor internationell hit, och följdes 2013 av debutalbumet True som nådde topp 10-placeringar i fler än femton länder och blev etta i Australien, Sverige och Danmark samt på Hot Dance Club Songs i USA. Albumet innehöll singeln \"Wake Me Up\" som kom att bli hans största hitlåt då den toppade de flesta listorna i Europa, låg 14 veckor i rad på Billboards lista för dans-/elektronisk musik och under en period var den mest spelade låten på Spotify.</p><p>Avicii hade vid den tiden blivit en internationellt uppmärksammad DJ/musikproducent och som en av de största inom genren elektronisk dansmusik gav han konserter runt om i världen. 2015 kom det andra studioalbumet, Stories, men året därpå meddelade han att han skulle sluta turnera av hälsoskäl; dock ämnade han fortsätta producera musik.</p><p>Bland Aviciis övriga låtar som rönt kommersiella framgångar kan nämnas \"Waiting for Love\", \"Without You\", \"Lonely Together\", \"I Could Be the One\", \"Fade into Darkness\", \"Hey Brother\", \"Addicted to You\" och \"Silhouettes\". Avicii fick under sitt liv två Grammynomineringar: \"Sunshine\" med David Guetta (2012) samt för \"Levels\" (2013).</p><p>Avicii begick självmord i Muskat i Oman 2018. Han var då 28 år. Avicii är gravsatt på Hedvig Eleonora kyrkogård i Stockholm.</p>",
          "Name": "Tim Bergling"
        },
        {
          "_fulltext": [
            "<em>Taylor</em> Swift",
            "<em>Taylor</em> Alison Swift, född 13 december 1989 i Reading i Pennsylvania, är en amerikansk popsångare och ... Den var den första av fem singlar från hennes debutalbum <em>Taylor</em> Swift, vilket släpptes i slutet av 2006"
          ],
          "MainBody": "<p>Taylor Alison Swift, född 13 december 1989 i Reading i Pennsylvania, är en amerikansk popsångare och låtskrivare.</p><p>Swifts musikkarriär började i de tidiga tonåren och hon fick tidigt kontakt med musikindustrin. Vid 14 års ålder (2004) flyttade Swift till Nashville på grund av sitt intresse för countrymusik.</p><p>I september 2006 gjorde hon debut på Billboard-countrylistan med debutsingeln \"Tim McGraw\". Låten hamnade som bäst på sjätte plats. Den var den första av fem singlar från hennes debutalbum Taylor Swift, vilket släpptes i slutet av 2006 och återlanserades 2007. Albumet har enligt RIAA uppnått multiplatina tre gånger och låg på Billboard 200 under 275 veckor.</p><p>Snart hamnade ytterligare en av hennes debutsinglar, \"Teardrops On My Guitar\" (#2) på en andraplats. Sex veckor senare toppade hennes \"Our Song\" listan samtidigt som hennes \"Picture to Burn\" (#3) låg på en tredjeplats. Ännu en förstaplats skulle senare intas med singeln \"Should've Said No\". Alla fem singlar från hennes debutalbum hamnade på Topp 40-hits på Billboard Hot 100. Det gjorde även \"Change\" från AT&T TEAM USA Soundtrack.</p><p>Hennes andra album Fearless släpptes 11 november 2008. Från det albumet heter den första singeln \"Love Story\", vilken som bäst nådde plats fyra på Billboard Hot 100.</p>",
          "Name": "Taylor Swift"
        }
      ]
    }
  },
  "extensions": {
    "correlationId": "31ae400f-f16c-4afc-b9cd-e1fe68fbf1d9",
    "cost": 26,
    "costSummary": [
      "BiographyPage(26) = limit(20) + fields(3) + basicFilter(1)*2 + highlight(1)"
    ]
  }
}

When highlighting is enabled on all fields with the following query, the same response is returned as in the previous example.

{
  BiographyPage(locale: sv, where: { _fulltext: { match: "taylor avicii" } }) {
    total
    items {
      _fulltext(highlight: { enabled: true })
      MainBody(highlight: { enabled: true })
      Name(highlight: { enabled: true })
    }
  }
}

Highlighting

Enable highlighted snippets in Optimizely Graph

📘
Note

📘
Note

Customization of highlighting

📘
Note

Synonyms and highlighting

More examples

Enable highlighted snippets in Optimizely Graph

📘Note

📘Note

Customization of highlighting

📘Note

Synonyms and highlighting

More examples

📘
Note

📘
Note

📘
Note