Skip to main content
`Ctrl`+`K`

# 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. 参考

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