Skip to main content
`Ctrl`+`K`

# 7.15.11. `highlight_html`

Added in version 4.0.5.

## 7.15.11.1. Summary

`highlight_html` tags target text. It can use to highlight the search keywords. The tagged text are prepared for embedding HTML. Special characters such as `<` and `>` are escapsed as `&lt;` and `&gt;`. Keyword is surrounded with `<span class="keyword">` and `</span>`. For example, a tagged text of `I am a groonga user. <3` for keyword `groonga` is `I am a <span class="keyword">groonga</span> user. &lt;3`.

## 7.15.11.2. Syntax

This function has from one to two parameters:

    highlight_html(text)
    highlight_html(text, {"option": "value of option"})

## 7.15.11.3. Usage

Here are a schema definition and sample data to show usage.

Execution example:

    table_create Entries TABLE_NO_KEY
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries body COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Terms document_index COLUMN_INDEX|WITH_POSITION Entries body
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Entries
    [
    {"body": "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga."}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

`highlight_html` can be used in only `--output_columns` in select before version 10.0.6 (exclusive). However, it can be also used in `--output_columns` in logical_select since version 10.0.6.

`highlight_html` requires Command version 2 or later.

You also need to specify `--query` and/or `--filter`. Keywords are extracted from `--query` and `--filter` arguments.

The following example uses `--query "groonga mysql"`. In this case, `groonga` and `mysql` are used as keywords.

Execution example:

    select Entries --output_columns --match_columns body --query 'groonga mysql' --output_columns 'highlight_html(body)' --command_version 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "Mroonga is a <span class=\"keyword\">ＭｙＳＱＬ</span> storage engine based on <span class=\"keyword\">Groonga</span>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <span class=\"keyword\">Groonga</span>."
    #       ]
    #     ]
    #   ]
    # ]

The text are scanned by the keywords for tagging after they are normalized by `NormalizerAuto` normalizer.

`--query "groonga mysql"` matches to only the first record’s body. `highlight_html(body)` surrounds the keywords `groonga` or `mysql` contained in the text with `<span class="keyword">` and `</span>`.

You can specify string literal instead of column.

Execution example:

    select Entries --output_columns 'highlight_html("Groonga is very fast fulltext search engine.")' --command_version 2 --match_columns body --query "groonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

You can use different style(e.g. background color) for each keywords by `sequential_class_tag_mode`.

Execution example:

    select Entries --match_columns body --query 'groonga OR mroonga' --output_columns 'highlight_html(body, {"sequential_class_tag_mode": true})'
    # [
    #   [
    #     0,
    #     1686038572.355064,
    #     0.002784013748168945
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "<mark class=\"keyword-0\">Mroonga</mark> is a ＭｙＳＱＬ storage engine based on <mark class=\"keyword-1\">Groonga</mark>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <mark class=\"keyword-1\">Groonga</mark>."
    #       ]
    #     ]
    #   ]
    # ]

## 7.15.11.4. Parameters

This section describes all parameters.

### 7.15.11.4.1. Required parameters

There is only one required parameter.

#### 7.15.11.4.1.1. `text`

The text to be highlighted in HTML.

### 7.15.11.4.2. Optional parameters

#### 7.15.11.4.2.1. `{"sequential_class_tag_mode": true}`

Added in version 13.0.2.

The default value of `sequential_class_tag_mode` is `false`. If `sequential_class_tag_mode` is `true`, you can use different style(e.g. background color) for each keywords.

If `sequential_class_tag_mode` is `true`, class tags are `<mark class="keyword-%d">/<mark>` for now.

## 7.15.11.5. Return value

`highlight_html` returns a tagged string or `null`. If `highlight_html` can’t find any keywords, it returns `null`.

## 7.15.11.6. See also

- select

- logical_select

- highlight_full