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

- English

# 7.14.14. `snippet_html`

ご用心

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

## 7.14.14.1. 概要

`snippet_html` は対象テキスト中から検索キーワード周辺のテキスト（ `KWIC` 。 `KeyWord In Context` ）を抽出します。抽出されたテキストのことをスニペットと呼びます。スニペットはHTML中に埋め込みやすいように処理されています。 `<` や `>` などの特殊文字は `&lt;` や `&gt;` にエスケープされています。キーワードは `<span class="keyword">` と `</span>` で囲まれています。たとえば、 `I am a groonga user. <3` という対象テキストのキーワード `groonga` でのスニペットは `I am a <span class="keyword">groonga</span> user. &lt;3` となります。

## 7.14.14.2. 構文

`snippet_html` の引数は1つだけです:

    snippet_html(column)

`snippet_html` は内部にはたくさんのオプションがありますが、今はまだ指定できません。じきに指定できるようになる予定です。

## 7.14.14.3. 使い方

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

実行例:

    table_create Documents TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Documents content COLUMN_SCALAR Text
    # [[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 documents_content_index COLUMN_INDEX|WITH_POSITION Documents content
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    load --table Documents
    [
    ["content"],
    ["Groonga is a fast and accurate full text search engine based on inverted index. One of the characteristics of groonga is that a newly registered document instantly appears in search results. Also, groonga allows updates without read locks. These characteristics result in superior performance on real-time applications."],
    ["Groonga is also a column-oriented database management system (DBMS). Compared with well-known row-oriented systems, such as MySQL and PostgreSQL, column-oriented systems are more suited for aggregate queries. Due to this advantage, groonga can cover weakness of row-oriented systems."]
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 2]

`snippet_html` は select コマンドの `--output_columns` 内でのみ指定できます。

Groonga 2.0.9では `output_columns` 内での関数呼び出しはまだ実験的な機能なので、明示的に `--command_version 2` オプションを指定する必要があります。この機能はじきに有効になる予定です。

また、 `--query` と `--filter` オプションも指定する必要があります。（どちらか一方でも構いません。）これは、 `--query` と `--filter` オプションからキーワードを抽出しているためです。

以下の例は `--query "fast performance"` を使っています。この場合は、キーワードとして `fast` と `performance` を使います。

実行例:

    select Documents --output_columns "snippet_html(content)" --command_version 2 --match_columns content --query "fast performance"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "snippet_html",
    #           "null"
    #         ]
    #       ],
    #       [
    #         [
    #           "Groonga is a <span class=\"keyword\">fast</span> and accurate full text search engine based on inverted index. One of the characteristics of groonga is that a newly registered document instantly appears in search results. Also, gro",
    #           "onga allows updates without read locks. These characteristics result in superior <span class=\"keyword\">performance</span> on real-time applications."
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

`--query "fast performance"` は最初のレコードの内容にだけマッチします。 `snippet_html(content)` は、テキスト中からキーワード `fast` と `performance` の少なくともどちらか一方を含んでいるテキストの断片を抽出します。今回は2箇所抽出しています。そして、抽出したテキストの断片内にあるキーワードを `<span class="keyword">` と `</span>` で囲みます。

テキストの断片数は多くても3です。4つ以上のテキストの断片が抽出できるときは、最初の3つだけを使います。

テキストの断片の最大サイズは200バイトです。単位は文字数ではなくバイトです。挿入される `<span keyword="keyword">` と `</span>` のバイト数はこのサイズの中には含まれません。

テキストの断片の最大数とテキストの断片の最大サイズはカスタマイズできません。

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

実行例:

    select Documents --output_columns 'snippet_html("Groonga is very fast fulltext search engine.")' --command_version 2 --match_columns content --query "fast performance"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "snippet_html",
    #           "null"
    #         ]
    #       ],
    #       [
    #         [
    #           "Groonga is very <span class=\"keyword\">fast</span> fulltext search engine."
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

## 7.14.14.4. 戻り値

`snippet_html` は文字列の配列もしくは `null` を返します。 `snippet_html` は該当するスニペットがない場合に `null` を返します。

配列の要素がスニペットになります:

    [SNIPPET1, SNIPPET2, SNIPPET3]

スニペットには1つ以上のキーワードが含まれています。 `<span keyword="keyword">` と `</span>` を除いたスニペットの最大サイズは200byteです。単位は文字数ではなくてバイトです。

配列のサイズは0以上3以下です。最大サイズの3は、じきにカスタマイズできるようになる予定です。

## 7.14.14.5. TODO

- テキストの断片の最大数をカスタマイズできるようにする。

- テキストの断片最大サイズをカスタマイズできるようにする。

- キーワードをカスタマイズできるようにする。

- キーワードを囲むタグをカスタマイズできるようにする。

- 正規化の方法をカスタマイズできるようにする。

- オブジェクトリテラル形式でのオプション指定をサポートする。

## 7.14.14.6. 参考

- select