7.1.3. groonga 実行ファイル

7.1.3.1. 概要

groonga 実行ファイルは以下の機能を提供します。:

• 全文検索サーバー

• 全文検索シェル

• Groonga全文検索サーバーのクライアント

Groongaはライブラリーとして使えます。Groongaをライブラリーとして使う場合、C、C++などの言語でプログラムを書く必要があります。ライブラリーとして使う使い方はアプリケーションに全文検索機能を組み込む場合に便利です。しかし、全文検索サーバーや全文検索シェルほどは使いやすい使い方ではありません。

全文検索機能を使うために groonga 実行ファイルを使うことができます。

Groongaを試したいときは全文検索シェルの使い方が便利です。サーバーもクライアントも必要ありません。ターミナルが1つあれば十分です。次のようにしてGroongaを試すことができます。:

% groonga -n db
> status
[[0,1429687763.70845,0.000115633010864258],{"alloc_count":195,...}]
> quit
%

全文検索機能を持ったアプリケーションを作る場合は全文検索サーバーとして使う使い方が便利です。RDBMS（リレーショナル・データベース管理システム）のようにGroongaをサーバーとして使うことができます。クライアント・サーバーモデルはよくあるアーキテクチャーです。

Groonga全文検索サーバーのクライアントとして使う使い方はあまり使いません。

7.1.3.2. 構文

groonga 実行ファイルには以下の4つのモードがあります。

• スタンドアローンモード

• サーバーモード

• デーモンモード

• クライアントモード

これらのモードは共通のオプションを持ちます。これらの共通のオプションについては後のセクションで説明します。

7.1.3.2.1. スタンドアローンモード

In standalone mode, groonga executable file runs one or more Groonga コマンド against a local Groonga database.

Here is the syntax to run shell that executes Groonga command against temporary database:

groonga [options]

Here is the syntax to create a new database and run shell that executes Groonga command against the new database:

groonga [options] -n DB_PATH

Here is the syntax to run shell that executes Groonga command against existing database:

groonga [options] DB_PATH

Here is the syntax to run Groonga command against existing database and exit:

groonga [options] DB_PATH COMMAND [command arguments]

7.1.3.2.2. サーバーモード

In server mode, groonga executable file runs as a server. The server accepts connections from other processes at local machine or remote machine and executes received Groonga コマンド against a local Groonga database.

You can choose one protocol from HTTP and GQTP. Normally, HTTP is suitable but GQTP is the default protocol. This section describes only about HTTP protocol usage.

In server mode, groonga executable file runs in the foreground. If you want to run Groonga server in the background, see デーモンモード.

Here is the syntax to run Groonga server with temporary database:

groonga [options] --protocol http -s

Here is the syntax to create a new database and run Groonga server with the new database:

groonga [options] --protocol http -s -n DB_PATH

Here is the syntax to run Groonga server with existing database:

groonga [options] --protocol http -s DB_PATH

7.1.3.2.3. デーモンモード

In daemon mode, groonga executable file runs as a daemon. Daemon is similar to server but it runs in the background. See サーバーモード about server.

Here is the syntax to run Groonga daemon with temporary database:

groonga [options] --protocol http -d

Here is the syntax to create a new database and run Groonga daemon with the new database:

groonga [options] --protocol http -d -n DB_PATH

Here is the syntax to run Groonga daemon with existing database:

groonga [options] --protocol http -d DB_PATH

--pid-path option will be useful for daemon mode.

7.1.3.2.4. クライアントモード

In client mode, groonga executable file runs as a client for GQTP protocol Groonga server. Its usage is similar to スタンドアローンモード. You can run shell and execute one command. You need to specify server address instead of local database.

HTTPを使っているGroongaサーバーのクライアントとして groonga 実行ファイルを使うことはできないことに注意してください。

Here is the syntax to run shell that executes Groonga command against Groonga server that is running at 192.168.0.1:10043:

groonga [options] -c --port 10043 192.168.0.1

Here is the syntax to run Groonga command against Groonga server that is running at 192.168.0.1:10043 and exit:

groonga [options] -c --port 10043 192.168.0.1 COMMAND [command arguments]

7.1.3.3. オプション

-n

新しいデータベースを作成します。

-c

Executes groonga command in client mode.

-s

Executes groonga command in server mode. Use "Ctrl+C" to stop the groonga process.

-d

Executes groonga command in daemon mode. In contrast to server mode, groonga command forks in daemon mode. For example, to stop local daemon process, use "curl http://127.0.0.1:10041/d/shutdown".

-e, --encoding <encoding>

Specifies encoding which is used for Groonga database. This option is effective when you create new Groonga database. This parameter specifies one of the following values: none, euc, utf8, sjis, latin or koi8r.

-l, --log-level <log level>

ログレベルを指定します。ログレベルはログレベル名または整数値です。利用可能なログレベルは以下の通りです。

