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

7.1.5. groonga-httpd

7.1.5.1. 概要

groonga-httpdはGroongaサーバーとHTTPプロトコルで通信するプログラムです。 機能的には、 groonga HTTPサーバー と同じです。 groonga HTTPサーバー はHTTPサーバーとしては最小限の機能しか持ちませんが、groonga-httpdは nginx を組み込むことでnginxが準拠しているHTTPの仕様と機能をすべて利用できます。

groonga-httpdにはHTML + JavaScriptで実装された管理ツールが標準で付属しています。ウェブブラウザでhttp://hostname:port/にアクセスすると、管理ツールを利用できます。

7.1.5.2. 書式

groonga-httpd [nginx options]

7.1.5.3. 使い方

7.1.5.3.1. 設定をする

まずは、データベースを指定するためにgroonga-httpdの設定ファイルを編集する必要があります。次のように/etc/groonga/httpd/groonga-httpd.confを編集して groonga_database ディレクティブを有効にしてます。

# Match this to the file owner of groonga database files if groonga-httpd is
# run as root.
#user groonga;
...
http {
  ...
  # Don't change the location; currently only /d/ is supported.
  location /d/ {
    groonga on; # <= This means to turn on groonga-httpd.

    # Specify an actual database and enable this.
    groonga_database /var/lib/groonga/db/db;
  }
  ...
}

次に、groonga-httpdを実行してください。すぐにターミナルに制御が戻ってきます。これはgroonga-httpdはデフォルトでデーモンプロセスになるからです。

% groonga-httpd

7.1.5.3.2. クエリーを実行する

動作を確認するため、簡単なクエリー( status )をリクエストしてみます。

実行例:

% curl http://localhost:10041/d/status
[
  [
    0,
    1337566253.89858,
    0.000355720520019531
  ],
  {
    "uptime": 0,
    "max_command_version": 2,
    "n_queries": 0,
    "cache_hit_rate": 0.0,
    "version": "4.0.1",
    "alloc_count": 161,
    "command_version": 1,
    "starttime": 1395806036,
    "default_command_version": 1
  }
]

7.1.5.3.3. Loading data by POST

The feature of groonga-httpd in contrast to groonga is supporting POST method.

You can load data by POST JSON data.

Here is an example curl command line that loads two users alice and bob to Users table:

% curl --data-binary '[{"_key": "alice"}, {"_key": "bob"}]' -H "Content-Type: application/json" "http://localhost:10041/d/load?table=Users"

If you loads users from JSON file, prepare JSON file like this:

[
{"_key": "alice"},
{"_key": "bob"}
]

Then specify JSON file in curl command line:

% curl -X POST 'http://localhost:10041/d/load?table=Users' -H 'Content-Type: application/json' -d @users.json

7.1.5.3.4. 管理ツールを使う

補足ですが、 http://localhost:10041/ にアクセスすると管理ツールを利用できます。

7.1.5.3.5. 終了する

最後に、次のコマンドで動作中のgroonga-httpdデーモンを終了できます。

% groonga-httpd -s stop

7.1.5.4. 設定ディレクティブ

このセクションでは重要なディレクティブのみ説明します。重要なディレクティブとはgroonga-http特有のディレクティブと性能に関するディレクティブです。

以下のディレクティブはgroonga-httpdの設定ファイル中で使用することができます。デフォルトでは、設定ファイルは/etc/groonga/httpd/groonga-httpd.confに置かれています。

7.1.5.4.1. groonga-httpd特有のディレクティブ

以下のディレクティブはnginxが提供しているものではなく、groonga-httpd関連の設定をするためにgroonga-httpdが提供しているディレクティブです。

7.1.5.4.1.1. groonga

書式:

groonga on | off;
Default
groonga off;
Context
location

この location ブロックでGroongaを使うかどうかを指定します。デフォルトは off です。Groongaを使うためには on を指定してください。

例:

location /d/ {
  groonga on;  # Enables groonga under /d/... path
}

location /d/ {
  groonga off; # Disables groonga under /d/... path
}

7.1.5.4.1.2. groonga_database

書式:

groonga_database /path/to/groonga/database;
Default
groonga_database /usr/local/var/lib/groonga/db/db;
Context
http, server, location

