8.1. GQTP

GQTPはGroonga Query Transfer Protocolの頭文字です。GQTPはgroonga用の独自プロトコルです。

8.1.1. プロトコル

GQTPはステートフルなクライアント・サーバーモデルのプロトコルです。以下の流れが1つの処理単位です:

  • クライアントがリクエストを送る

  • サーバーがリクエストを受け取る

  • サーバーがリクエストを処理する

  • サーバーがレスポンスを返す

  • クライアントがレスポンスを受け取る

1つのセッション内で0個以上の処理単位を実行できます。

リクエストもレスポンスもGQTPヘッダーとボディから成ります。GQTPヘッダーは固定長のデータです。ボディは可変長サイズのデータです。ボディのサイズはGQTPヘッダーの中に入っています。GQTPではボディの中身については何も定義しません。

8.1.1.1. GQTPヘッダー

GQTPヘッダーは以下の符号なし整数値から成ります:

名前

サイズ

説明

protocol

1byte

プロトコルの種類。

query_type

1byte

ボディのコンテントタイプ。

key_length

2byte

未使用。

level

1byte

未使用。

flags

1byte

フラグ。

status

2byte

リターンコード。

size

4byte

ボディのサイズ。

opaque

4byte

未使用。

cas

8byte

未使用。

ヘッダーのすべての値はネットワークバイトオーダーを使っています。

以下のセクションではそれぞれのヘッダーの値で利用可能な値について説明します。

GQTPヘッダーは全部で24byteになります。

8.1.1.1.1. protocol

リクエストのGQTPヘッダーでもレスポンスのGQTPヘッダーでも、この値は常に 0xc7 になります。

8.1.1.1.2. query_type

この値は以下のいずれかの値です:

名前

値

説明

NONE

0

自由形式。

TSV

1

値をタブで区切った形式。

JSON

2

JSON。

XML

3

XML。

MSGPACK

4

MessagePack。

リクエストGQTPヘッダーでは使われません。

レスポンスGQTPヘッダーで使われます。ボディは指定した形式にします。

8.1.1.1.3. flags

この値は以下の値をビット単位ORしたものになります:

名前

値

説明

MORE

0x01

まだデータがあります。

TAIL

0x02

これ以上データはありません。

HEAD

0x04

未使用。

QUIET

0x08

レスポンスを出力しません。

QUIT

0x10

終了します。

MORE あるいは TAIL フラグは必ず指定しないといけません。

MORE フラグを使うときは QUIET フラグも使うべきです。リクエストが途中のときはレスポンスを出力する必要がないからです。

セッションを終了するときは QUIT フラグを使ってください。

8.1.1.1.4. status

利用可能な値です。将来的に新しいステータスが追加される可能性があります。

  • 0: SUCCESS

  • 1: END_OF_DATA

  • 65535: UNKNOWN_ERROR

  • 65534: OPERATION_NOT_PERMITTED

  • 65533: NO_SUCH_FILE_OR_DIRECTORY

  • 65532: NO_SUCH_PROCESS

  • 65531: INTERRUPTED_FUNCTION_CALL

  • 65530: INPUT_OUTPUT_ERROR

  • 65529: NO_SUCH_DEVICE_OR_ADDRESS

  • 65528: ARG_LIST_TOO_LONG

  • 65527: EXEC_FORMAT_ERROR

  • 65526: BAD_FILE_DESCRIPTOR

  • 65525: NO_CHILD_PROCESSES

  • 65524: RESOURCE_TEMPORARILY_UNAVAILABLE

  • 65523: NOT_ENOUGH_SPACE

  • 65522: PERMISSION_DENIED

  • 65521: BAD_ADDRESS

  • 65520: RESOURCE_BUSY

  • 65519: FILE_EXISTS

  • 65518: IMPROPER_LINK

  • 65517: NO_SUCH_DEVICE

  • 65516: NOT_A_DIRECTORY

  • 65515: IS_A_DIRECTORY

  • 65514: INVALID_ARGUMENT

  • 65513: TOO_MANY_OPEN_FILES_IN_SYSTEM

  • 65512: TOO_MANY_OPEN_FILES

  • 65511: INAPPROPRIATE_I_O_CONTROL_OPERATION

  • 65510: FILE_TOO_LARGE

  • 65509: NO_SPACE_LEFT_ON_DEVICE

  • 65508: INVALID_SEEK

  • 65507: READ_ONLY_FILE_SYSTEM

  • 65506: TOO_MANY_LINKS

  • 65505: BROKEN_PIPE

  • 65504: DOMAIN_ERROR

  • 65503: RESULT_TOO_LARGE

  • 65502: RESOURCE_DEADLOCK_AVOIDED

  • 65501: NO_MEMORY_AVAILABLE

  • 65500: FILENAME_TOO_LONG

  • 65499: NO_LOCKS_AVAILABLE

  • 65498: FUNCTION_NOT_IMPLEMENTED

  • 65497: DIRECTORY_NOT_EMPTY

  • 65496: ILLEGAL_BYTE_SEQUENCE

  • 65495: SOCKET_NOT_INITIALIZED

  • 65494: OPERATION_WOULD_BLOCK

  • 65493: ADDRESS_IS_NOT_AVAILABLE

  • 65492: NETWORK_IS_DOWN

  • 65491: NO_BUFFER

  • 65490: SOCKET_IS_ALREADY_CONNECTED

  • 65489: SOCKET_IS_NOT_CONNECTED

  • 65488: SOCKET_IS_ALREADY_SHUTDOWNED

  • 65487: OPERATION_TIMEOUT

  • 65486: CONNECTION_REFUSED

  • 65485: RANGE_ERROR

  • 65484: TOKENIZER_ERROR

  • 65483: FILE_CORRUPT

  • 65482: INVALID_FORMAT

  • 65481: OBJECT_CORRUPT

  • 65480: TOO_MANY_SYMBOLIC_LINKS

  • 65479: NOT_SOCKET

  • 65478: OPERATION_NOT_SUPPORTED

  • 65477: ADDRESS_IS_IN_USE

  • 65476: ZLIB_ERROR

  • 65475: LZO_ERROR

  • 65474: STACK_OVER_FLOW

  • 65473: SYNTAX_ERROR

  • 65472: RETRY_MAX

  • 65471: INCOMPATIBLE_FILE_FORMAT

  • 65470: UPDATE_NOT_ALLOWED

  • 65469: TOO_SMALL_OFFSET

  • 65468: TOO_LARGE_OFFSET

  • 65467: TOO_SMALL_LIMIT

  • 65466: CAS_ERROR

  • 65465: UNSUPPORTED_COMMAND_VERSION