ログレベル	名前	整数値
なし	none	0
緊急	E, emerge, emergency のどれか	1
アラート	A, alert のどれか	2
危機的	C, crit, critical のどれか	3
エラー	e, error のどれか	4
警告	w, warn, warning のどれか	5
通知	n, notice のどれか	6
情報	i, info のどれか	7
デバッグ	d, debug のどれか	8
ダンプ	-, dump のどれか	9

-a, --address <ip/hostname>

バージョン 1.2.2 で非推奨: Use --bind-address instead.

--bind-address <ip/hostname>

Added in version 1.2.2.

サーバモードかデーモンモードで実行するとき、listenするアドレスを指定します。(デフォルトは hostname の返すホスト名)

-p, --port <port number>

クライアント、サーバ、またはデーモンモードで使用するTCPポート番号。 (クライアントモードのデフォルトは10043番、サーバ、またはデーモンモードのデフォルトは、HTTPの場合、10041番、GQTPの場合、10043番)

-i, --server-id <ip/hostname>

サーバモードかデーモンモードで実行するとき、サーバのIDとなるアドレスを指定します。(デフォルトは`hostname`の返すホスト名)

-h, --help

ヘルプメッセージを出力します。

--document-root <path>

httpサーバとしてgroongaを使用する場合に静的ページを格納するディレクトリを指定します。

デフォルトでは、データベースを管理するための汎用的なページに対応するファイルが/usr/share/groonga/admin_html以下にインストールされます。このディレクトリをdocument-rootオプションの値に指定して起動した場合、ウェブブラウザでhttp://hostname:port/index.htmlにアクセスすると、ウェブベースのデータベース管理ツールを使用できます。

--protocol <protocol>

http,gqtpのいずれかを指定します。(デフォルトはgqtp)

--log-path <path>

ログを出力するファイルのパスを指定します。(デフォルトは/var/log/groonga/groonga.logです)

--log-flags <log flags>

Added in version 8.1.1.

ログフラグを指定します。デフォルト値は time|+message です。

フラグの前に + をつけると現在のフラグにこのフラグを追加します。たとえば、 +process_id は現在のフラグに process_id フラグを追加します。

フラグの前に - をつけると現在のフラグからこのフラグを削除します。たとえば、 -time は現在のフラグから time フラグを削除します。

