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
#   ],
#   {
#     "alloc_count": 29,
#     "starttime": 1696558618,
#     "start_time": 1696558618,
#     "uptime": 0,
#     "version": "2.9.1",
#     "n_queries": 0,
#     "cache_hit_rate": 0.0,
#     "command_version": 1,
#     "default_command_version": 1,
#     "max_command_version": 3,
#     "n_jobs": 0,
#     "features": {
#       "nfkc": true,
#       "mecab": true,
#       "message_pack": true,
#       "mruby": true,
#       "onigmo": true,
#       "zlib": true,
#       "lz4": true,
#       "zstandard": true,
#       "kqueue": false,
#       "epoll": true,
#       "poll": false,
#       "rapidjson": false,
#       "apache_arrow": true,
#       "xxhash": true,
#       "blosc": true,
#       "bfloat16": true,
#       "h3": true,
#       "simdjson": true,
#       "llama.cpp": true,
#       "back_trace": true,
#       "reference_count": false
#     },
#     "apache_arrow": {
#       "version_major": 2,
#       "version_minor": 9,
#       "version_patch": 1,
#       "version": "2.9.1"
#     },
#     "memory_map_size": 2929,
#     "n_workers": 0,
#     "default_n_workers": 0,
#     "os": "Linux",
#     "cpu": "x86_64"
#   }
# ]
> ctrl-d
$

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

8.1.2.4. GQTPサーバの終了#

shutdown でGQTPサーバーを終了できます。

$ groonga -c
> shutdown
$

8.1. GQTP#

8.1.1. プロトコル#

8.1.1.1. GQTPヘッダー#

8.1.1.1.1. protocol#

8.1.1.1.2. query_type#

8.1.1.1.3. flags#

8.1.1.1.4. status#

8.1.1.1.5. size#

8.1.2. 例#

8.1.2.1. GQTPサーバの起動#

8.1.2.2. GQTPデーモンの起動#

8.1.2.3. GQTPサーバへの接続#

8.1.2.4. GQTPサーバの終了#

8.1.3. 参照#

8.1.1.1.1. `protocol`#

8.1.1.1.2. `query_type`#

8.1.1.1.3. `flags`#

8.1.1.1.4. `status`#

8.1.1.1.5. `size`#