5.5.3. mroonga_highlight_html() — Mroonga vmrn_version documentation

本文へスキップ
`Ctrl`+`K`

# 5.5.3. `mroonga_highlight_html()`

Added in version 7.05.

## 5.5.3.1. 概要

`mroonga_highlight_html()` は対象のテキストの中の指定されたキーワードをハイライトします。各キーワードを `<span class="keyword">...</span>` で囲み、`<` や `>` といったHTMLの特殊文字をエスケープします。この関数の結果は、安全なHTMLとして使うことができます。

## 5.5.3.2. 構文

`mroonga_highlight_html()` には必須引数と省略可能引数とがあります。:

    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` はとても重要です。クエリーを使ってキーワードを抽出する場合に指定する必要があります。

`open_tag` と `close_tag` は省略可能です。ハイライトに使用するタグを指定することができます。

## 5.5.3.3. 使いかた

以下は'mroonga OR groonga'というクエリーによって、対象テキストの中の'mroonga'と'groonga'をハイライトする例です。 `AS query` を指定する必要があります。:

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

実行結果はこちらです。:

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

'mroonga'と'groonga'というキーワードで対象となるテキストのハイライトをするクエリーです。

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

実行結果はこちらです。:

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

## 5.5.3.4. 引数

### 5.5.3.4.1. 必須引数

必須引数が1つあります。

#### 5.5.3.4.1.1. `text`

ハイライトされるカラム名もしくは文字列が必要です。

### 5.5.3.4.2. 省略可能引数

いくつか省略可能な引数があります。

#### 5.5.3.4.2.1. `query`

詳細は Groongaのクエリー構文 を参照してください。

クエリーを使ってキーワードを抽出するには、以下のように `AS query` を指定する必要があります。:

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

#### 5.5.3.4.2.2. `keyword`

ハイライトする0個以上のキーワードを指定します。

#### 5.5.3.4.2.3. `open_tag`

ハイライトの開始タグを指定します。

このパラメーターを指定するには、以下のように `AS open_tag` を指定する必要があります。

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

デフォルト値は `<span class="keyword">` です。

#### 5.5.3.4.2.4. `close_tag`

ハイライトの終了タグを指定します。

このパラメーターを指定するには、以下のように `AS close_tag` を指定する必要があります。

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

デフォルト値は `</span>` です。

## 5.5.3.5. 返り値

ハイライトされたHTMLを返します。省略可能な引数が指定されない場合、`text` に含まれるHTMLの特殊文字 `<` や `>` をエスケープします。