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

# 7.15.9. `highlight`

Added in version 6.0.0.

## 7.15.9.1. 概要

`highlight` は対象テキストをタグ付けします。検索文字列をハイライトするのに使えます。ノーマライザー名やキーワード毎にタグを変更したり、HTMLエスケープの有無を指定できます。

## 7.15.9.2. 構文

`highlight` 必須の引数とオプションの引数を持ちます。:

    highlight(column,
              keyword1, open_tag1, close_tag1,
              ...
              [keywordN, open_tagN, close_tagN],
              [{"option": "value of option"}])

## 7.15.9.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]

10.0.6より前のバージョンでは、 `highlight` は select の `--output_columns` 内でのみ指定できますが、 10.0.6より前のバージョンでは以降は logical_select `--output_columns` 内でも使用できます。

`highlight` は コマンドバージョン 2 以降で使えます。

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

実行例:

    select Entries --output_columns 'highlight(body, "Groonga", "<span class=\\"keyword1\\">", "</span>", "mysql", "<span class=\\"keyword2\\">", "</span>", {"normalizers": "NormalizerAuto", "html_mode": true})' --command_version 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight",
    #           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` は、キーワード `groonga` を含むテキストを `<span class="keyword1">` と `</span>` で囲い、キーワード `mysql` を含むテキストを `<span class="keyword2">` と `</span>` で囲います。

`<` や `>` のような特殊文字は `&lt;` や `&gt;` としてエスケープされます。

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

実行例:

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

## 7.15.9.4. 引数

`highlight` は、複数の必須の引数と複数のオプションの引数を持ちます。

### 7.15.9.4.1. `column`

ハイライト対象のカラムを指定します。

### 7.15.9.4.2. `keywordN`

タグ付けをするキーワードを指定します。複数のキーワードを指定できます。

### 7.15.9.4.3. `open_tagN`

開始タグを指定します。複数の開始タグをキーワードごとに指定できます。

### 7.15.9.4.4. `close_tagN`

終了タグを指定します。複数の終了タグをキーワードごとに指定できます。

### 7.15.9.4.5. `{"default_open_tag": "open_tag"}`

開始タグを指定します。 `open_tagN` と異なり、複数の開始タグは指定できません。

### 7.15.9.4.6. `{"default_close_tag": "close_tag"}`

開始タグを指定します。 `open_tagN` と異なり、複数の開始タグは指定できません。

### 7.15.9.4.7. `{"html_escape": true}` or `{"html_mode": true}`

Added in version 13.0.2.

HTMLエスケープの使用有無を指定します。このパラメータが `true` の場合、HTMLエスケープを使います。このパラメータが `false` の場合、HTMLエスケープを使いません。

### 7.15.9.4.8. `{"normalizer": "Normalizerxxx"}`

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

### 7.15.9.4.9. `{"normalizers": "Normalizerxxx"}`

Added in version 13.0.2.

ノーマライザー名を指定します。複数のノーマライザーを指定できます。

このオプションは、 NormalizerTable と組み合わせるときに便利です。

### 7.15.9.4.10. `{"sequential_class_tag_mode": true}`

Added in version 13.0.2.

`sequential_class_tag_mode` のデフォルト値は `false` です。`sequential_class_tag_mode` が `true` の場合、それぞれのキーワードで異なるスタイル(例えば、背景色)を使えます。

`sequential_class_tag_mode` が `true` の場合、classタグは今の所、 `<mark class="keyword-%d">/<mark>` となります。

## 7.15.9.5. 戻り値

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

## 7.15.9.6. 参考

- select

- logical_select

- highlight_html