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 < and >.
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. <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>. <b>Rroonga</b> 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>. <b>Rroonga</b> 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.