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

- 日本語

# 7.1.8. groonga-suggest-httpd

## 7.1.8.1. Summary

groonga-suggest-httpd is a program to provide interface which accepts HTTP request and returns suggestion dataset, then saves logs for learning. groonga-suggest-httpd behaves similar in point of view of suggestion functionality, but the name of parameter is different.

## 7.1.8.2. Synopsis

    groonga-suggest-httpd [options] database_path

## 7.1.8.3. Usage

### 7.1.8.3.1. Set up

First you need to set up database for suggestion.

Execution example:

    % groonga-suggest-create-dataset /tmp/groonga-databases/groonga-suggest-httpd query

### 7.1.8.3.2. Launch groonga-suggest-httpd

Execute groonga-suggest-httpd command:

Execution example:

    % groonga-suggest-httpd /tmp/groonga-databases/groonga-suggest-httpd

After executing above command, groonga-suggest-httpd accepts HTTP request on 8080 port.

If you just want to save requests into log file, use `-l` option.

Here is the example to save log files under `logs` directory with `log` prefix for each file.:

    % groonga-suggest-httpd -l logs/log /tmp/groonga-databases/groonga-suggest-httpd

Under `logs` directory, log files such as `logYYYYmmddHHMMSS-00` are created.

### 7.1.8.3.3. Request to groonga-suggest-httpd

Here is the sample requests to learn `groonga` for `query` dataset:

    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=92619&t=complete&q=g'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=93850&t=complete&q=gr'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94293&t=complete&q=gro'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=94734&t=complete&q=groo'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95147&t=complete&q=grooon'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95553&t=complete&q=groonga'
    % curl 'http://localhost:8080/?i=127.0.0.1&l=query&s=95959&t=submit&q=groonga

## 7.1.8.4. Options

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

  Specify http server port number. The default value is 8080.

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

  Specify number of threads. The default value is 8. This option accepts 128 as the max value, but use the number of CPU cores for performance.

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

  Specify endpoint for sender.

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

  Specify endpoint for receiver.

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

  Specify path prefix of log.

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

  Specify the number of lines in a log file. The default value is 1,000,000.

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

  Specify this option to daemonize.

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

  Specify this option to disable checking max fd on start.

## 7.1.8.5. Command line parameters

There is one required parameter - `database_path`.

### 7.1.8.5.1. `database_path`

Specifies the path to a Groonga database. This database must be created by groonga-suggest-create-dataset command because it executes required initialization for suggestion.

## 7.1.8.6. GET parameters

groonga-suggest-httpd accepts following GET parameters.

There are required parameters which depends on type of query.

### 7.1.8.6.1. Required parameters

Key | Description | Note
--- | --- | ---
q | UTF-8 encoded string which user fills in form |
t | The type of query. The value of type must be complete, correct, suggest or submit. It also accepts multiple type of query which is concatinated by `|`. Note that `submit` is invalid value when you specify multiple type of query. |

### 7.1.8.6.2. Required parameters for learning

Key | Description | Note
--- | --- | ---
s | Elapsed time from 0:00 January 1, 1970 | Note that you need specify the value of `s` in milliseconds
i | Unique ID to distinct user | Use session ID or IP address for example
l | Specify the name of dataset for learning. It also accepts multiple dataset name which is concatinated by `|` | Note that dataset name must be matched to following regular expression `[A-Za-z ][A-Za-z0-9 ]{0,15}`

### 7.1.8.6.3. Required parameters for suggestion

Key | Description | Note
--- | --- | ---
n | Specify the name of dataset for suggestion | This dataset name is used to calculate suggestion results

### 7.1.8.6.4. Optional parameter

Key | Description | Note
--- | --- | ---
callback | Specify the name of function if you prefer JSONP as response format | The name of function must be matched to reqular expression `[A-Za-z ][A-Za-z0-9 ]{0,15}`

## 7.1.8.7. Return value

`groonga-suggest-httpd` command returns following response in JSON or JSONP format.

In JSON format:

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

In JSONP format:

    FUNCTION({TYPE: [[CANDIDATE_1, SCORE_1], [CANDIDATE_2, SCORE_2], ... [CANDIDATE_N, SCORE_N]]})

`TYPE`

> One of `complete`, `correct` and `suggest`.

`CANDIDATE_N`

> The string of candidate (UTF-8).

`SCORE_N`

> The score.