Skip to main content
`Ctrl`+`K`

# 7.3.2. Output format

## 7.3.2.1. Summary

Commands output their result as JSON, MessagePack, XML or TSV format.

JSON and MessagePack output have the same structure. XML and TSV are their original structure.

JSON or MessagePack is recommend format. XML is useful for visual result check. TSV is just for special use. Normally you doesn’t need to use TSV.

## 7.3.2.2. JSON and MessagePack

This secsion describes the structure of command result on JSON and MessagePack format. JSON is used to show structure because MessagePack is binary format. Binary format isn’t proper for documenataion.

JSON and MessagePack uses the following structure:

    [HEADER, BODY]

For example:

    [
      [
        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
          ]
        ]
      ]
    ]

In the example, the following part is `HEADER`:

    [
      0,
      1337566253.89858,
      0.000355720520019531
    ]

The following part is `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` is an array. The content of `HEADER` has some patterns.

#### 7.3.2.2.1.1. Success case

`HEADER` has three elements on success:

    [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME]

The first element is always `0`.

`UNIX_TIME_WHEN_COMMAND_IS_STARTED` is the number of seconds since 1970-01-01 00:00:00 UTC when the command is started processing. `ELAPSED_TIME` is the elapsed time for processing the command in seconds. Both `UNIX_TIME_WHEN_COMMAND_IS_STARTED` and `ELAPSED_TIME` are float value. The precision of them are nanosecond.

#### 7.3.2.2.1.2. Error case

`HEADER` has four or five elements on error:

    [
      RETURN_CODE,
      UNIX_TIME_WHEN_COMMAND_IS_STARTED,
      ELAPSED_TIME,
      ERROR_MESSAGE,
      ERROR_LOCATION
    ]

`ERROR_LOCATION` may not be included in `HEADER` but other four elements are always included.

`RETURN_CODE` is non 0 value. See Return code about available return codes.

`UNIX_TIME_WHEN_COMMAND_IS_STARTED` and `ELAPSED_TIME` are the same as success case.

`ERROR_MESSAGE` is an error message in string.

`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. See also

- Return code describes about return code.