# groonga - オープンソースのカラムストア機能付き全文検索エンジン

- English

# 7.14.6. `highlight_full`

ご用心

この機能は実験的です。APIが変わる可能性があります。

## 7.14.6.1. 概要

`highlight_full` は対象テキストをタグ付けします。検索文字列をハイライトさせるために利用することができます。HTMLエスケープの有無、ノーマライザー名を指定することができ、キーワードごとにタグを変更することができます。

## 7.14.6.2. 構文

`highlight_full` には必須引数と省略可能引数とがあります:

    highlight_full(column, normalizer_name, use_html_escape,
                   keyword1, open_tag1, close_tag1,
                   ...
                   [keywordN, open_tagN, close_tagN])

## 7.14.6.3. 使い方

使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。

実行例:

    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_full` は select コマンドの `--output_columns` 内でのみ指定できます。

`highlight_full` を使うにはGroonga 4.0.5以降が必要です。

`highlight_full` を使うには コマンドバージョン 2以降を使う必要があります。

以下の例はHTMLエスケープを使用し、ノーマライザーに `NormalizerAuto` を指定しています。この例では キーワード `groonga` に `<span class="keyword1">` と `</span>` のタグを指定し、キーワード `mysql` に `<span class="keyword2">` と `</span>` のタグを指定しています。

実行例:

    select Entries --output_columns 'highlight_full(body, "NormalizerAuto", true, "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>")' --command_version 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_full",
    #           "null"
    #         ]
    #       ],
    #       [
    #         "Mroonga is a <span class=\"keyword2\">ＭｙＳＱＬ</span> storage engine based on <span class=\"keyword1\">Groonga</span>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <span class=\"keyword1\">Groonga</span>."
    #       ]
    #     ]
    #   ]
    # ]

キーワードとテキストは `NormalizerAuto` ノーマライザーで正規化されてタグ付けのためにスキャンされます。

`--query "groonga mysql"` は最初のレコードにマッチします。 `highlight_full` は、テキスト中に含まれるキーワード `groonga` を `<span class="keyword1">` と `</span>` で囲み、 キーワード `mysql` を `<span class="keyword2">` と `</span>` で囲みます。

`<` や `>` などの特殊文字は &lt; や &gt; にエスケープされています。

カラムの代わりに文字列リテラルを指定することもできます。

実行例:

    select Entries --output_columns 'highlight_full("Groonga is very fast fulltext search engine.", "NormalizerAuto", true, "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>")' --command_version 2 --match_columns body --query "groonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_full",
    #           "null"
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword1\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

## 7.14.6.4. 引数

必須引数は3つあります。 `column` と `normalizer_name` と `use_html_escape` です。省略可能引数は3つ以上あります。 `keywordN` と `open_tagN` と `end_tagN` です。

### 7.14.6.4.1. `column`

テーブルのカラムを指定します。

### 7.14.6.4.2. `normalizer_name`

ノーマライザー名を指定します。

### 7.14.6.4.3. `use_html_escape`

HTMLエスケープの有無を指定します。 `true` を指定すればHTMLエスケープされます。 `false` を指定すればHTMLエスケープされません。

### 7.14.6.4.4. `keywordN`

タグ付けするキーワードを指定します。3つの引数ごとに複数のキーワードを指定することができます。

### 7.14.6.4.5. `open_tagN`

開始タグを指定します。3つの引数ごとに複数の開始タグを指定することができます。

### 7.14.6.4.6. `close_tagN`

終了タグを指定します。3つの引数ごとに複数の終了タグを指定することができます。

## 7.14.6.5. 戻り値

`highlight_full` はタグ付の文字列もしくは null を返します。`highlight_full` は該当するキーワードがない場合に null を返します。

## 7.14.6.6. 参考

- select
- highlight_html