# groonga - An open-source fulltext search engine and column store.

- 日本語

# 7.14.7. `highlight_full`

Caution

This feature is experimental. API will be changed.

## 7.14.7.1. Summary

`highlight_full` tags target text. It can use to highlight the search keyword. It can specify use/not use HTML escape, the normalizer name and change the tag for each keyword.

## 7.14.7.2. Syntax

`highlight_full` has required parameter and optional parameter:

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

## 7.14.7.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 ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga."}
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 1]

`highlight_full` can be used in only `--output_columns` in select.

`highlight_full` requires Groonga 4.0.5 or later.

`highlight_full` requires Command version 2 or later.

The following example uses HTML escape and normalzier is `NormalizeAuto`. It specifies the tags `<span class="keyword1">` and `</span>` of the keyword `groonga`, and the tags `<span class="keyword2">` and `</span>` of the keyword `mysql`.

Execution example:

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

The text are scanned by the keywords for tagging after they are normalized by `NormalizerAuto` normalizer.

`--query "groonga mysql"` matches to the first record's body. `highight_full` surrounds the keywords `groonga` contained in the text with `<span class="keyword1">` and `</span>`, and the keywords `mysql` contained in the text with with `<span class="keyword2">` and `</span>`.

Special characters such as `<` and `>` are escapsed as `&lt;` and `&gt;`.

You can specify string literal instead of column.

Execution example:

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

There are three required parameters, `column`, `normalizer_name` and `use_html_escape`. There are three or over optional parameters, `keywordN`, `open_tagN` and `end_tagN`.

### 7.14.7.4.1. `column`

Specifies a column of the table.

### 7.14.7.4.2. `normalizer_name`

Specifies a normalizer name.

### 7.14.7.4.3. `use_html_escape`

Specifies use or not use HTML escape. If it is `true` , use HTML escape. If it is `false` , not use HTML escape.

### 7.14.7.4.4. `keywordN`

Specifies a keyword for tagging. You can specify multiple keywords for each three arguments.

### 7.14.7.4.5. `open_tagN`

Specifies a open tag. You can specify multiple open tags for each three arguments.

### 7.14.7.4.6. `close_tagN`

Specifies a close tag. You can specify multiple close tags for each three arguments.

## 7.14.7.5. Return value

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

## 7.14.7.6. See also

- select
- highlight_html