Code

c0cecba8dfe55cbaafe839139c6ecd19510fcadf
[sysdb.git] / doc / sysdbql.7.txt
1 sysdbql(7)
2 ==========
3 :doctype: manpage
5 NAME
6 ----
7 sysdbql - the SysDB query language (SysQL)
9 SYNOPSIS
10 --------
12   LIST hosts;
13   LIST services;
15   FETCH host 'some.host.name';
17   LOOKUP hosts MATCHING attribute['architecture'] = 'amd64'
18                    AND 'backend::collectd::unixsock' in backend
19                FILTER age < 5 * interval;
21   STORE host attribute 'some.host.name'.'key' 123.45
22                        LAST UPDATE 2001-02-03 04:05:06;
24 DESCRIPTION
25 -----------
26 include::sysdb-description.txt[]
28 The SysDB query language (SysQL) is a human-readable format for describing a
29 request to retrieve data from a SysDB daemon. It is very remotely similar to
30 the Standard Query Language (SQL) supported by relational database management
31 systems (RDBMS) but specialized for SysDB's use-case.
33 Besides querying data, SysQL may also be used to store or update objects in
34 SysDB.
36 QUERY COMMANDS
37 --------------
38 Each command is terminated by a semicolon. The following commands are
39 available to retrieve information from SysDB:
41 *LIST* hosts|services|metrics [*FILTER* '<filter_condition>']::
42 Retrieve a sorted (by name) list of all objects of the specified type
43 currently stored in SysDB. The return value is a list of objects including
44 their names, the timestamp of the last update and an approximation of the
45 interval with which the host was updated. When listing services or metrics,
46 the respective objects will be grouped by host. If a filter condition is
47 specified, only objects matching that filter will be included in the reply.
48 See the section "FILTER clause" for more details about how to specify the
49 search and filter conditions.
51 *FETCH* host '<hostname>' [*FILTER* '<filter_condition>']::
52 *FETCH* service|metric '<hostname>'.'<name>' [*FILTER* '<filter_condition>']::
53 Retrieve detailed information about the specified object. The return value
54 includes the full object including all of its attributes and child objects.
55 If the named object does not exist, an error is returned. If a filter
56 condition is specified, only objects matching that filter will be included in
57 the reply. See the section "FILTER clause" for more details about how to
58 specify the search and filter conditions.
60 *LOOKUP* hosts|services|metrics [*MATCHING* '<search_condition>'] [*FILTER* '<filter_condition>']::
61 Retrieve detailed information about all objects matching the specified search
62 condition. The return value is a list of detailed information for each
63 matching object providing the same details as returned by the *FETCH* command.
64 If no object matches the search criteria, it's not considered an error.
65 Instead, an empty list is returned. If a filter condition is specified, only
66 objects matching that filter will be included in the reply. See the sections
67 "MATCHING clause" and "FILTER clause" for more details about how to specify
68 the search and filter conditions.
70 *TIMESERIES* '<hostname>'.'<metric>' [START '<datetime>'] [END '<datetime>']::
71 Retrieve a time-series for the specified host's metric. The data is retrieved
72 from a backend data-store based on information provided by the respective
73 query plugin. The return value includes the actual start and end time of the
74 time-series and one or multiple sequences of time-stamp / value pairs. If the
75 metric does not exist or if the backend data-store is not supported, an error
76 is returned.
78 MATCHING clause
79 ~~~~~~~~~~~~~~~
80 The *MATCHING* clause in a query specifies a boolean expression which is used
81 to match objects based on their fields, attributes, or child objects. Any
82 object for which the expression evaluates to true will be included in the
83 result set according to the rules set by the actual query.
85 FILTER clause
86 ~~~~~~~~~~~~~
87 The *FILTER* clause in a query specifies a boolean expression which is used to
88 filter objects included in the query's response. The filter is applied to
89 hosts, services, and attributes alike and, thus, will usually be based on the
90 core properties of the stored objects. The basic syntax for filter clauses is
91 the same as for matching clauses.
93 Expressions
94 ~~~~~~~~~~~
95 Expressions form the basic building block for all queries. Boolean expressions
96 select objects based on the values of arithmetic expressions which operate on
97 object specific values (fields) or constant values.
99 Boolean expressions may use the following operators:
101 '<expression>' *AND* '<expression>'::
102 '<expression>' *OR* '<expression>'::
103         Evaluates to the logical AND or logical OR of the specified
104         subexpressions.
106 *NOT* '<expression>'::
107         Invert the boolean result of the specified subexpression.
109 '<expression>' '<cmp>' '<expression>'::
110         Compare the values of two expressions using any compare operator (see
111         below). Evaluates to either true or false. Comparing any value with a NULL
112         value always evaluates to false. The data types of the two values have to
113         match except for a few cases as noted in the documentation of the
114         respective operator.
116 *ANY* '<iterable>' '<cmp>' '<expression>'::
117         Compares each element of an iterable using any compare operator. Evaluates
118         to true if any of the elements matches or false if no such elements exist.
119         Otherwise, the same rules as for other comparison operations apply.
120         Attributes, a host's services and metrics, and arrays are iterables.
122 *ALL* '<iterable>' '<cmp>' '<expression>'::
123         *ALL* is similar to the *ANY* operator but matches if all elements match
124         or if no elements exist.
126 '<expression>' *IS NULL*::
127 '<expression>' *IS NOT NULL*::
128         Check whether an expression evaluates to a NULL value (or not). An
129         expression evaluates to NULL if the queried object does not exist (e.g.,
130         when accessing an attribute value).
132 '<expression>' *IN* '<expression>'::
133         Checks whether the value of the first expression is included in the value
134         of the second expression which has to be an array value (e.g., *backend*
135         field). If the second value is not an array or if the type of the first
136         value does not match the array's element type, the expression always
137         evaluates to false. The first value may also be an array. In this case,
138         the expression evaluates to true if all elements of that array are
139         included in the second array where order does not matter.
141 Parentheses ('()') may be used around subexpressions to group them and enforce
142 precedence.
144 The following fields may be queried:
146 *name*::
147         The canonicalized name of the object. The type of this field is string.
149 *last_update*::
150         The timestamp of the last update of the object. This value is based on
151         information provided by the queried backend if possible. The type of this
152         field is date-time.
154 *age*::
155         The amount of time since the last update of the object. The type of this
156         field is date-time.
158 *interval*::
159         The interval with which the object gets updated. This value is determined
160         automatically based on a moving average determined from the update
161         timestamps of an object. It depends on the update timestamps as provided
162         by the backend (if available) and SysDB's query interval. The type of this
163         field is date-time.
165 *backend*::
166         The name of the backend (plugin) providing the data. The type of this
167         field is array of strings.
169 *attribute[*'<name>'*]*::
170         The value of the object's named attribute. If an attribute of the
171         specified name does not exist, each comparison is treated as if the value
172         does not match. See the documentation for the *IS NULL* and *IS NOT NULL*
173         operators for ways to check if an attribute exists. The value of an
174         attribute may be of any of the supported data types. There is no schema
175         specifying each attribute's data type which means that the parser cannot
176         do any type checks. Thus, in case the data types mismatch when comparing
177         an attribute value with some other value, the two values will be cast to
178         strings before comparing them.
180 The following logical operators are supported by SysDB. Unless otherwise
181 noted, the data types of the left hand and right hand side have to match.
183 *=*::
184         Checks two values for equality.
186 *!=*::
187         Checks two values for inequality.
189 *=~*::
190         Checks if a value matches a regular expression. The regex pattern has to
191         be specified as a string but the value may be of any type and will be cast
192         to a string before evaluating the regular expression. SysDB uses POSIX
193         extended regular expressions.
195 *!~*::
196         Checks if a value does not match a regular expression. The same rules
197         apply as for the *=~* operator.
199 *<*, *\<=*, *>=*, *>*::
200         Checks whether a value compares less than, less than or equal to, greater
201         than or equal, or greater than some other value.
203 The following arithmetic operators are supported by SysDB. Unless otherwise 
204 noted, the data types of the left hand and right hand side have to match.
206 *+*::
207 *-*::
208         Add or subtract two numeric or date-time values.
210 ***::
211 */*::
212         Multiple or divide two numeric or data-time values. A date-time value may
213         be multiplied with a numeric value or divided by a numeric value. The
214         result will then be a date-time value.
216 *%*::
217         Modulo operator (remainder of division). Same rules for data types apply
218         as for division.
220 *||*::
221         Concatenate string or array values.
223 STORING DATA
224 ------------
225 The *STORE* command may be used to store or update an object in SysDB. Each
226 command is terminated by a semicolon. The following variants are available for
227 storing the different data types:
229 *STORE* host '<name>' [*LAST UPDATE* '<datetime>']::
230 *STORE* service|metric '<hostname>'.'<name>' [*LAST UPDATE* '<datetime>']::
231 *STORE* host attribute '<hostname>'.'<key>' '<value>' [*LAST UPDATE* '<datetime>']::
232 *STORE* service|metric attribute '<hostname>'.'<name>'.'<key>' '<value>' [*LAST UPDATE* '<datetime>']::
233         Store an object of the specified type and name. For services, metrics, and
234         attributes, the name is prepended with the parent object name separated by
235         a dot ('.'). Optionally, the time-stamp of the object's last update may be
236         provided as well. If omitted, the current time on the server will be used
237         instead.
239 *STORE* metric '<hostname>'.'<name>' STORE '<type>' '<id>' [*LAST UPDATE* '<datetime>']::
240         Store a metric and provide information about the metric store associated
241         with it. A metric store describes how to access a metric's data and can be
242         used to retrieve time-series information associated with the metric. See
243         the manpage:sysdb[7] manpage for details.
245         Note that the metric store information will be forwarded to the server
246         unmodified. That is, they need to be specified in a way such that the
247         server can make sense out of them. Else, retrieval of time-series data
248         will fail.
250 DATA TYPES
251 ----------
252 The SysDB query language natively supports various data-types. Constants of
253 all types may be used in any place where a value is expected.
255 *String constants*::
256         A string constant is an arbitrary sequence of characters enclosed in
257         single quotes ('''). Single quotes may be included in a string constant by
258         specifying two adjacent single quotes.
260 *Integer constants*::
261         An integer constant may be specified either as a sequence of digits or in
262         scientific notation written in the form "'a' E 'b'" (without spaces) where
263         'a' and 'b' are integers. A leading plus or minus sign specifies the sign
264         of the constant.
266 *Floating-point constants*::
267         A floating-point constant is a sequence of digits containing a decimal
268         point. Digits before or after the decimal point (but not both) are
269         optional. Floating-point constants may also be specified in scientific
270         notation by appending the letter "E" and a positive or negative integer
271         exponent. A leading plus or minus sign specifies the sign of the constant.
273 *Date and time constants*::
274         A date constant may be specified as 'YYYY-MM-DD' and time constants may be
275         specified as 'HH:MM:SS.nnnnnnnnn' where seconds and nanoseconds are
276         optional.
278 *Interval constants*::
279         An interval may be specified by one or multiple quantity and unit pairs.
280         The quantity may be any integer constant and the unit may be any of the
281         following: *Y* (years), *M* (months), *D* (days), *h* (hours), *m*
282         (minutes), *s* (seconds), *ms* (milliseconds), *us* (microseconds), or
283         *ns* (nanoseconds). Note that years and months are approximations.
285 *Array constants*::
286         An array stores of one or more values of the same type. It may be
287         specified as a comma-separated list of constant values enclosed in square
288         brackets ('[<elem1>,<elem2>,...]'). For each value, the same rules apply
289         as for a regular constant value of that type.
291 RESPONSE FORMAT
292 ---------------
293 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
294 used in all query replies from the server. http://www.ietf.org/rfc/rfc4627.txt
296 For all other commands, the reply will be a message string.
298 EXAMPLES
299 --------
300 The following examples illustrate the use of the commands and what their
301 replies look like. The replies are pretty-printed to more easily follow them.
303   LIST hosts;
304   [{
305       "name": "host1.example.com",
306       "last_update": "2001-02-03 04:05:06 +0700",
307       "update_interval": "5m4s",
308       "backend": ['backend::mk-livestatus']
309     },{
310       "name": "host2.example.com",
311       "last_update": "2001-02-03 04:05:06 +0700",
312       "update_interval": "10s",
313       "backend": ['backend::mk-livestatus','backend::collectd::unixsock']
314     }]
316   FETCH host 'host1.example.com';
317   {
318       "name": "host1.example.com",
319       "last_update": "2001-02-03 04:05:06 +0700",
320       "update_interval": "5m4s",
321       "backend": ['backend::mk-livestatus'],
322       "attributes": [{
323           "name": "architecture",
324           "value": "amd64",
325           "last_update": "2001-02-03 04:05:06 +0700",
326           "update_interval": "5m4s",
327           "backend": ['backend::mk-livestatus']
328         },{
329           ...
330         }],
331       "services": [{
332           "name": "some service",
333           "last_update": "2001-02-03 04:05:06 +0700",
334           "update_interval": "5m4s",
335           "backend": ['backend::mk-livestatus']
336         },{
337           ...
338         }]}
340   LOOKUP hosts MATCHING attribute['architecture'] = 'amd64';
341   [{
342       "name": "host1.example.com",
343       "last_update": "2001-02-03 04:05:06 +0700",
344       "update_interval": "5m4s",
345       "backend": ['backend::mk-livestatus'],
346       "attributes": [{
347           "name": "architecture",
348           "value": "amd64",
349           "last_update": "2001-02-03 04:05:06 +0700",
350           "update_interval": "5m4s",
351           "backend": ['backend::mk-livestatus']
352         },{
353           ...
354         }],
355       "services": [{
356           "name": "some service",
357           "last_update": "2001-02-03 04:05:06 +0700",
358           "update_interval": "5m4s",
359           "backend": ['backend::mk-livestatus']
360         },{
361           ...
362     }]},{
363       ...
364     }]
366 SEE ALSO
367 --------
368 manpage:sysdb[1], manpage:sysdb[7]
370 RFC 4627 (JSON): http://www.ietf.org/rfc/rfc4627.txt
372 The SysDB homepage: https://sysdb.io/
374 AUTHOR
375 ------
376 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
378 COPYRIGHT
379 ---------
380 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
382 This is free software under the terms of the BSD license, see the source for
383 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
384 FITNESS FOR A PARTICULAR PURPOSE.
386 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :