7.15.9. highlight#

Added 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(body, "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>", {"normalizers": "NormalizerAuto", "html_mode": true})' --command_version 2
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "highlight",
#           null
#         ]
#       ],
#       [
#         "Mroonga is a <span class=\"keyword2\">ＭｙＳＱＬ</span> storage engine based on <span class=\"keyword1\">Groonga</span>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <span class=\"keyword1\">Groonga</span>."
#       ]
#     ]
#   ]
# ]

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,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         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}#

Added 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"}#

Added 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}#

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.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#