7.3.2. 出力形式¶
7.3.2.1. 概要¶
コマンドは実行結果をJSONまたはMessagePack、XML、TSVのどれかで出力します。
JSONとMessagePackの出力は同じ構造になっています。XMLとTSVはそれぞれ独自の構造になっています。
JSONまたはMessagePackの利用を推奨します。XMLは目視で結果を確認する時に便利です。TSVは特殊な用途では有用です。通常はTSVを使う必要はありません。
7.3.2.2. JSONとMessagePack¶
このセクションではJSONとMessagePack形式を使った時のコマンド実行結果の構造を説明します。MessagePackはバイナリー形式なのでここでは構造を示すためにJSONを使います。バイナリー形式はドキュメントには向いていません。
JSON形式、MessagePack形式のときは以下のような構造になります:
[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
]
]
]
7.3.2.2.1. HEADER¶
HEADER は配列です。 HEADER の内容にはいくつかのパターンがあります。
7.3.2.2.1.1. 成功した場合¶
コマンドが成功した場合は 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 も浮動小数点数です。小数部分はナノ秒を表します。
7.3.2.2.1.2. エラーの場合¶
エラーの場合、 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 is optional. If error location is collected,
ERROR_LOCATION is included. ERROR_LOCATION is an
array. ERROR_LOCATION has one or two elements:
[
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 is optional. LOCATION_IN_INPUT is included
when the location that error is occurred in input file is
collected. Input file can be specified by --file command line
option for groonga command. LOCATION_IN_INPUT is an
array. LOCATION_IN_INPUT has three elements:
[
INPUT_FILE_NAME,
LINE_NUMBER,
LINE_CONTENT
]
INPUT_FILE_NAME はエラーが発生した入力ファイルのファイル名です。
LINE_NUMBER はエラーが発生した箇所の INPUT_FILE_NAME での行番号です。
LINE_CONTENT は INPUT_FILE_NAME 内の LINE_NUMBER 行目の内容です。
7.3.2.2.2. BODY¶
BODY の内容は実行したコマンドに依存します。 BODY がないこともあります。
エラーが発生した時に、 BODY にエラーメッセージが入っていることもあります。
7.3.2.3. XML¶
TODO
7.3.2.4. TSV¶
TODO
7.3.2.5. 参考¶
リターンコード はリターンコードについて説明しています。