7.15.9. highlight_html#

New in version 4.0.5.

7.15.9.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.9.2. Syntax#

This function has only one parameter:

highlight_html(text)

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 MySQL 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\">MySQL</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."
#       ]
#     ]
#   ]
# ]

7.15.9.4. Parameters#

This section describes all parameters.

7.15.9.4.1. Required parameters#

There is only one required parameter.

7.15.9.4.1.1. text#

The text to be highlighted in HTML.

7.15.9.4.2. Optional parameters#

There is no optional parameter.

7.15.9.5. Return value#

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

7.15.9.6. See also#