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 は存在しないことがあります。もし、エラーが発生した場所の情報を収集できていた場合は 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 行目の内容です。
7.3.2.3. XML¶
TODO
7.3.2.4. TSV¶
TODO