doc/sysdbql.7.txt

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