Skip to main content
`Ctrl`+`K`

# 7.15.9. `highlight`

New in version 6.0.0.

## 7.15.9.1. Summary

`highlight` tags target text. It can use to highlight the search keyword. It can specify use/not use HTML escape, the normalizer name and change the tag for each keyword.

## 7.15.9.2. Syntax

`highlight` has required parameter and optional parameter:

    highlight(column,
              keyword1, open_tag1, close_tag1,
              ...
              [keywordN, open_tagN, close_tagN],
              [{"option": "value of option"}])

## 7.15.9.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` 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` requires Command version 2 or later.

The following example uses HTML escape and normalzier is `NormalizeAuto`. It specifies the tags `<span class="keyword1">` and `</span>` of the keyword `groonga`, and the tags `<span class="keyword2">` and `</span>` of the keyword `mysql`.

Execution example:

    select Entries --output_columns 'highlight("Groonga is very fast fulltext search engine.", "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>", {"normalizers": "NormalizerAuto", "html_mode": true})' --command_version 2 --match_columns body --query "groonga"
    # [
    #   [
    #     0,
    #     1686037492.46897,
    #     0.0482330322265625
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight",
    #           null
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword1\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

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

`--query "groonga mysql"` matches to the first record’s body. `highight` surrounds the keywords `groonga` contained in the text with `<span class="keyword1">` and `</span>`, and the keywords `mysql` contained in the text with `<span class="keyword2">` and `</span>`.

Special characters such as `<` and `>` are escapsed as `&lt;` and `&gt;`.

You can specify string literal instead of column.

Execution example:

    select Entries --output_columns 'highlight("Groonga is very fast fulltext search engine.", "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>", {"normalizers": "NormalizerAuto", "html_mode": true})' --command_version 2 --match_columns body --query "groonga"
    # [
    #   [
    #     0,
    #     1686037814.127705,
    #     0.03028535842895508
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight",
    #           null
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword1\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

## 7.15.9.4. Parameters

There are multiple required parameters and multiple optional parameters.

### 7.15.9.4.1. `column`

Specifies a highlight target column.

### 7.15.9.4.2. `keywordN`

Specifies a keyword for tagging. You can specify multiple keywords.

### 7.15.9.4.3. `open_tagN`

Specifies a open tag. You can specify multiple open tags for each keywords.

### 7.15.9.4.4. `close_tagN`

Specifies a close tag. You can specify multiple close tags for each keywords.

### 7.15.9.4.5. `{"default_open_tag": "open_tag"}`

Specifies a open tag. You can not specify multiple open tags unlike `open_tagN` parameter.

### 7.15.9.4.6. `{"default_close_tag": "close_tag"}`

Specifies a close tag. You can not specify multiple close tags unlike `close_tagN` parameter.

### 7.15.9.4.7. `{"html_escape": true}` or `{"html_mode": true}`

New in version 13.0.2.

Specifies use or not use HTML escape. If it is `true` , use HTML escape. If it is `false` , not use HTML escape.

### 7.15.9.4.8. `{"normalizer": "Normalizerxxx"}`

Specifies a normalizer name.

### 7.15.9.4.9. `{"normalizers": "Normalizerxxx"}`

New in version 13.0.2.

Specifies a normalizer name. You can specify multiple normalizers.

This option is useful when combining NormalizerTable.

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

New 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.9.5. Return value

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

## 7.15.9.6. See also

- select

- logical_select

- highlight_html