7.14.8. highlight_html

New in version 4.0.5.

7.14.8.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.14.8.2. Syntax

This function has only one parameter:

highlight_html(text)

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

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.14.8.4. Parameters

This section describes all parameters.

7.14.8.4.1. Required parameters

There is only one required parameters.

7.14.8.4.1.1. text

The text to be highlighted in HTML.

7.14.8.4.2. Optional parameters

There is no optional parameter.

7.14.8.5. Return value

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

7.14.8.6. See also