1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
.. -*- rst -*-
Output format
=============
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.
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
]
]
]
``HEADER``
^^^^^^^^^^
``HEADER`` is an array. The content of ``HEADER`` has some patterns.
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.
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 :doc:`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``.
``BODY``
^^^^^^^^
``BODY`` content depends on the executed command. It may be omitted.
``BODY`` may be an error message on error case.
XML
---
TODO
TSV
---
TODO
See also
--------
* :doc:`return_code` describes about return code.
|
