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

- English

# 7.1.8. `groonga-suggest-httpd`

## 7.1.8.1. 概要

`groonga-suggest-httpd` は次の機能に対するHTTPインターフェイスを提供するプログラムです。

> - サジェスト を実行した結果を返す
> - 学習用にログを保存する

`groonga-suggest-httpd` は suggest コマンドのようなサジェスト機能を提供します。いくつかパラメーター名が異なることに注意してください。

## 7.1.8.2. 構文

`groonga-suggest-httpd` にはデータベースのパスを指定します。:

    groonga-suggest-httpd [options] DATABASE_PATH

## 7.1.8.3. 使い方

`groonga-suggest-httpd` を使う場合は1つ以上のデータセットを作る必要があります。データセットはテーブルとカラムの集まりです。これらのテーブル・カラムは groonga-suggest-create-dataset で作成できます。

ユーザーの入力からサジェスト用データを学習するには groonga-suggest-learner を使う必要があります。手動でサジェスト用データを作成する場合は groonga-suggest-learner を使う必要はありません。手動でサジェスト用データを作る方法については サジェスト とその関連ドキュメントを参照してください。

1つ以上のデータセットを作ったらHTTP経由で `groonga-suggest-httpd` を使えます。

つづくセクションでは次のことについて説明します。

> - データセットのセットアップ方法
> - groonga-suggest-learner と一緒に `groonga-suggest-httpd` を使う方法
> - サジェスト結果を取得するために `groonga-suggest-httpd` を使う方法

### 7.1.8.3.1. セットアップ

groonga-suggest-create-dataset でデータセットを作ります。

以下は `query` データセットを作る例です。

実行例:

    % groonga-suggest-create-dataset ${DB_PATH} query
    > plugin_register suggest/suggest
    false
    > table_create event_type TABLE_HASH_KEY ShortText
    true
    > table_create bigram TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    true
    > table_create kana TABLE_PAT_KEY ShortText --normalizer NormalizerAuto
    true
    > table_create item_query TABLE_PAT_KEY ShortText --default_tokenizer TokenDelimit --normalizer NormalizerAuto
    true
    > column_create bigram item_query_key COLUMN_INDEX|WITH_POSITION item_query _key
    true
    > column_create item_query kana COLUMN_VECTOR kana
    true
    > column_create kana item_query_kana COLUMN_INDEX item_query kana
    true
    > column_create item_query freq COLUMN_SCALAR Int32
    true
    > column_create item_query last COLUMN_SCALAR Time
    true
    > column_create item_query boost COLUMN_SCALAR Int32
    true
    > column_create item_query freq2 COLUMN_SCALAR Int32
    true
    > column_create item_query buzz COLUMN_SCALAR Int32
    true
    > table_create pair_query TABLE_HASH_KEY UInt64
    true
    > column_create pair_query pre COLUMN_SCALAR item_query
    true
    > column_create pair_query post COLUMN_SCALAR item_query
    true
    > column_create pair_query freq0 COLUMN_SCALAR Int32
    true
    > column_create pair_query freq1 COLUMN_SCALAR Int32
    true
    > column_create pair_query freq2 COLUMN_SCALAR Int32
    true
    > column_create item_query co COLUMN_INDEX pair_query pre
    true
    > table_create sequence_query TABLE_HASH_KEY ShortText
    true
    > table_create event_query TABLE_NO_KEY
    true
    > column_create sequence_query events COLUMN_VECTOR|RING_BUFFER event_query
    true
    > column_create event_query type COLUMN_SCALAR event_type
    true
    > column_create event_query time COLUMN_SCALAR Time
    true
    > column_create event_query item COLUMN_SCALAR item_query
    true
    > column_create event_query sequence COLUMN_SCALAR sequence_query
    true
    > table_create configuration TABLE_HASH_KEY ShortText
    true
    > column_create configuration weight COLUMN_SCALAR UInt32
    true
    > load --table configuration
    > [
    > {"_key": "query", "weight": 1}
    > ]
    1

groonga-suggest-create-dataset は実行したコマンドを出力します。新しいデータセット用にどんなテーブル・カラムを作ったかを確認できます。

### 7.1.8.3.2. `groonga-suggest-learner` を起動

学習したサジェストデータをすぐに使うかどうかを選択できます。

学習したサジェストデータをすぐに使う方法は2つあります。

> - `groonga-suggest-httpd` と groonga-suggest-learner のどちらも同じデータベースを使う
> - `groonga-suggest-httpd` が groonga-suggest-learner から学習したサジェストデータを受け取る

前者のケースでは、 `groonga-suggest-httpd` と groonga-suggest-learner を同じホスト上で実行しなければいけません。

後者のケースでは、 `groonga-suggest-httpd` と groonga-suggest-learner を違うホストで動かせます。

学習したサジェストデータをすぐに使う必要がないとき、 groonga-suggest-learner が使っているデータベースから `groonga-suggest-httpd` が使っているデータベースに学習したサジェストデータを主導で反映する必要があります。通常、こちらの使い方を推奨します。なぜなら学習したサジェストデータには悪意のあるユーザーが入力由来のゴミデータが含まれているかもしれないからです。