Groongaデータベースのパスを指定します。このディレクティブは必須です。

7.1.5.4.1.3. groonga_database_auto_create

書式:

groonga_database_auto_create on | off;
Default
groonga_database_auto_create on;
Context
http, server, location

Groongaのデータベースを自動で作成するかどうかを指定します。もし、この値が ongroonga_database に指定したGroongaのデータベースが存在しない場合は自動でGroongaのデータベースを作成します。Groongaのデータベースが存在している場合は何もしません。

もし、親ディレクトリが存在しな場合は再帰的に親ディレクトリも作成します。

デフォルト値は on です。通常、この値を変更する必要はありません。

7.1.5.4.1.4. groonga_base_path

書式:

groonga_base_path /d/;
Default

location の名前と同じ値。

Context
location

URIのベースパスを指定します。Groongaは command を実行するために /d/command?parameter1=value1&... というパスを使います。groonga-httpdでもこのパスの形式を使いますが、groonga-httpdは /other-prefix/command?parameter1=value1&... というように /d/ ではなく別のプレフィックスを使った形式もサポートしています。この別の形式もサポートするために、groonga-httpdはリクエストURIの先頭からベースパスを削除し、先頭に /d/ を追加します。このパスの変換をすることにより、ユーザーはプレフィックスをカスタムできるようになりますが、Groongaは常に /d/command?parameter1=value1&... という形式で処理できます。

通常、このディレクティブを使う必要はありません。このディレクティブはコマンド毎に設定をしたい場合に使います。

以下は shutdown コマンドに認証をかける設定例です。:

groonga_database /var/lib/groonga/db/db;

location /d/shutdown {
  groonga on;
  # groonga_base_path is needed.
  # Because /d/shutdown is handled as the base path.
  # Without this configuration, /d/shutdown/shutdown path is required
  # to run shutdown command.
  groonga_base_path /d/;
  auth_basic           "manager is required!";
  auth_basic_user_file "/etc/managers.htpasswd";
}

location /d/ {
  groonga on;
  # groonga_base_path doesn't needed.
  # Because location name is the base path.
}

7.1.5.4.1.5. groonga_log_path

書式:

groonga_log_path path | off;
Default
/var/log/groonga/httpd/groonga.log
Context
http, server, location

Groongaのログ保存先を httpserver もしくは location ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga.log です。ログを無効にするには off を指定します。

例:

location /d/ {
  groonga on;
  # You can disable log for groonga.
  groonga_log_path off;
}

7.1.5.4.1.6. groonga_log_level

書式:

groonga_log_level none | emergency | alert | ciritical | error | warning | notice | info | debug | dump;
Default
notice
Context
http, server, location

Groongaのログレベルを httpserver もしくは location ブロックで指定します。デフォルトは notice です。 none を指定することでログを無効にできます。

例:

location /d/ {
  groonga on;
  # You can customize log level for groonga.
  groonga_log_level notice;
}

7.1.5.4.1.7. groonga_query_log_path

書式:

groonga_query_log_path path | off;
Default
/var/log/groonga/httpd/groonga-query.log
Context
http, server, location

Groongaのクエリーログの保存先を httpserver もしくは location ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga-query.log です。ログを無効にするには off を指定します。

例:

location /d/ {
  groonga on;
  # You can disable query log for groonga.
  groonga_query_log_path off;
}

クエリーログは以下のようなケースで有用です:

  • スロークエリーを見つける。

  • デバッグ。

groonga-query-log パッケージ でクエリーログを解析できます。このパッケージは有用なツールを提供しています。

例えば、クエリーログを解析するツールがあります。これを使えば、スロークエリーを見つけることができます。クエリーログ内のすべてのクエリーを再生するツールもあります。これを使えば、新しいGroongaをプロダクション環境にデプロイする前に網羅的にテストすることができます。

7.1.5.5. 利用可能なnginxモジュール

全てのHTTPの標準モジュールが利用可能です。PCRE(Perl Compatible Regular Expressions)がない場合はHttpRewriteModuleは無効になります。標準モジュールの一覧は、 http://wiki.nginx.org/Modules を参照してください。