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.