このドキュメントでは groonga-suggest-learner から学習したサジェストデータを受け取り、学習したサジェストデータをすぐに使います。 `groonga-suggest-httpd` と groonga-suggest-learner はどちらも同じホストで動かします。これは説明しやすいからです。

以下は groonga-suggest-learner を起動する例です。 `query` データセットがあるデータベースを指定します。このドキュメントでは `query` データセットを作る手順は省略します。

実行例:

    % groonga-suggest-learner --daemon ${DB_PATH}

`groonga-suggest-learner` プロセスは2つのエンドポイントを提供します。それぞれ `1234` 番ポートと `1235` 番ポートを使います。

> - `1234` 番ポート： `groogna-suggest-httpd` からユーザーの入力を受け付けるエンドポイント
> - `1235` 番ポート： `groogna-suggest-httpd` に学習したサジェストデータを送信するエンドポイント

### 7.1.8.3.3. `groonga-suggest-httpd` を起動

次の目的のため、 `groonga-suggest-httpd` を起動します。

> - ユーザーの入力からサジェストデータを学習するため
> - サジェスト結果をクライアントに提供するため

以下は groonga-suggest-learner と通信する `groonga-suggest-httpd` を起動する例です。

実行例:

    % groonga-suggest-httpd --send-endpoint 'tcp://127.0.0.1:1234' --receive-endpoint 'tcp://127.0.0.1:1235' --daemon ${DB_PATH}

`groonga-suggest-httpd` プロセスは `8080` 番ポートでHTTPリクエストを受け付けます。

リクエストをログファイルに保存したい場合は `--log-base-path` オプションを指定してください。

以下は各ログファイルに `log` というプレフィックスをつけて `logs` ディレクトリーに保存する例です。:

    % groonga-suggest-httpd --log-base-path logs/log ${DB_PATH}

`groonga-suggest-httpd` は `logYYYYmmddHHMMSS-00` という名前のログファイルを作成し、 `logs` ディレクトリー以下に保存します。

### 7.1.8.3.4. ユーザーの入力から学習

ユーザーの入力からサジェストデータを学習できます。

サジェストデータを学習するには次のパラメーターを指定する必要があります。

> - `i`: The ID of the user (You may use IP address of client)
> - `l` ：データセット名
> - `s` ：入力のタイムスタンプ。単位は秒。
> - `t` ：クエリーの種類。（省略可能。ユーザーの入力がサブミットされたときだけ `submit` を指定します。）
> - `q` ：ユーザーの入力

以下は `query` データセットで「Groonga」というユーザーの入力を学習するリクエスト例です。

    .. groonga-command
    .. include:: ../../example/reference/executables/groonga-suggest-httpd/learn.log
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=92619&q=G'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=93850&q=Gr'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94293&q=Gro'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94734&q=Groo'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95147&q=Grooon'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95553&q=Groonga'
    .. % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=Groonga'

入力中のデータに `t=submit` パラメーターをつけてはいけません。上の例では、ユーザーの入力を学習しているだけですが、ユーザーの入力を学習しながら同時に補完候補を取得することもできます。これは次のセクションで説明します。

サブミットされたデータには `t=submit` パラメーターをつけます。

### 7.1.8.3.5. サジェスト結果を使う

`groonga-suggest-httpd` からのサジェスト結果を使えます。

サジェスト結果を取得するには次のパラメーターを指定します。

> - `n` ：データセット名
> - `t` ：クエリーの種類（ `complete` 、 `correct` 、 `suggest` のどれか。複数指定も可。）
> - `q` ：ユーザーの入力

suggest のパラメーターを指定することもできます。

以下は 補完 結果を取得する例です。この結果は前のセクションで学習したデータを使って計算しています。 `frequency_threshold=1` パラメーターを使っているのはこれが例だからです。このパラメーターは1回以上出現した入力データも有効なデータとします。通常、プロダクション環境ではこのパラメーターを指定するべきではありません。ノイズが増える可能性が高いからです。

実行例:

    % curl 'http://localhost:8080/?n=query&t=complete&q=G&frequency_threshold=1'

補完用と学習用のどちらのパラメーターも指定することで補完と学習を組み合わせることができます。

実行例:

    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=96000&q=G&n=query&t=complete&frequency_threshold=1'

## 7.1.8.4. コマンドライン引数

### 7.1.8.4.1. 必須引数

必須の引数が1つあります。

#### 7.1.8.4.1.1. `DATABASE_PATH`

Groongaのデータベースのパスを指定します。このデータベースには1つ以上のデータセットを作っておいてください。各データセットは groonga-suggest-create-dataset で作ります。

### 7.1.8.4.2. 省略可能引数

`-p````,` `--port```

  HTTPサーバーのポート番号を指定します。

  デフォルトのポート番号は `8080` です。