8.1.1.1.5. size

ボディのサイズです。ボディの最大サイズは4GiBです。これは size が4byteの符号なし整数だからです。4GiB以上のサイズのデータを送りたい場合は MORE フラグを使ってください。

8.1.2. 例

8.1.2.1. GQTPサーバの起動

Groongaには、専用のプロトコルであるGQTPが存在します。GQTPを用いることにより、データベースへとリモートアクセスすることができます。以下の書式はGQTPサーバの起動方法を示しています。

Form:

groonga [-p PORT_NUMBER] -s DB_PATH

-s オプションはGroongaをサーバとして起動するためのオプションです。DB_PATHには既存のデータベースのパスを指定します。 -p オプションとその引数により、サーバのポート番号を指定することができます。ポート番号を省略した場合は10043が使用されます。

以下のコマンドにより、デフォルトのポート番号で待ち受けるサーバを起動することができます。サーバは指定されたデータベースへの操作を受け付けます。

実行例:

% groonga -s /tmp/groonga-databases/introduction.db
Ctrl-c
%

8.1.2.2. GQTPデーモンの起動

GQTPサーバはデーモンとして起動することができます。オプションとして、 -s の代わりに -d を与えてください。

Form:

groonga [-p PORT_NUMBER] -d DB_PATH

Groongaをデーモンとして起動したときは、デーモンのプロセスIDが表示されます。以下の例では、12345というプロセスIDが表示されています。サーバとして起動した場合と同様に、指定されたデータベースへの操作を受け付けます。

実行例:

% groonga -d /tmp/groonga-databases/introduction.db
12345
%

8.1.2.3. GQTPサーバへの接続

GQTPサーバに接続するクライアントは、以下のように起動します。

Form:

groonga [-p PORT_NUMBER] -c [HOST_NAME_OR_IP_ADDRESS]

上記のコマンドによって起動されたクライアントは、サーバとの接続に成功すると対話モードに入ります。HOST_NAME_OR_IP_ADDRESSにはサーバのホスト名もしくはIPアドレスを指定します。HOST_NAME_OR_IP_ADDRESSが省略されたときは"localhost"をサーバのホスト名として採用します。また、 -p オプションとその引数により、サーバのポート番号を指定することができます。ポート番号を省略した場合は10043が使用されます。

実行例:

% groonga -c
status
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "uptime": 10,
#     "max_command_version": 3,
#     "start_time": 1514346074,
#     "cache_hit_rate": 0.0,
#     "version": "7.0.9",
#     "alloc_count": 13655,
#     "command_version": 1,
#     "starttime": 1514346074,
#     "default_command_version": 1,
#     "n_queries": 13
#   }
# ]
> ctrl-d
%

対話モードでは、標準入力からコマンドを読み込んで順次実行します。

8.1.2.4. GQTPサーバの終了

GQTPサーバを終了する安全は方法は、クライアントを起動して shutdown を発行することです。

実行例:

% groonga -c
> shutdown
%

8.1.3. 参照

前へ

8. 仕様

次へ

8.2. 検索