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 is the source location that error is occurred in groonga. It is useful for groonga developers but not useful for users. LOCATION_IN_GROONGA is an array. LOCATION_IN_GROONGA has three elements:

[
  FUNCTION_NAME,
  SOURCE_FILE_NAME,
  LINE_NUMBER
]

FUNCTION_NAME is the name of function that error is occurred.

SOURCE_FILE_NAME is the name of groonga's source file that error is occurred.

LINE_NUMBER is the line number of SOURCE_FILE_NAME that error is occurred.

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 is the input file name that error is occurred.

LINE_NUMBER is the line number of INPUT_FILE_NAME that error is occurred.

LINE_CONTENT is the content at LINE_NUMBER in INPUT_FILE_NAME.

7.3.2.2.2. BODY

BODY content depends on the executed command. It may be omitted.

BODY may be an error message on error case.

7.3.2.3. XML

TODO

7.3.2.4. TSV

TODO

7.3.2.5. 参考

• リターンコード はリターンコードについて説明しています。