`-t````,` `--n-threads```

  最大スレッド数を指定します。

  最大で128を指定できますが、パフォーマンスを出すためには最大でもCPUコア数を指定する方がよいです。

  デフォルトはコア数です。

`-s````,` `--send-endpoint```

  ユーザーの入力送信先になる groonga-suggest-learner のエンドポイントURIを指定します。

  フォーマットは `tcp://${HOST}:${PORT}` です。たとえば、 `tcp://192.168.0.1:2929` のように指定します。

  デフォルト値はありません。

`-r````,` `--receive-endpoint```

  groonga-suggest-learner が学習済みのサジェストデータを受信するために使用するURIを指定します。

  フォーマットは `tcp://${HOST}:${PORT}` です。たとえば、 `tcp://192.168.0.1:2929` のように指定します。

  デフォルト値はありません。

`-l````,` `--log-base-path```

  ログのパス名のプレフィックスを指定します。

  デフォルト値はありません。

`--n-lines-per-log-file```

  1つのログファイルの最大行数を指定します。

  デフォルトは `1000000` （100万行）です。

`-d````,` `--daemon```

  デーモン化する場合に指定します。

  デフォルトではデーモン化しません。

`--disable-max-fd-check```

  起動時の最大ファイルディスクリプター数のチェックを無効化する場合に指定します。

  デフォルトはチェックします。

## 7.1.8.5. GETの引数

`groonga-suggest-httpd` GETパラメーターを受け付けます。

必須の引数があります。どれが必須かはクエリーの種類に依存します。

クエリーの種類が `complete` 、 `correct` 、 `suggest` のどれかのときは、道のパラメーターは suggest にそのまま渡します。つまり、 suggest のパラメーターを使うことができます。

### 7.1.8.5.1. 必須引数

次のパラメーターを指定する必要があります。

キー | 説明 | 備考
--- | --- | ---
`q` | ユーザーの入力。UTF-8でエンコードされた文字列です。 |

### 7.1.8.5.2. 学習時に必須の引数

`--send-endpoint` を指定したときは次のパラメーターを指定しなければいけません。

キー | 説明 | 備考
--- | --- | ---
`s` | `1970-01-01T00:00:00Z` から経過時間。 | 単位はミリ秒。
`i` | 各ユーザーを識別するユニークなID。 | セッションID、IPアドレスなどを使うことができるでしょう。
`l` | 1つ以上の学習対象のデータセット名。複数のデータセットを指定する場合は `dataset1|dataset2|dataset3` のように区切り文字として `|` を使います。 | データセット名は groonga-suggest-create-dataset で指定した名前です。

### 7.1.8.5.3. サジェスト時に必須の引数

`t` パラメータに `complete` 、 `correct` 、 `suggest` のどれかを指定したときは次のパラメーターを指定する必要があります。

キー | 説明 | 備考
--- | --- | ---
`n` | サジェスト結果を計算するときに使うデータセット名。 | データセット名は groonga-suggest-create-dataset で指定した名前です。
`t` | クエリーの種類。 `complete` 、 `correct` 、 `suggest` のどれか。 | 複数の種類を指定することもできます。複数指定するときは `complete|correct` のように `|` で区切ってください。

### 7.1.8.5.4. 省略可能引数

いくつか省略可能な引数があります。

キー | 説明 | 備考
--- | --- | ---
`callback` | JSONPの関数名 |

### 7.1.8.5.5. 学習時に指定可能な引数

`--send-endpoint` オプションを指定したときに指定可能なパラメーターは次の通りです。

キー | 説明 | 備考
--- | --- | ---
`t` | クエリーの種類。 指定可能な値は `submit` だけです。 | ユーザーが `q` で指定した入力をサブミットしたときは `submit` を指定してください。 まだサブミットされていないユーザーの入力を指定するときは `submit` を指定しないでください。 `submit` を指定していないときに `t` に `complete` 、 `correct` 、 `suggest` のうち1つ以上を指定するとサジェスト結果を使えます。これらの `t` に指定する値については サジェスト時に必須の引数 を参照してください。

## 7.1.8.6. 戻り値

`groonga-suggest-httpd` のレスポンスは次のフォーマットになります。 suggest のボディ部分と同じです。:

    {
      TYPE1: [
        [CANDIDATE_1, SCORE_1],
        [CANDIDATE_2, SCORE_2],
        ...,
        [CANDIDATE_N, SCORE_N]
      ],
      TYPE2: [
        [CANDIDATE_1, SCORE_1],
        [CANDIDATE_2, SCORE_2],
        ...,
        [CANDIDATE_N, SCORE_N]
      ],
      ...
    }

`t` に `submit` を指定したときのレスポンスは次の通りです。:

    {}

### 7.1.8.6.1. `TYPE`

`complete` 、 `correct` 、 `suggest` のどれか。

### 7.1.8.6.2. `CANDIDATE_N`

UTF-8でエンコードされた候補文字列。

### 7.1.8.6.3. `SCORE_N`

候補のスコアー。

スコアーの降順でソートされた候補リスト。

## 7.1.8.7. 参考

> - suggest