root / doc / design-query2.rst @ 7fa310f6
History | View | Annotate | Download (12.8 kB)
1 | e5a246df | Michael Hanselmann | ====================== |
---|---|---|---|
2 | e5a246df | Michael Hanselmann | Query version 2 design |
3 | e5a246df | Michael Hanselmann | ====================== |
4 | e5a246df | Michael Hanselmann | |
5 | e5a246df | Michael Hanselmann | .. contents:: :depth: 4 |
6 | e5a246df | Michael Hanselmann | .. highlight:: python |
7 | e5a246df | Michael Hanselmann | |
8 | e5a246df | Michael Hanselmann | Current state and shortcomings |
9 | e5a246df | Michael Hanselmann | ============================== |
10 | e5a246df | Michael Hanselmann | |
11 | e5a246df | Michael Hanselmann | Queries are used to retrieve information about the cluster, e.g. a list |
12 | e5a246df | Michael Hanselmann | of instances or nodes. For historical reasons they use a simple data |
13 | e5a246df | Michael Hanselmann | structure for their result. The client submits the fields it would like |
14 | e5a246df | Michael Hanselmann | to receive and the query returns a list for each item (instance, node, |
15 | e5a246df | Michael Hanselmann | etc.) available. Each item consists of another list representing the |
16 | e5a246df | Michael Hanselmann | fields' values. |
17 | e5a246df | Michael Hanselmann | |
18 | e5a246df | Michael Hanselmann | This data structure has a few drawbacks. It can't associate a status |
19 | e5a246df | Michael Hanselmann | (e.g. “node offline”) with fields as using special values can lead to |
20 | e5a246df | Michael Hanselmann | ambiguities. Additionally it can't mark fields as “not found” as the |
21 | e5a246df | Michael Hanselmann | list of returned columns must match the fields requested. |
22 | e5a246df | Michael Hanselmann | |
23 | e5a246df | Michael Hanselmann | Example:: |
24 | e5a246df | Michael Hanselmann | |
25 | e5a246df | Michael Hanselmann | >>> cli.GetClient().QueryNodes([], ["name", "pip", "mfree"], False) |
26 | e5a246df | Michael Hanselmann | [ |
27 | e5a246df | Michael Hanselmann | ['node1.example.com', '192.0.2.18', 14800], |
28 | e5a246df | Michael Hanselmann | ['node2.example.com', '192.0.2.19', 31280] |
29 | e5a246df | Michael Hanselmann | ] |
30 | e5a246df | Michael Hanselmann | |
31 | e5a246df | Michael Hanselmann | There is no way for clients to determine the list of possible fields, |
32 | e5a246df | Michael Hanselmann | meaning they have to be hardcoded. Selecting unknown fields raises |
33 | e5a246df | Michael Hanselmann | an exception:: |
34 | e5a246df | Michael Hanselmann | |
35 | e5a246df | Michael Hanselmann | >>> cli.GetClient().QueryNodes([], ["name", "UnknownField"], False) |
36 | e5a246df | Michael Hanselmann | ganeti.errors.OpPrereqError: (u'Unknown output fields selected: UnknownField', u'wrong_input') |
37 | e5a246df | Michael Hanselmann | |
38 | e5a246df | Michael Hanselmann | The client must also know each fields' kind, that is whether a field is |
39 | e5a246df | Michael Hanselmann | numeric, boolean, describes a storage size, etc. Centralizing this |
40 | e5a246df | Michael Hanselmann | information in one place, the master daemon, is desirable. |
41 | e5a246df | Michael Hanselmann | |
42 | e5a246df | Michael Hanselmann | |
43 | e5a246df | Michael Hanselmann | Proposed changes |
44 | e5a246df | Michael Hanselmann | ---------------- |
45 | e5a246df | Michael Hanselmann | |
46 | e5a246df | Michael Hanselmann | The current query result format can not be changed as it's being used in |
47 | e5a246df | Michael Hanselmann | various places. Changing the format from one Ganeti version to another |
48 | e5a246df | Michael Hanselmann | would cause too much disruption. For this reason the ability to |
49 | e5a246df | Michael Hanselmann | explicitly request a new result format must be added while the old |
50 | e5a246df | Michael Hanselmann | format stays the default. |
51 | e5a246df | Michael Hanselmann | |
52 | e5a246df | Michael Hanselmann | The implementation of query filters is planned for the future. To avoid |
53 | e5a246df | Michael Hanselmann | having to change the calls again, a (hopefully) future-compatible |
54 | e5a246df | Michael Hanselmann | interface will be implemented now. |
55 | e5a246df | Michael Hanselmann | |
56 | e5a246df | Michael Hanselmann | In Python code, the objects described below will be implemented using |
57 | e5a246df | Michael Hanselmann | subclasses of ``objects.ConfigObject``, providing existing facilities |
58 | e5a246df | Michael Hanselmann | for de-/serializing. |
59 | e5a246df | Michael Hanselmann | |
60 | 9189c902 | Michael Hanselmann | Regular expressions |
61 | 9189c902 | Michael Hanselmann | +++++++++++++++++++ |
62 | 9189c902 | Michael Hanselmann | |
63 | 9189c902 | Michael Hanselmann | As it turned out, only very few fields for instances used regular |
64 | 9189c902 | Michael Hanselmann | expressions, all of which can easily be turned into static field names. |
65 | 9189c902 | Michael Hanselmann | Therefore their use in field names is dropped. Reasons: |
66 | 9189c902 | Michael Hanselmann | |
67 | 9189c902 | Michael Hanselmann | - When regexps are used and a field name is not listed as a simple |
68 | 9189c902 | Michael Hanselmann | string in the field dictionary, all keys in the field dictionary have |
69 | 9189c902 | Michael Hanselmann | to be checked whether they're a regular expression object and if so, |
70 | 9189c902 | Michael Hanselmann | matched (see ``utils.FindMatch``). |
71 | 9189c902 | Michael Hanselmann | - Code becomes simpler. There would be no need anymore to care about |
72 | 9189c902 | Michael Hanselmann | regular expressions as field names—they'd all be simple strings, even |
73 | 9189c902 | Michael Hanselmann | if there are many more. The list of field names would be static once |
74 | 9189c902 | Michael Hanselmann | built at module-load time. |
75 | 9189c902 | Michael Hanselmann | - There's the issue of formatting titles for the clients. Should it be |
76 | 9189c902 | Michael Hanselmann | done in the server? In the client? The field definition's title would |
77 | 9189c902 | Michael Hanselmann | contain backreferences to the regexp groups in the field name |
78 | 9189c902 | Michael Hanselmann | (``re.MatchObject.expand`` can be used). With just strings, the field |
79 | 9189c902 | Michael Hanselmann | definitions can be passed directly to the client. They're static. |
80 | 9189c902 | Michael Hanselmann | - Only a side note: In the memory consumed for 1'000 |
81 | 9189c902 | Michael Hanselmann | ``_sre.SRE_Pattern`` objects (as returned by ``re.compile`` for an |
82 | 9189c902 | Michael Hanselmann | expression with one group) one can easily store 10'000 strings of the |
83 | 9189c902 | Michael Hanselmann | same length (the regexp objects keep the expression string around, so |
84 | 9189c902 | Michael Hanselmann | compiling the expression always uses more memory). |
85 | 9189c902 | Michael Hanselmann | |
86 | 9189c902 | Michael Hanselmann | |
87 | 9189c902 | Michael Hanselmann | .. _item-types: |
88 | 9189c902 | Michael Hanselmann | |
89 | 9189c902 | Michael Hanselmann | Item types |
90 | 9189c902 | Michael Hanselmann | ++++++++++ |
91 | 9189c902 | Michael Hanselmann | |
92 | 9189c902 | Michael Hanselmann | The proposal is to implement this new interface for the following |
93 | 9189c902 | Michael Hanselmann | items: |
94 | 9189c902 | Michael Hanselmann | |
95 | 9189c902 | Michael Hanselmann | ``instance`` |
96 | 9189c902 | Michael Hanselmann | Instances |
97 | 9189c902 | Michael Hanselmann | ``node`` |
98 | 9189c902 | Michael Hanselmann | Nodes |
99 | 9189c902 | Michael Hanselmann | ``job`` |
100 | 9189c902 | Michael Hanselmann | Jobs |
101 | 9189c902 | Michael Hanselmann | ``lock`` |
102 | 9189c902 | Michael Hanselmann | Locks |
103 | be3a4b14 | Michael Hanselmann | ``os`` |
104 | be3a4b14 | Michael Hanselmann | Operating systems |
105 | 9189c902 | Michael Hanselmann | |
106 | 9189c902 | Michael Hanselmann | .. _data-query: |
107 | 9189c902 | Michael Hanselmann | |
108 | 9189c902 | Michael Hanselmann | Data query |
109 | 9189c902 | Michael Hanselmann | ++++++++++ |
110 | 9189c902 | Michael Hanselmann | |
111 | 9189c902 | Michael Hanselmann | .. _data-query-request: |
112 | 9189c902 | Michael Hanselmann | |
113 | 9189c902 | Michael Hanselmann | Request |
114 | 9189c902 | Michael Hanselmann | ^^^^^^^ |
115 | 9189c902 | Michael Hanselmann | |
116 | 9189c902 | Michael Hanselmann | The request is a dictionary with the following entries: |
117 | 9189c902 | Michael Hanselmann | |
118 | 46aae796 | Michael Hanselmann | ``what`` (string, required) |
119 | 9189c902 | Michael Hanselmann | An :ref:`item type <item-types>`. |
120 | 9189c902 | Michael Hanselmann | ``fields`` (list of strings, required) |
121 | 9189c902 | Michael Hanselmann | List of names of fields to return. Example:: |
122 | 9189c902 | Michael Hanselmann | |
123 | 9189c902 | Michael Hanselmann | ["name", "mem", "nic0.ip", "disk0.size", "disk1.size"] |
124 | 9189c902 | Michael Hanselmann | |
125 | 9189c902 | Michael Hanselmann | ``filter`` (optional) |
126 | e5a246df | Michael Hanselmann | This will be used to filter queries. In this implementation only names |
127 | e5a246df | Michael Hanselmann | can be filtered to replace the previous ``names`` parameter to |
128 | e5a246df | Michael Hanselmann | queries. An empty filter (``None``) will return all items. To retrieve |
129 | e5a246df | Michael Hanselmann | specific names, the filter must be specified as follows, with the |
130 | e5a246df | Michael Hanselmann | inner part repeated for each name:: |
131 | e5a246df | Michael Hanselmann | |
132 | e5a246df | Michael Hanselmann | ["|", ["=", "name", "node1"], ["=", "name", "node2"], …] |
133 | e5a246df | Michael Hanselmann | |
134 | e5a246df | Michael Hanselmann | Filters consist of S-expressions (``["operator", <operants…>]``) and |
135 | e5a246df | Michael Hanselmann | extensions will be made in the future to allow for more operators and |
136 | e5a246df | Michael Hanselmann | fields. Such extensions might include a Python-style "in" operator, |
137 | e5a246df | Michael Hanselmann | but for simplicity only "=" is supported in this implementation. |
138 | e5a246df | Michael Hanselmann | |
139 | e5a246df | Michael Hanselmann | To reiterate: Filters for this implementation must consist of exactly |
140 | e5a246df | Michael Hanselmann | one OR expression (``["|", …]``) and one or more name equality filters |
141 | e5a246df | Michael Hanselmann | (``["=", "name", "…"]``). |
142 | e5a246df | Michael Hanselmann | |
143 | e5a246df | Michael Hanselmann | Support for synchronous queries, currently available in the interface |
144 | e5a246df | Michael Hanselmann | but disabled in the master daemon, will be dropped. Direct calls to |
145 | e5a246df | Michael Hanselmann | opcodes have to be used instead. |
146 | e5a246df | Michael Hanselmann | |
147 | 9189c902 | Michael Hanselmann | .. _data-query-response: |
148 | e5a246df | Michael Hanselmann | |
149 | 9189c902 | Michael Hanselmann | Response |
150 | 9189c902 | Michael Hanselmann | ^^^^^^^^ |
151 | e5a246df | Michael Hanselmann | |
152 | e5a246df | Michael Hanselmann | The result is a dictionary with the following entries: |
153 | e5a246df | Michael Hanselmann | |
154 | 9189c902 | Michael Hanselmann | ``fields`` (list of :ref:`field definitions <field-def>`) |
155 | e5a246df | Michael Hanselmann | In-order list of a :ref:`field definition <field-def>` for each |
156 | e5a246df | Michael Hanselmann | requested field, unknown fields are returned with the kind |
157 | e5a246df | Michael Hanselmann | ``unknown``. Length must be equal to number of requested fields. |
158 | 9189c902 | Michael Hanselmann | ``data`` (list of lists of tuples) |
159 | 9189c902 | Michael Hanselmann | List of lists, one list for each item found. Each item's list must |
160 | 9189c902 | Michael Hanselmann | have one entry for each field listed in ``fields`` (meaning their |
161 | 9189c902 | Michael Hanselmann | length is equal). Each field entry is a tuple of ``(status, value)``. |
162 | 9189c902 | Michael Hanselmann | ``status`` must be one of the following values: |
163 | e5a246df | Michael Hanselmann | |
164 | e5a246df | Michael Hanselmann | Normal (numeric 0) |
165 | e5a246df | Michael Hanselmann | Value is available and matches the kind in the :ref:`field |
166 | e5a246df | Michael Hanselmann | definition <field-def>`. |
167 | 9189c902 | Michael Hanselmann | Unknown field (numeric 1) |
168 | 9189c902 | Michael Hanselmann | Field for this column is not known. Value must be ``None``. |
169 | 9189c902 | Michael Hanselmann | No data (numeric 2) |
170 | e5a246df | Michael Hanselmann | Exact meaning depends on query, e.g. node is unreachable or marked |
171 | e5a246df | Michael Hanselmann | offline. Value must be ``None``. |
172 | 9189c902 | Michael Hanselmann | Value unavailable for item (numeric 3) |
173 | 9189c902 | Michael Hanselmann | Used if, for example, NIC 3 is requested for an instance with only |
174 | 9189c902 | Michael Hanselmann | one network interface. Value must be ``None``. |
175 | a6070ef7 | Michael Hanselmann | Resource offline (numeric 4) |
176 | a6070ef7 | Michael Hanselmann | Used if resource is marked offline. Value must be ``None``. |
177 | e5a246df | Michael Hanselmann | |
178 | 9189c902 | Michael Hanselmann | Example response after requesting the fields ``name``, ``mfree``, |
179 | 9189c902 | Michael Hanselmann | ``xyz``, ``mtotal``, ``nic0.ip``, ``nic1.ip`` and ``nic2.ip``:: |
180 | e5a246df | Michael Hanselmann | |
181 | e5a246df | Michael Hanselmann | { |
182 | e5a246df | Michael Hanselmann | "fields": [ |
183 | e5a246df | Michael Hanselmann | { "name": "name", "title": "Name", "kind": "text", }, |
184 | e5a246df | Michael Hanselmann | { "name": "mfree", "title": "MemFree", "kind": "unit", }, |
185 | e5a246df | Michael Hanselmann | # Unknown field |
186 | e5a246df | Michael Hanselmann | { "name": "xyz", "title": None, "kind": "unknown", }, |
187 | e5a246df | Michael Hanselmann | { "name": "mtotal", "title": "MemTotal", "kind": "unit", }, |
188 | 9189c902 | Michael Hanselmann | { "name": "nic0.ip", "title": "Nic.IP/0", "kind": "text", }, |
189 | 9189c902 | Michael Hanselmann | { "name": "nic1.ip", "title": "Nic.IP/1", "kind": "text", }, |
190 | 9189c902 | Michael Hanselmann | { "name": "nic2.ip", "title": "Nic.IP/2", "kind": "text", }, |
191 | e5a246df | Michael Hanselmann | ], |
192 | e5a246df | Michael Hanselmann | |
193 | e5a246df | Michael Hanselmann | "data": [ |
194 | 9189c902 | Michael Hanselmann | [(0, "node1"), (0, 128), (1, None), (0, 4096), |
195 | 9189c902 | Michael Hanselmann | (0, "192.0.2.1"), (0, "192.0.2.2"), (3, None)], |
196 | 9189c902 | Michael Hanselmann | [(0, "node2"), (0, 96), (1, None), (0, 5000), |
197 | 9189c902 | Michael Hanselmann | (0, "192.0.2.21"), (0, "192.0.2.39"), (3, "192.0.2.90")], |
198 | 9189c902 | Michael Hanselmann | # Node not available, can't get "mfree" or "mtotal" |
199 | 9189c902 | Michael Hanselmann | [(0, "node3"), (2, None), (1, None), (2, None), |
200 | 9189c902 | Michael Hanselmann | (0, "192.0.2.30"), (3, None), (3, None)], |
201 | e5a246df | Michael Hanselmann | ], |
202 | e5a246df | Michael Hanselmann | } |
203 | e5a246df | Michael Hanselmann | |
204 | 9189c902 | Michael Hanselmann | .. _fields-query: |
205 | 9189c902 | Michael Hanselmann | |
206 | 9189c902 | Michael Hanselmann | Fields query |
207 | 9189c902 | Michael Hanselmann | ++++++++++++ |
208 | 9189c902 | Michael Hanselmann | |
209 | 9189c902 | Michael Hanselmann | .. _fields-query-request: |
210 | 9189c902 | Michael Hanselmann | |
211 | 9189c902 | Michael Hanselmann | Request |
212 | 9189c902 | Michael Hanselmann | ^^^^^^^ |
213 | 9189c902 | Michael Hanselmann | |
214 | 9189c902 | Michael Hanselmann | The request is a dictionary with the following entries: |
215 | 9189c902 | Michael Hanselmann | |
216 | 46aae796 | Michael Hanselmann | ``what`` (string, required) |
217 | 9189c902 | Michael Hanselmann | An :ref:`item type <item-types>`. |
218 | 9189c902 | Michael Hanselmann | ``fields`` (list of strings, optional) |
219 | 9189c902 | Michael Hanselmann | List of names of fields to return. If not set, all fields are |
220 | 9189c902 | Michael Hanselmann | returned. Example:: |
221 | 9189c902 | Michael Hanselmann | |
222 | 9189c902 | Michael Hanselmann | ["name", "mem", "nic0.ip", "disk0.size", "disk1.size"] |
223 | e5a246df | Michael Hanselmann | |
224 | 9189c902 | Michael Hanselmann | .. _fields-query-response: |
225 | 9189c902 | Michael Hanselmann | |
226 | 9189c902 | Michael Hanselmann | Response |
227 | 9189c902 | Michael Hanselmann | ^^^^^^^^ |
228 | e5a246df | Michael Hanselmann | |
229 | e5a246df | Michael Hanselmann | The result is a dictionary with the following entries: |
230 | e5a246df | Michael Hanselmann | |
231 | 9189c902 | Michael Hanselmann | ``fields`` (list of :ref:`field definitions <field-def>`) |
232 | 9189c902 | Michael Hanselmann | List of a :ref:`field definition <field-def>` for each field. If |
233 | 9189c902 | Michael Hanselmann | ``fields`` was set in the request and contained an unknown field, it |
234 | 9189c902 | Michael Hanselmann | is returned as type ``unknown``. |
235 | e5a246df | Michael Hanselmann | |
236 | e5a246df | Michael Hanselmann | Example:: |
237 | e5a246df | Michael Hanselmann | |
238 | e5a246df | Michael Hanselmann | { |
239 | e5a246df | Michael Hanselmann | "fields": [ |
240 | e5a246df | Michael Hanselmann | { "name": "name", "title": "Name", "kind": "text", }, |
241 | e5a246df | Michael Hanselmann | { "name": "mfree", "title": "MemFree", "kind": "unit", }, |
242 | e5a246df | Michael Hanselmann | { "name": "mtotal", "title": "MemTotal", "kind": "unit", }, |
243 | 9189c902 | Michael Hanselmann | { "name": "nic0.ip", "title": "Nic.IP/0", "kind": "text", }, |
244 | 9189c902 | Michael Hanselmann | { "name": "nic1.ip", "title": "Nic.IP/1", "kind": "text", }, |
245 | 9189c902 | Michael Hanselmann | { "name": "nic2.ip", "title": "Nic.IP/2", "kind": "text", }, |
246 | 9189c902 | Michael Hanselmann | { "name": "nic3.ip", "title": "Nic.IP/3", "kind": "text", }, |
247 | 9189c902 | Michael Hanselmann | # … |
248 | 9189c902 | Michael Hanselmann | { "name": "disk0.size", "title": "Disk.Size/0", "kind": "unit", }, |
249 | 9189c902 | Michael Hanselmann | { "name": "disk1.size", "title": "Disk.Size/1", "kind": "unit", }, |
250 | 9189c902 | Michael Hanselmann | { "name": "disk2.size", "title": "Disk.Size/2", "kind": "unit", }, |
251 | 9189c902 | Michael Hanselmann | { "name": "disk3.size", "title": "Disk.Size/3", "kind": "unit", }, |
252 | 9189c902 | Michael Hanselmann | # … |
253 | e5a246df | Michael Hanselmann | ] |
254 | e5a246df | Michael Hanselmann | } |
255 | e5a246df | Michael Hanselmann | |
256 | e5a246df | Michael Hanselmann | .. _field-def: |
257 | e5a246df | Michael Hanselmann | |
258 | e5a246df | Michael Hanselmann | Field definition |
259 | e5a246df | Michael Hanselmann | ++++++++++++++++ |
260 | e5a246df | Michael Hanselmann | |
261 | e5a246df | Michael Hanselmann | A field definition is a dictionary with the following entries: |
262 | e5a246df | Michael Hanselmann | |
263 | 9189c902 | Michael Hanselmann | ``name`` (string) |
264 | 9189c902 | Michael Hanselmann | Field name. Must only contain characters matching ``[a-z0-9/._]``. |
265 | 9189c902 | Michael Hanselmann | ``title`` (string) |
266 | e5a246df | Michael Hanselmann | Human-readable title to use in output. Must not contain whitespace. |
267 | 9189c902 | Michael Hanselmann | ``kind`` (string) |
268 | e5a246df | Michael Hanselmann | Field type, one of the following: |
269 | e5a246df | Michael Hanselmann | |
270 | e5a246df | Michael Hanselmann | ``unknown`` |
271 | 9189c902 | Michael Hanselmann | Unknown field |
272 | e5a246df | Michael Hanselmann | ``text`` |
273 | e5a246df | Michael Hanselmann | String |
274 | e5a246df | Michael Hanselmann | ``bool`` |
275 | e5a246df | Michael Hanselmann | Boolean, true/false |
276 | e5a246df | Michael Hanselmann | ``number`` |
277 | e5a246df | Michael Hanselmann | Numeric |
278 | e5a246df | Michael Hanselmann | ``unit`` |
279 | e5a246df | Michael Hanselmann | Numeric, in megabytes |
280 | 9189c902 | Michael Hanselmann | ``timestamp`` |
281 | 9189c902 | Michael Hanselmann | Unix timestamp in seconds since the epoch |
282 | e5a246df | Michael Hanselmann | ``other`` |
283 | e5a246df | Michael Hanselmann | Free-form type, depending on query |
284 | e5a246df | Michael Hanselmann | |
285 | e5a246df | Michael Hanselmann | More types can be added in the future, so clients should default to |
286 | e5a246df | Michael Hanselmann | formatting any unknown types the same way as "other", which should be |
287 | e5a246df | Michael Hanselmann | a string representation in most cases. |
288 | e5a246df | Michael Hanselmann | |
289 | 1ae17369 | Michael Hanselmann | ``doc`` (string) |
290 | 1ae17369 | Michael Hanselmann | Human-readable description. Must start with uppercase character and |
291 | 1ae17369 | Michael Hanselmann | must not end with punctuation or contain newlines. |
292 | 1ae17369 | Michael Hanselmann | |
293 | 9189c902 | Michael Hanselmann | .. TODO: Investigate whether there are fields with floating point |
294 | 9189c902 | Michael Hanselmann | .. numbers |
295 | 9189c902 | Michael Hanselmann | |
296 | e5a246df | Michael Hanselmann | Example 1 (item name):: |
297 | e5a246df | Michael Hanselmann | |
298 | e5a246df | Michael Hanselmann | { |
299 | e5a246df | Michael Hanselmann | "name": "name", |
300 | e5a246df | Michael Hanselmann | "title": "Name", |
301 | e5a246df | Michael Hanselmann | "kind": "text", |
302 | e5a246df | Michael Hanselmann | } |
303 | e5a246df | Michael Hanselmann | |
304 | e5a246df | Michael Hanselmann | Example 2 (free memory):: |
305 | e5a246df | Michael Hanselmann | |
306 | e5a246df | Michael Hanselmann | { |
307 | e5a246df | Michael Hanselmann | "name": "mfree", |
308 | e5a246df | Michael Hanselmann | "title": "MemFree", |
309 | e5a246df | Michael Hanselmann | "kind": "unit", |
310 | e5a246df | Michael Hanselmann | } |
311 | e5a246df | Michael Hanselmann | |
312 | e5a246df | Michael Hanselmann | Example 3 (list of primary instances):: |
313 | e5a246df | Michael Hanselmann | |
314 | e5a246df | Michael Hanselmann | { |
315 | e5a246df | Michael Hanselmann | "name": "pinst", |
316 | e5a246df | Michael Hanselmann | "title": "PrimaryInstances", |
317 | e5a246df | Michael Hanselmann | "kind": "other", |
318 | e5a246df | Michael Hanselmann | } |
319 | e5a246df | Michael Hanselmann | |
320 | e5a246df | Michael Hanselmann | .. _old-result-format: |
321 | e5a246df | Michael Hanselmann | |
322 | e5a246df | Michael Hanselmann | Old result format |
323 | e5a246df | Michael Hanselmann | +++++++++++++++++ |
324 | e5a246df | Michael Hanselmann | |
325 | e5a246df | Michael Hanselmann | To limit the amount of code necessary, the :ref:`new result format |
326 | 9189c902 | Michael Hanselmann | <data-query-response>` will be converted for clients calling the old |
327 | 9189c902 | Michael Hanselmann | methods. Unavailable values are set to ``None``. If unknown fields were |
328 | 9189c902 | Michael Hanselmann | requested, the whole query fails as the client expects exactly the |
329 | 9189c902 | Michael Hanselmann | fields it requested. |
330 | 9189c902 | Michael Hanselmann | |
331 | a1e43376 | Michael Hanselmann | .. _query2-luxi: |
332 | e5a246df | Michael Hanselmann | |
333 | e5a246df | Michael Hanselmann | LUXI |
334 | e5a246df | Michael Hanselmann | ++++ |
335 | e5a246df | Michael Hanselmann | |
336 | e5a246df | Michael Hanselmann | Currently query calls take a number of parameters, e.g. names, fields |
337 | e5a246df | Michael Hanselmann | and whether to use locking. These will continue to work and return the |
338 | 9189c902 | Michael Hanselmann | :ref:`old result format <old-result-format>`. Only clients using the |
339 | 9189c902 | Michael Hanselmann | new calls described below will be able to make use of new features such |
340 | 9189c902 | Michael Hanselmann | as filters. Two new calls are introduced: |
341 | 9189c902 | Michael Hanselmann | |
342 | 9189c902 | Michael Hanselmann | ``Query`` |
343 | 9189c902 | Michael Hanselmann | Execute a query on items, optionally filtered. Takes a single |
344 | 9189c902 | Michael Hanselmann | parameter, a :ref:`query object <data-query-request>` encoded as a |
345 | 9189c902 | Michael Hanselmann | dictionary and returns a :ref:`data query response |
346 | 2656091a | Michael Hanselmann | <data-query-response>`. |
347 | 9189c902 | Michael Hanselmann | ``QueryFields`` |
348 | 9189c902 | Michael Hanselmann | Return list of supported fields as :ref:`field definitions |
349 | 9189c902 | Michael Hanselmann | <field-def>`. Takes a single parameter, a :ref:`fields query object |
350 | 9189c902 | Michael Hanselmann | <fields-query-request>` encoded as a dictionary and returns a |
351 | 9189c902 | Michael Hanselmann | :ref:`fields query response <fields-query-response>`. |
352 | 9189c902 | Michael Hanselmann | |
353 | e5a246df | Michael Hanselmann | |
354 | e5a246df | Michael Hanselmann | Python |
355 | e5a246df | Michael Hanselmann | ++++++ |
356 | e5a246df | Michael Hanselmann | |
357 | e5a246df | Michael Hanselmann | The LUXI API is more or less mapped directly into Python. In addition to |
358 | e5a246df | Michael Hanselmann | the existing stub functions new ones will be added for the new query |
359 | e5a246df | Michael Hanselmann | requests. |
360 | e5a246df | Michael Hanselmann | |
361 | e5a246df | Michael Hanselmann | RAPI |
362 | e5a246df | Michael Hanselmann | ++++ |
363 | e5a246df | Michael Hanselmann | |
364 | e5a246df | Michael Hanselmann | The RAPI interface already returns dictionaries for each item, but to |
365 | e5a246df | Michael Hanselmann | not break compatibility no changes should be made to the structure (e.g. |
366 | e5a246df | Michael Hanselmann | to include field definitions). The proposal here is to add a new |
367 | e5a246df | Michael Hanselmann | parameter to allow clients to execute the requests described in this |
368 | e5a246df | Michael Hanselmann | proposal directly and to receive the unmodified result. The new formats |
369 | e5a246df | Michael Hanselmann | are a lot more verbose, flexible and extensible. |
370 | e5a246df | Michael Hanselmann | |
371 | 9189c902 | Michael Hanselmann | .. _cli-programs: |
372 | 9189c902 | Michael Hanselmann | |
373 | 9189c902 | Michael Hanselmann | CLI programs |
374 | 9189c902 | Michael Hanselmann | ++++++++++++ |
375 | 9189c902 | Michael Hanselmann | |
376 | 9189c902 | Michael Hanselmann | Command line programs might have difficulties to display the verbose |
377 | 9189c902 | Michael Hanselmann | status data to the user. There are several options: |
378 | 9189c902 | Michael Hanselmann | |
379 | 9189c902 | Michael Hanselmann | - Use colours to indicate missing values |
380 | 9189c902 | Michael Hanselmann | - Display status as value in parentheses, e.g. "(unavailable)" |
381 | 9189c902 | Michael Hanselmann | - Hide unknown columns from the result table and print a warning |
382 | 9189c902 | Michael Hanselmann | - Exit with non-zero code to indicate failures and/or missing data |
383 | 9189c902 | Michael Hanselmann | |
384 | 9189c902 | Michael Hanselmann | Some are better for interactive usage, some better for use by other |
385 | 9189c902 | Michael Hanselmann | programs. It is expected that a combination will be used. The column |
386 | 9189c902 | Michael Hanselmann | separator (``--separator=…``) can be used to differentiate between |
387 | 9189c902 | Michael Hanselmann | interactive and programmatic usage. |
388 | 9189c902 | Michael Hanselmann | |
389 | e5a246df | Michael Hanselmann | |
390 | e5a246df | Michael Hanselmann | Other discussed solutions |
391 | e5a246df | Michael Hanselmann | ------------------------- |
392 | e5a246df | Michael Hanselmann | |
393 | e5a246df | Michael Hanselmann | Another solution discussed was to add an additional column for each |
394 | e5a246df | Michael Hanselmann | non-static field containing the status. Clients interested in the status |
395 | e5a246df | Michael Hanselmann | could explicitely query for it. |
396 | e5a246df | Michael Hanselmann | |
397 | e5a246df | Michael Hanselmann | .. vim: set textwidth=72 : |
398 | e5a246df | Michael Hanselmann | .. Local Variables: |
399 | e5a246df | Michael Hanselmann | .. mode: rst |
400 | e5a246df | Michael Hanselmann | .. fill-column: 72 |
401 | e5a246df | Michael Hanselmann | .. End: |