5.5.3. mroonga_highlight_html()

New in version 7.05.

5.5.3.1. Summary

mroonga_highlight_html() highlights the specified keywords in target text. It surrounds each keyword with <span class="keyword">...</span> and special characters in HTML such as < and > are escaped. You can use the result as is safely in HTML.

5.5.3.2. Syntax

mroonga_highlight_html() has required parameter and optional parameter:

mroonga_highlight_html(text, query AS query)
mroonga_highlight_html(text, query AS query, open_tag AS open_tag)
mroonga_highlight_html(text, query AS query, close_tag AS close_tag)
mroonga_highlight_html(text, query AS query, open_tag AS open_tag, close_tag AS close_tag)

mroonga_highlight_html(text, keyword1, ..., keywordN)
mroonga_highlight_html(text, keyword1, ..., keywordN, open_tag AS open_tag)
mroonga_highlight_html(text, keyword1, ..., keywordN, open_tag AS close_tag)
mroonga_highlight_html(text, keyword1, ..., keywordN, open_tag AS open_tag, close_tag AS close_tag)

AS query is very important. You must specify it to extract keywords from query.

open_tag and close_tag are optional. You can specify a tag for highlighting.

5.5.3.3. Usage

Here is a sample to highlight keywords “mroonga” and “groonga” in target text by query “mroonga OR groonga”. You must specify AS query:

SELECT mroonga_highlight_html('Mroonga is the Groonga based storage engine.',
                              'mroonga OR groonga' AS query) AS highlighted;

Here is the result of the execution example:

+--------------------------------------------------------------------------------------------------------+
| highlighted                                                                                            |
+--------------------------------------------------------------------------------------------------------+
| <span class="keyword">Mroonga</span> is the <span class="keyword">Groonga</span> based storage engine. |
+--------------------------------------------------------------------------------------------------------+
1 row in set (0.00 sec)

Here is a sample to highlight keywords “mroonga” and “groonga” in target text by keywords “mroonga” and “groonga”:

SELECT mroonga_highlight_html('Mroonga is the Groonga based storage engine.',
                              'mroonga', 'groonga') AS highlighted;

Here is the result of the execution example:

+--------------------------------------------------------------------------------------------------------+
| highlighted                                                                                            |
+--------------------------------------------------------------------------------------------------------+
| <span class="keyword">Mroonga</span> is the <span class="keyword">Groonga</span> based storage engine. |
+--------------------------------------------------------------------------------------------------------+

5.5.3.4. Parameters

5.5.3.4.1. Required parameters

There is one required parameter.

5.5.3.4.1.1. text

The column name of string or string value to be highlighted.

5.5.3.4.2. Optional parameters

There are some optional parameters.

5.5.3.4.2.1. query

Specify query in Groonga’s query syntax.

You must specify AS query to extract keywords from query like the following:

SELECT mroonga_highlight_html('...', 'mroonga OR groonga' AS query);

5.5.3.4.2.2. keyword

Specify 0 or more keywords to be highlighted.

5.5.3.4.2.3. open_tag

Specify an open tag for highlighting.

You must specify AS open_tag to specify this parameter like the following.

SELECT mroonga_highlight_html('Mroonga is the Groonga based storage engine.', 'groonga',
                              '<span class="my-class">' AS open_tag) AS highlighted;

-- +----------------------------------------------------------------------------+
-- | highlighted                                                                |
-- +----------------------------------------------------------------------------+
-- | Mroonga is the <span class="my-class">Groonga</span> based storage engine. |
-- +----------------------------------------------------------------------------+

The default value is <span class="keyword">.

5.5.3.4.2.4. close_tag

Specify a close tag for highlighting.

You must specify AS close_tag to specify this parameter like the following.

SELECT mroonga_highlight_html('Mroonga is the Groonga based storage engine.', 'groonga',
                              '<mark>' AS open_tag, '</mark>' AS close_tag) AS highlighted;

-- +-----------------------------------------------------------+
-- | highlighted                                               |
-- +-----------------------------------------------------------+
-- | Mroonga is the <mark>Groonga</mark> based storage engine. |
-- +-----------------------------------------------------------+

The default value is </span>.

5.5.3.5. Return value

It returns highlighted HTML. If optional parameter is not given, it only escapes special characters in HTML such as <, > in text.