フラグの前になにもつけないと現在のフラグを指定したフラグで置き換えます。たとえば、 time|message は message` と同じです。なぜなら最初の ``time フラグは次の message フラグで置き換えられるからです。

| でフラグを区切ることで、複数のログフラグを指定できます。

利用可能なフラグは次のとおりです。

名前	説明
none	ログに何も出力しません。
time	タイムスタンプをログに出力します。
message	メッセージをログに出力します。
location	プロセスIDとログを出力した場所の情報（ファイル名・行数・関数名）をログに出力します。
process_id	プロセスIDをログに出力します。
pid	このフラグは process_id の別名です。
thread_id	スレッドIDをログに出力します。
context_id	Added in version 14.1.1. コンテキストIDをログに出力します。 コンテキストIDは クエリーログ にも出力されます。そのため、このフラグを使うと プロセスログ と クエリーログ にある同一コンテキストのログを関連付けやすくなります。
all	このフラグは、 none と default フラグ以外の全てのフラグを指定します。
default	time|+message と同じです。

--log-rotate-threshold-size <threshold>

Added in version 5.0.3.

ログローテーションの閾値を指定します。ログファイルのサイズが閾値に指定した値以上になると、ローテートされます。（デフォルトは0（無効）です）

--query-log-path <path>

クエリーログを出力するファイルのパスを指定します。(デフォルトでは出力されません)

--query-log-rotate-threshold-size <threshold>

Added in version 5.0.3.

クエリーログのローテーションの閾値を指定します。クエリーログファイルのサイズが閾値に指定した値以上になると、ローテートされます。（デフォルトは0（無効）です）

-t, --max-threads <max threasd>

最大で利用するスレッド数を指定します。(デフォルトはマシンのCPUコア数と同じ数です)

--pid-path <path>

PIDを保存するパスを指定します。(デフォルトでは保存しません)

--config-path <path>

設定ファイルのパスを指定します。設定ファイルは以下のようなフォーマットになります。:

# '#'以降はコメント。
; ';'以降もコメント。

# 'キー = 値'でオプションを指定。
pid-path = /var/run/groonga.pid

# '='の前後の空白はは無視される。↓は↑と同じ意味。
pid-path=/var/run/groonga.pid

# 'キー'は'--XXX'スタイルのオプション名と同じものが使える。
# 例えば、'--pid-path'に対応するキーは'pid-path'。
# ただし、キーが'config-path'のオプションは無視される。

--cache-limit <limit>

キャッシュ数の最大値を指定します。(デフォルトは100です)

--default-match-escalation-threshold <threshold>

検索の挙動をエスカレーションする閾値を指定します。(デフォルトは0です)

--default-n-workers <n>

Added in version 14.0.7.

Groongaプロセスのデフォルトのワーカー数を指定します。例として、select の n_workers のデフォルト値として使用されます。

デフォルト値は 0 です。

--default-request-timeout <timeout>

デフォルトのリクエストタイムアウトを指定します。単位は秒です。

0.1 のように小数で指定することで1秒未満のタイムアウトを設定できます。 0.1 は100ミリ秒のタイムアウトという意味です。

0 未満の値を指定するとデフォルトでリクエストタイムアウトは無効になります。

デフォルト値は 0 です。

参考

リクエストタイムアウト

--cache-base-path <path>

Added in version 7.0.2.

キャッシュの保存先のベースとなるパスを指定します。これを指定すると永続キャッシュ機能が有効になります。

永続キャッシュ機能を使うと次のメリットがあります。

• groonga プロセスが再起動した後もキャッシュを再利用できます。再起動する毎にキャッシュをウォームアップする必要はありません。

• 複数の groonga プロセス間でキャッシュを共有できます。

このベースとなるパスはメモリーファイルシステム上のパスを指定するべきです。ディスク上にベースとなるパスを指定するとキャッシュが遅くなります。これでは意味がありません。

デフォルト値はありません。これは永続キャッシュは無効だということです。代わりにメモリーキャッシュが使われます。

永続キャッシュはメモリーキャッシュよりも少し遅いです。通常、この差によるパフォーマンスの影響は軽微です。

7.1.3.4. コマンドライン引数

dest

使用するデータベースのパス名を指定します。

クライアントモードの場合は接続先のホスト名とポート番号を指定します(デフォルト値は'localhost:10043')。ポート番号を指定しない場合には、10043が指定されたものとします。

command [args]

スタンドアロンおよびクライアントモードの場合は、実行するコマンドとその引数をコマンドライン引数に指定できます。コマンドライン引数にcommandを与えなかった場合は、標準入力から一行ずつEOFに達するまでコマンド文字列を読み取り、順次実行します。

7.1.3.5. コマンド

groongaコマンドを通してデータベースを操作する命令をコマンドと呼びます。コマンドは主にC言語で記述され、groongaプロセスにロードすることによって使用できるようになります。 それぞれのコマンドは一意な名前と、0個以上の引数を持ちます。

引数は以下の2種類の方法のいずれかで指定することができます。:

形式1: コマンド名 値1 値2,..

形式2: コマンド名 --引数名1 値1 --引数名2 値2,..

形式1でコマンドを実行する場合は、定義された順番で値を指定しなければならず、途中の引数の値を省略することはできません。形式2でコマンドを実行する場合は、「--引数名」のように引数の名前を明示しなければならない代わりに、任意の順番で引数を指定することが可能で、途中の引数の指定を省略することもできます。

標準入力からコマンド文字列を与える場合は、コマンド名と引数名と値は、空白( )で区切ります。空白や、記号「"'()」のうちいずれかを含む値を指定したい場合は、シングルクォート(')かダブルクォート(")で値を囲みます。値として指定する文字列の中では、改行文字は'n'に置き換えて指定します。また、引用符に使用した文字を値の中で指定する場合には、その文字の前にバックスラッシュ('') を指定します。バックスラッシュ文字自身を値として指定する場合には、その前にバックスラッシュを指定します。

'\'文字で継続行であることを明示してコマンドリストを記述することができます。

table_create --name Terms \
             --flags TABLE_PAT_KEY \
             --key_type ShortText \
             --default_tokenizer TokenBigram

7.1.3.6. 組み込みコマンド

以下のコマンドは組み込みコマンドとして予め定義されています。

status

groongaプロセスの状態を表示します。

table_list

DBに定義されているテーブルのリストを表示します。

column_list

テーブルに定義されているカラムのリストを表示します。

table_create

DBにテーブルを追加します。

column_create

テーブルにカラムを追加します。

table_remove

DBに定義されているテーブルを削除します。

column_remove

テーブルに定義されているカラムを削除します。

load

テーブルにレコードを挿入します。

select

テーブルに含まれるレコードを検索して表示します。

define_selector

検索条件をカスタマイズした新たな検索コマンドを定義します。

quit

データベースとのセッションを終了します。

shutdown

サーバ(デーモン)プロセスを停止します。

log_level

ログ出力レベルを設定します。

log_put

ログ出力を行います。

clearlock

ロックを解除します。

7.1.3.7. 使い方

新しいデータベースを作成します。:

% groonga -n /tmp/hoge.db quit
%

作成済みのデータベースにテーブルを定義します。:

% groonga /tmp/hoge.db table_create Table 0 ShortText
[[0]]
%

サーバを起動します。:

% groonga -d /tmp/hoge.db
%

httpサーバとして起動します。:

% groonga -d -p 80 --protocol http --document-root /usr/share/groonga/admin_html /tmp/hoge.db
%

サーバに接続し、テーブル一覧を表示します。:

% groonga -c localhost table_list
[[0],[["id","name","path","flags","domain"],[256,"Table","/tmp/hoge.db.0000100",49152,14]]]
%