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

- 日本語版はこちら

# 7.12.6. highlight_full

Caution

This feature is experimental. API will be changed.

## 7.12.6.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.12.6.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.12.6.3. Usage

Here are a schema definition and sample data to show usage.

Execution example:

    table_create Entries TABLE_NO_KEY
    # [[0,1407692435.35498,0.0364797115325928],true]
    column_create Entries body COLUMN_SCALAR ShortText
    # [[0,1407692435.39156,0.0256640911102295],true]
    table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    # [[0,1407692435.423,0.0274741649627686],true]
    column_create Terms document_index COLUMN_INDEX|WITH_POSITION Entries body
    # [[0,1407692435.45051,0.0534985065460205],true]
    load --table Entries
    [
    {"body": "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga."}
    ]
    # [[0,1407692435.50406,0.378907442092896],1]

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

`highlight_full` requires Groonga 4.0.5 or later.

`highlight_full` requires コマンドバージョン 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,
    #     1407695996.52987,
    #     0.00151872634887695
    #   ],
    #   [
    #     [
    #       [
    #         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,
    #     1407696157.1849,
    #     0.00164437294006348
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_full",
    #           "null"
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword1\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

## 7.12.6.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.12.6.4.1. `column`

It specifies a column of the table.

### 7.12.6.4.2. `normalizer_name`

It specifies a normalizer name.

### 7.12.6.4.3. `use_html_escape`

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

### 7.12.6.4.4. `keywordN`

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

### 7.12.6.4.5. `open_tagN`

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

### 7.12.6.4.6. `close_tagN`

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

## 7.12.6.5. Return value

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

## 7.12.6.6. See also

- select
- highlight_html