コマンドは実行結果をJSONまたはMessagePack、XML、TSVのどれかで出力します。
JSONとMessagePackの出力は同じ構造になっています。XMLとTSVはそれぞれ独自の構造になっています。
JSONまたはMessagePackの利用を推奨します。XMLは目視で結果を確認する時に便利です。TSVは特殊な用途では有用です。通常はTSVを使う必要はありません。
このセクションではJSONとMessagePack形式を使った時のコマンド実行結果の構造を説明します。MessagePackはバイナリー形式なのでここでは構造を示すためにJSONを使います。バイナリー形式はドキュメントには向いていません。
JSON形式、MessagePack形式のときは以下のような構造になります:
English page[HEADER, BODY]
実行例:
[
[
0,
1337566253.89858,
0.000355720520019531
],
[
[
[
1
],
[
[
"_id",
"UInt32"
],
[
"_key",
"ShortText"
],
[
"content",
"Text"
],
[
"n_likes",
"UInt32"
]
],
[
2,
"Groonga",
"I started to use groonga. It's very fast!",
10
]
]
]
]
この例では、以下の部分が HEADER に相当します:
[
0,
1337566253.89858,
0.000355720520019531
]
BODY に相当する部分は以下です:
[
[
[
1
],
[
[
"_id",
"UInt32"
],
[
"_key",
"ShortText"
],
[
"content",
"Text"
],
[
"n_likes",
"UInt32"
]
],
[
2,
"Groonga",
"I started to use groonga. It's very fast!",
10
]
]
]
HEADER は配列です。 HEADER の内容にはいくつかのパターンがあります。
コマンドが成功した場合は HEADER には3つの要素があります:
[0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME]
最初の値は常に 0 です。
UNIX_TIME_WHEN_COMMAND_IS_STARTED はコマンドの実行が始まったときの時刻です。時刻は1970-01-01 00:00:00から経過した秒数で表現されています。 ELAPSED_TIME はコマンドの実行にかかった時間です。単位は秒です。 UNIX_TIME_WHEN_COMMAND_IS_STARTED も ELAPSED_TIME も浮動小数点数です。小数部分はナノ秒を表します。
エラーの場合、 HEADER には4個または5個の要素があります:
[
RETURN_CODE,
UNIX_TIME_WHEN_COMMAND_IS_STARTED,
ELAPSED_TIME,
ERROR_MESSAGE,
ERROR_LOCATION
]
ERROR_LOCATION は HEADER には含まれないかもしれませんが、他の4個の要素は常に含まれます。
RETURN_CODE は0ではない値です。リターンコードの詳細は リターンコード を見てください。
UNIX_TIME_WHEN_COMMAND_IS_STARTED と ELAPSED_TIME は成功した時と同じです。
ERROR_MESSAGE はエラーメッセージです。文字列です。
ERROR_LOCATION は存在しないことがあります。もし、エラーが発生した場所の情報を収集できていた場合は ERROR_LOCATION が含まれます。 ERROR_LOCATION は配列です。 ERROR_LOCATION は1個または2個の要素を含みます:
[
LOCATION_IN_GROONGA,
LOCATION_IN_INPUT
]
LOCATION_IN_GROONGA はgroonga内でエラーが発生したソースコードの場所です。この情報はgroonga開発者には役に立ちますが、ユーザーの役には立ちません。 LOCATION_IN_GROONGA は配列です。 LOCATION_IN_GROONGA には3個の要素があります:
[
FUNCTION_NAME,
SOURCE_FILE_NAME,
LINE_NUMBER
]
FUNCTION_NAME はエラーが発生した関数の名前です。
SOURCE_FILE_NAME はエラーが発生した箇所を含んだgroongaのソースコードのファイル名です。
LINE_NUMBER はエラーが発生した箇所の SOURCE_FILE_NAME での行番号です。
LOCATION_IN_INPUT は存在しないことがあります。 LOCATION_IN_INPUT は入力ファイルでエラーが発生した場所の情報を収集できたときに含まれます。入力ファイルは groonga コマンドのコマンドラインオプション --file で指定できます。 LOCATION_IN_GROONGA は配列です。 LOCATION_IN_GROONGA には3個の要素があります:
[
INPUT_FILE_NAME,
LINE_NUMBER,
LINE_CONTENT
]
INPUT_FILE_NAME はエラーが発生した入力ファイルのファイル名です。
LINE_NUMBER はエラーが発生した箇所の INPUT_FILE_NAME での行番号です。
LINE_CONTENT は INPUT_FILE_NAME 内の LINE_NUMBER 行目の内容です。
TODO
TODO