8.1. GQTP — Groonga v16.1.0ドキュメント

本文へスキップ
`Ctrl`+`K`

# 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.3. 参照

- groonga 実行ファイル

- GQTP